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.",
        "parameters": [
            {
                "$ref": "../parameters/version.json"
            },
            {
                "name": "page",
                "in": "query",
                "description": "The page to be displayed. Defaults to 1",
                "required": false,
                "schema": {
                    "type": "integer"
                }
            },
            {
                "name": "itemsPerPage",
                "in": "query",
                "description": "The amount of items to return on every page. Defaults to 10",
                "required": false,
                "schema": {
                    "type": "number"
                }
            },
            {
                "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 result set. 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-ASC",
                        "longUrl-DESC",
                        "shortCode-ASC",
                        "shortCode-DESC",
                        "dateCreated-ASC",
                        "dateCreated-DESC",
                        "visits-ASC",
                        "visits-DESC",
                        "title-ASC",
                        "title-DESC"
                    ]
                }
            },
            {
                "name": "startDate",
                "in": "query",
                "description": "The date (in ISO-8601 format) from which we want to get short URLs.",
                "required": false,
                "schema": {
                    "type": "string"
                }
            },
            {
                "name": "endDate",
                "in": "query",
                "description": "The date (in ISO-8601 format) until which we want to get short URLs.",
                "required": false,
                "schema": {
                    "type": "string"
                }
            }
        ],
        "security": [
            {
                "ApiKey": []
            }
        ],
        "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
                                    },
                                    "domain": null,
                                    "title": "Welcome to Steam"
                                },
                                {
                                    "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
                                    },
                                    "domain":  null,
                                    "title": null
                                },
                                {
                                    "shortCode": "123bA",
                                    "shortUrl": "https://example.com/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
                                    },
                                    "domain":  "example.com",
                                    "title": 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>**Param findIfExists**: 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": []
            }
        ],
        "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"
                            },
                            "shortCodeLength": {
                                "description": "The length for generated short code. It has to be at least 4 and defaults to 5. It will be ignored when customSlug is provided",
                                "type": "number"
                            },
                            "validateUrl": {
                                "description": "Tells if the long URL should or should not be validated as a reachable URL. If not provided, it will fall back to app-level config",
                                "type": "boolean"
                            },
                            "title": {
                                "type": "string",
                                "description": "A descriptive title of the short URL."
                            }
                        }
                    }
                }
            }
        },
        "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
                        },
                        "domain": null
                    }
                }
            },
            "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"
                        }
                    }
                }
            }
        }
    }
}