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": [
            {
                "$ref": "../parameters/version.json"
            },
            {
                "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": [
            {
                "ApiKey": []
            },
            {
                "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"
                                    ],
                                    "meta": {
                                        "validSince": "2017-01-21T00:00:00+02:00",
                                        "validUntil": null,
                                        "maxVisits": 100
                                    }
                                },
                                {
                                    "shortCode": "12Kb3",
                                    "shortUrl": "https://doma.in/12Kb3",
                                    "longUrl": "https://shlink.io",
                                    "dateCreated": "2016-05-01T20:34:16+02:00",
                                    "visitsCount": 1029,
                                    "tags": [
                                        "shlink"
                                    ],
                                    "meta": {
                                        "validSince": null,
                                        "validUntil": null,
                                        "maxVisits": null
                                    }
                                },
                                {
                                    "shortCode": "123bA",
                                    "shortUrl": "https://doma.in/123bA",
                                    "longUrl": "https://www.google.com",
                                    "dateCreated": "2015-10-01T20:34:16+02:00",
                                    "visitsCount": 25,
                                    "tags": [],
                                    "meta": {
                                        "validSince": "2017-01-21T00:00:00+02:00",
                                        "validUntil": null,
                                        "maxVisits": null
                                    }
                                }
                            ],
                            "pagination": {
                                "currentPage": 5,
                                "pagesCount": 12,
                                "itemsPerPage": 10,
                                "itemsInCurrentPage": 10,
                                "totalItems": 115
                            }
                        }
                    }
                }
            },
            "500": {
                "description": "Unexpected error.",
                "content": {
                    "application/problem+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.<br></br>**Param findIfExists:**: Starting with v1.16, this new param allows to force shlink to return existing short URLs when found based on provided params, instead of creating a new one. However, it might add complexity and have unexpected outputs.\n\nThese are the use cases:\n* Only the long URL is provided: It will return the newest match or create a new short URL if none is found.\n* Long url and custom slug are provided: It will return the short URL when both params match, return an error when the slug is in use for another long URL, or create a new short URL otherwise.\n* Any of the above but including other params (tags, validSince, validUntil, maxVisits): It will behave the same as the previous two cases, but it will try to exactly match existing results using all the params. If any of them does not match, it will try to create a new short URL.",
        "security": [
            {
                "ApiKey": []
            },
            {
                "Bearer": []
            }
        ],
        "parameters": [
            {
                "$ref": "../parameters/version.json"
            }
        ],
        "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"
                            },
                            "findIfExists": {
                                "description": "Will force existing matching URL to be returned if found, instead of creating a new one",
                                "type": "boolean"
                            },
                            "domain": {
                                "description": "The domain to which the short URL will be attached",
                                "type": "string"
                            }
                        }
                    }
                }
            }
        },
        "responses": {
            "200": {
                "description": "The result of parsing the long URL",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "../definitions/ShortUrl.json"
                        }
                    }
                },
                "examples": {
                    "application/json": {
                        "shortCode": "12C18",
                        "shortUrl": "https://doma.in/12C18",
                        "longUrl": "https://store.steampowered.com",
                        "dateCreated": "2016-08-21T20:34:16+02:00",
                        "visitsCount": 0,
                        "tags": [
                            "games",
                            "tech"
                        ],
                        "meta": {
                            "validSince": "2017-01-21T00:00:00+02:00",
                            "validUntil": null,
                            "maxVisits": 500
                        }
                    }
                }
            },
            "400": {
                "description": "Some of provided data is invalid. Check extra fields to know exactly what.",
                "content": {
                    "application/problem+json": {
                        "schema": {
                            "type": "object",
                            "allOf": [
                                {
                                    "$ref": "../definitions/Error.json"
                                },
                                {
                                    "type": "object",
                                    "properties": {
                                        "invalidElements": {
                                            "type": "array",
                                            "items": {
                                                "type": "string",
                                                "enum": [
                                                    "validSince",
                                                    "validUntil",
                                                    "customSlug",
                                                    "maxVisits",
                                                    "findIfExists",
                                                    "domain"
                                                ]
                                            }
                                        },
                                        "url": {
                                            "type": "string",
                                            "description": "A URL that could not be verified, if the error type is INVALID_URL"
                                        },
                                        "customSlug": {
                                            "type": "string",
                                            "description": "Provided custom slug when the error type is INVALID_SLUG"
                                        }
                                    }
                                }
                            ]
                        }
                    }
                }
            },
            "500": {
                "description": "Unexpected error.",
                "content": {
                    "application/problem+json": {
                        "schema": {
                            "$ref": "../definitions/Error.json"
                        }
                    }
                }
            }
        }
    }
}