shlink/docs/swagger/paths/v1_short-urls.json

{
    "get": {
        "operationId": "listShortUrls",
        "tags": [
            "Short URLs"
        ],
        "summary": "List short URLs",
        "description": "Returns the list of short URLs.<br><br>**Important note**: Before shlink v1.13, this endpoint used to use the `/short-codes` path instead of `/short-urls`. Both of them will keep working, while the first one is considered deprecated.",
        "parameters": [
            {
                "name": "page",
                "in": "query",
                "description": "The page to be displayed. Defaults to 1",
                "required": false,
                "schema": {
                    "type": "integer"
                }
            },
            {
                "name": "searchTerm",
                "in": "query",
                "description": "A query used to filter results by searching for it on the longUrl and shortCode fields. (Since v1.3.0)",
                "required": false,
                "schema": {
                    "type": "string"
                }
            },
            {
                "name": "tags[]",
                "in": "query",
                "description": "A list of tags used to filter the resultset. Only short URLs tagged with at least one of the provided tags will be returned. (Since v1.3.0)",
                "required": false,
                "schema": {
                    "type": "array",
                    "items": {
                        "type": "string"
                    }
                }
            },
            {
                "name": "orderBy",
                "in": "query",
                "description": "The field from which you want to order the result. (Since v1.3.0)",
                "required": false,
                "schema": {
                    "type": "string",
                    "enum": [
                        "longUrl",
                        "shortCode",
                        "dateCreated",
                        "visits"
                    ]
                }
            }
        ],
        "security": [
            {
                "Bearer": []
            }
        ],
        "responses": {
            "200": {
                "description": "The list of short URLs",
                "content": {
                    "application/json": {
                        "schema": {
                            "type": "object",
                            "properties": {
                                "shortUrls": {
                                    "type": "object",
                                    "properties": {
                                        "data": {
                                            "type": "array",
                                            "items": {
                                                "$ref": "../definitions/ShortUrl.json"
                                            }
                                        },
                                        "pagination": {
                                            "$ref": "../definitions/Pagination.json"
                                        }
                                    }
                                }
                            }
                        }
                    }
                },
                "examples": {
                    "application/json": {
                        "shortUrls": {
                            "data": [
                                {
                                    "shortCode": "12C18",
                                    "shortUrl": "https://doma.in/12C18",
                                    "longUrl": "https://store.steampowered.com",
                                    "dateCreated": "2016-08-21T20:34:16+02:00",
                                    "visitsCount": 328,
                                    "tags": [
                                        "games",
                                        "tech"
                                    ]
                                },
                                {
                                    "shortCode": "12Kb3",
                                    "shortUrl": "https://doma.in/12Kb3",
                                    "longUrl": "https://shlink.io",
                                    "dateCreated": "2016-05-01T20:34:16+02:00",
                                    "visitsCount": 1029,
                                    "tags": [
                                        "shlink"
                                    ]
                                },
                                {
                                    "shortCode": "123bA",
                                    "shortUrl": "https://doma.in/123bA",
                                    "longUrl": "https://www.google.com",
                                    "dateCreated": "2015-10-01T20:34:16+02:00",
                                    "visitsCount": 25,
                                    "tags": []
                                }
                            ],
                            "pagination": {
                                "currentPage": 5,
                                "pagesCount": 12,
                                "itemsPerPage": 10,
                                "itemsInCurrentPage": 10,
                                "totalItems": 115
                            }
                        }
                    }
                }
            },
            "500": {
                "description": "Unexpected error.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "../definitions/Error.json"
                        }
                    }
                }
            }
        }
    },

    "post": {
        "operationId": "createShortUrl",
        "tags": [
            "Short URLs"
        ],
        "summary": "Create short URL",
        "description": "Creates a new short URL.<br><br>**Important note**: Before shlink v1.13, this endpoint used to use the `/short-codes` path instead of `/short-urls`. Both of them will keep working, while the first one is considered deprecated.",
        "security": [
            {
                "Bearer": []
            }
        ],
        "requestBody": {
            "description": "Request body.",
            "required": true,
            "content": {
                "application/json": {
                    "schema": {
                        "type": "object",
                        "required": [
                            "longUrl"
                        ],
                        "properties": {
                            "longUrl": {
                                "description": "The URL to parse",
                                "type": "string"
                            },
                            "tags": {
                                "description": "The URL to parse",
                                "type": "array",
                                "items": {
                                    "type": "string"
                                }
                            },
                            "validSince": {
                                "description": "The date (in ISO-8601 format) from which this short code will be valid",
                                "type": "string"
                            },
                            "validUntil": {
                                "description": "The date (in ISO-8601 format) until which this short code will be valid",
                                "type": "string"
                            },
                            "customSlug": {
                                "description": "A unique custom slug to be used instead of the generated short code",
                                "type": "string"
                            },
                            "maxVisits": {
                                "description": "The maximum number of allowed visits for this short code",
                                "type": "number"
                            }
                        }
                    }
                }
            }
        },
        "responses": {
            "200": {
                "description": "The result of parsing the long URL",
                "content": {
                    "application/json": {
                        "schema": {
                            "type": "object",
                            "properties": {
                                "longUrl": {
                                    "type": "string",
                                    "description": "The original long URL that has been parsed"
                                },
                                "shortUrl": {
                                    "type": "string",
                                    "description": "The generated short URL"
                                },
                                "shortCode": {
                                    "type": "string",
                                    "description": "the short code that is being used in the short URL"
                                }
                            }
                        }
                    }
                }
            },
            "400": {
                "description": "The long URL was not provided or is invalid.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "../definitions/Error.json"
                        }
                    }
                }
            },
            "500": {
                "description": "Unexpected error.",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "../definitions/Error.json"
                        }
                    }
                }
            }
        }
    }
}