From 8b83809e9c496efa503900cb512d20ffee468c19 Mon Sep 17 00:00:00 2001 From: acelaya Date: Mon, 14 Oct 2024 07:51:18 +0000 Subject: [PATCH] =?UTF-8?q?Deploying=20to=20main=20from=20@=20shlinkio/shl?= =?UTF-8?q?ink@fa7969c746ee4b1715bfc64c1ddce1d97672247f=20=F0=9F=9A=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- specs/v4.2.2/open-api-spec.json | 6552 +++++++++++++++++++++++++++++++ 1 file changed, 6552 insertions(+) create mode 100644 specs/v4.2.2/open-api-spec.json diff --git a/specs/v4.2.2/open-api-spec.json b/specs/v4.2.2/open-api-spec.json new file mode 100644 index 0000000..150c943 --- /dev/null +++ b/specs/v4.2.2/open-api-spec.json @@ -0,0 +1,6552 @@ +{ + "openapi": "3.1.0", + "info": { + "title": "Shlink", + "description": "Shlink, the self-hosted URL shortener", + "version": "3.0" + }, + "servers": [ + { + "url": "{scheme}:\/\/{host}", + "variables": { + "scheme": { + "enum": [ + "https", + "http" + ], + "default": "https" + }, + "host": { + "default": "" + } + } + } + ], + "paths": { + "\/rest\/v{version}\/short-urls": { + "get": { + "tags": [ + "Short URLs" + ], + "summary": "List short URLs", + "description": "Returns the list of short URLs.", + "operationId": "listShortUrls", + "parameters": [ + { + "name": "version", + "in": "path", + "description": "The API version to be consumed", + "required": true, + "schema": { + "enum": [ + "3", + "2", + "1" + ], + "type": "string" + } + }, + { + "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": "tagsMode", + "in": "query", + "description": "Tells how the filtering by tags should work, returning short URLs containing \"any\" of the tags, or \"all\" the tags. It's ignored if no tags are provided, and defaults to \"any\" if not provided.", + "required": false, + "schema": { + "enum": [ + "any", + "all" + ], + "type": "string" + } + }, + { + "name": "orderBy", + "in": "query", + "description": "The field from which you want to order the result.", + "required": false, + "schema": { + "enum": [ + "longUrl-ASC", + "longUrl-DESC", + "shortCode-ASC", + "shortCode-DESC", + "dateCreated-ASC", + "dateCreated-DESC", + "title-ASC", + "title-DESC", + "visits-ASC", + "visits-DESC", + "nonBotVisits-ASC", + "nonBotVisits-DESC" + ], + "type": "string" + } + }, + { + "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" + } + }, + { + "name": "excludeMaxVisitsReached", + "in": "query", + "description": "If true, short URLs which already reached their maximum amount of visits will be excluded.", + "required": false, + "schema": { + "enum": [ + "true", + "false" + ], + "type": "string" + } + }, + { + "name": "excludePastValidUntil", + "in": "query", + "description": "If true, short URLs which validUntil date is on the past will be excluded.", + "required": false, + "schema": { + "enum": [ + "true", + "false" + ], + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The list of short URLs", + "content": { + "application\/json": { + "schema": { + "type": "object", + "properties": { + "shortUrls": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "required": [ + "shortCode", + "shortUrl", + "longUrl", + "dateCreated", + "visitsSummary", + "tags", + "meta", + "domain", + "title", + "crawlable", + "forwardQuery" + ], + "type": "object", + "properties": { + "shortCode": { + "type": "string", + "description": "The short code for this short URL." + }, + "shortUrl": { + "type": "string", + "description": "The short URL." + }, + "longUrl": { + "type": "string", + "description": "The original long URL." + }, + "dateCreated": { + "type": "string", + "description": "The date in which the short URL was created in ISO format.", + "format": "date-time" + }, + "visitsSummary": { + "required": [ + "total", + "nonBots", + "bots" + ], + "type": "object", + "properties": { + "total": { + "type": "integer", + "description": "The total amount of visits." + }, + "nonBots": { + "type": "integer", + "description": "The amount of visits which were not identified as bots." + }, + "bots": { + "type": "integer", + "description": "The amount of visits that were identified as potential bots." + } + } + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "A list of tags applied to this short URL" + }, + "meta": { + "required": [ + "validSince", + "validUntil", + "maxVisits" + ], + "type": "object", + "properties": { + "validSince": { + "type": [ + "string", + "null" + ], + "description": "The date (in ISO-8601 format) from which this short code will be valid" + }, + "validUntil": { + "type": [ + "string", + "null" + ], + "description": "The date (in ISO-8601 format) until which this short code will be valid" + }, + "maxVisits": { + "type": [ + "number", + "null" + ], + "description": "The maximum number of allowed visits for this short code" + } + } + }, + "domain": { + "type": [ + "string", + "null" + ], + "description": "The domain in which the short URL was created. Null if it belongs to default domain." + }, + "title": { + "type": [ + "string", + "null" + ], + "description": "A descriptive title of the short URL." + }, + "crawlable": { + "type": "boolean", + "description": "Tells if this URL will be included as 'Allow' in Shlink's robots.txt." + }, + "forwardQuery": { + "type": "boolean", + "description": "Tells if this URL will forward the query params to the long URL when visited, as explained in [the docs](https:\/\/shlink.io\/documentation\/some-features\/#query-params-forwarding)." + } + } + } + }, + "pagination": { + "type": "object", + "properties": { + "currentPage": { + "type": "integer", + "description": "The number of current page." + }, + "pagesCount": { + "type": "integer", + "description": "The total number of pages that can be obtained." + }, + "itemsPerPage": { + "type": "integer", + "description": "The number of items for every page." + }, + "itemsInCurrentPage": { + "type": "integer", + "description": "The number of items in current page (could be smaller than itemsPerPage)." + }, + "totalItems": { + "type": "integer", + "description": "The total number of items among all pages." + } + } + } + } + } + } + }, + "example": { + "shortUrls": { + "data": [ + { + "shortCode": "12C18", + "shortUrl": "https:\/\/s.test\/12C18", + "longUrl": "https:\/\/store.steampowered.com", + "dateCreated": "2016-08-21T20:34:16+02:00", + "visitsSummary": { + "total": 328, + "nonBots": 328, + "bots": 0 + }, + "tags": [ + "games", + "tech" + ], + "meta": { + "validSince": "2017-01-21T00:00:00+02:00", + "validUntil": null, + "maxVisits": 100 + }, + "domain": null, + "title": "Welcome to Steam", + "crawlable": false + }, + { + "shortCode": "12Kb3", + "shortUrl": "https:\/\/s.test\/12Kb3", + "longUrl": "https:\/\/shlink.io", + "dateCreated": "2016-05-01T20:34:16+02:00", + "visitsSummary": { + "total": 1029, + "nonBots": 900, + "bots": 129 + }, + "tags": [ + "shlink" + ], + "meta": { + "validSince": null, + "validUntil": null, + "maxVisits": null + }, + "domain": null, + "title": null, + "crawlable": false + }, + { + "shortCode": "123bA", + "shortUrl": "https:\/\/example.com\/123bA", + "longUrl": "https:\/\/www.google.com", + "dateCreated": "2015-10-01T20:34:16+02:00", + "visitsSummary": { + "total": 25, + "nonBots": 0, + "bots": 25 + }, + "tags": [], + "meta": { + "validSince": "2017-01-21T00:00:00+02:00", + "validUntil": null, + "maxVisits": null + }, + "domain": "example.com", + "title": null, + "crawlable": false + } + ], + "pagination": { + "currentPage": 5, + "pagesCount": 12, + "itemsPerPage": 10, + "itemsInCurrentPage": 10, + "totalItems": 115 + } + } + } + } + } + }, + "default": { + "description": "Unexpected error.", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKey": [] + } + ] + }, + "post": { + "tags": [ + "Short URLs" + ], + "summary": "Create short URL", + "description": "Creates a new short URL.
<\/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.", + "operationId": "createShortUrl", + "parameters": [ + { + "name": "version", + "in": "path", + "description": "The API version to be consumed", + "required": true, + "schema": { + "enum": [ + "3", + "2", + "1" + ], + "type": "string" + } + } + ], + "requestBody": { + "description": "Request body.", + "content": { + "application\/json": { + "schema": { + "allOf": [ + { + "type": "object", + "properties": { + "longUrl": { + "type": "string", + "description": "The long URL this short URL will redirect to" + }, + "validSince": { + "type": [ + "string", + "null" + ], + "description": "The date (in ISO-8601 format) from which this short code will be valid" + }, + "validUntil": { + "type": [ + "string", + "null" + ], + "description": "The date (in ISO-8601 format) until which this short code will be valid" + }, + "maxVisits": { + "type": [ + "number", + "null" + ], + "description": "The maximum number of allowed visits for this short code" + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The list of tags to set to the short URL." + }, + "title": { + "type": [ + "string", + "null" + ], + "description": "A descriptive title of the short URL." + }, + "crawlable": { + "type": "boolean", + "description": "Tells if this URL will be included as 'Allow' in Shlink's robots.txt." + }, + "forwardQuery": { + "type": "boolean", + "description": "Tells if the query params should be forwarded from the short URL to the long one, as explained in [the docs](https:\/\/shlink.io\/documentation\/some-features\/#query-params-forwarding)." + } + } + }, + { + "required": [ + "longUrl" + ], + "type": "object", + "properties": { + "customSlug": { + "type": "string", + "description": "A unique custom slug to be used instead of the generated short code" + }, + "pathPrefix": { + "type": "string", + "description": "A prefix that will be prepended to provided custom slug or auto-generated short code" + }, + "findIfExists": { + "type": "boolean", + "description": "Will force existing matching URL to be returned if found, instead of creating a new one" + }, + "domain": { + "type": "string", + "description": "The domain to which the short URL will be attached" + }, + "shortCodeLength": { + "type": "number", + "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" + } + } + } + ] + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "The result of parsing the long URL", + "content": { + "application\/json": { + "schema": { + "required": [ + "shortCode", + "shortUrl", + "longUrl", + "dateCreated", + "visitsSummary", + "tags", + "meta", + "domain", + "title", + "crawlable", + "forwardQuery" + ], + "type": "object", + "properties": { + "shortCode": { + "type": "string", + "description": "The short code for this short URL." + }, + "shortUrl": { + "type": "string", + "description": "The short URL." + }, + "longUrl": { + "type": "string", + "description": "The original long URL." + }, + "dateCreated": { + "type": "string", + "description": "The date in which the short URL was created in ISO format.", + "format": "date-time" + }, + "visitsSummary": { + "required": [ + "total", + "nonBots", + "bots" + ], + "type": "object", + "properties": { + "total": { + "type": "integer", + "description": "The total amount of visits." + }, + "nonBots": { + "type": "integer", + "description": "The amount of visits which were not identified as bots." + }, + "bots": { + "type": "integer", + "description": "The amount of visits that were identified as potential bots." + } + } + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "A list of tags applied to this short URL" + }, + "meta": { + "required": [ + "validSince", + "validUntil", + "maxVisits" + ], + "type": "object", + "properties": { + "validSince": { + "type": [ + "string", + "null" + ], + "description": "The date (in ISO-8601 format) from which this short code will be valid" + }, + "validUntil": { + "type": [ + "string", + "null" + ], + "description": "The date (in ISO-8601 format) until which this short code will be valid" + }, + "maxVisits": { + "type": [ + "number", + "null" + ], + "description": "The maximum number of allowed visits for this short code" + } + } + }, + "domain": { + "type": [ + "string", + "null" + ], + "description": "The domain in which the short URL was created. Null if it belongs to default domain." + }, + "title": { + "type": [ + "string", + "null" + ], + "description": "A descriptive title of the short URL." + }, + "crawlable": { + "type": "boolean", + "description": "Tells if this URL will be included as 'Allow' in Shlink's robots.txt." + }, + "forwardQuery": { + "type": "boolean", + "description": "Tells if this URL will forward the query params to the long URL when visited, as explained in [the docs](https:\/\/shlink.io\/documentation\/some-features\/#query-params-forwarding)." + } + } + }, + "example": { + "shortCode": "12C18", + "shortUrl": "https:\/\/s.test\/12C18", + "longUrl": "https:\/\/store.steampowered.com", + "dateCreated": "2016-08-21T20:34:16+02:00", + "visitsSummary": { + "total": 0, + "nonBots": 0, + "bots": 0 + }, + "tags": [ + "games", + "tech" + ], + "meta": { + "validSince": "2017-01-21T00:00:00+02:00", + "validUntil": null, + "maxVisits": 500 + }, + "domain": null, + "title": null, + "crawlable": false + } + } + } + }, + "400": { + "description": "Some of provided data is invalid. Check extra fields to know exactly what.", + "content": { + "application\/problem+json": { + "schema": { + "type": "object", + "allOf": [ + { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + }, + { + "type": "object", + "properties": { + "invalidElements": { + "type": "array", + "items": { + "enum": [ + "validSince", + "validUntil", + "customSlug", + "pathPrefix", + "maxVisits", + "findIfExists", + "domain" + ], + "type": "string" + } + }, + "customSlug": { + "type": "string", + "description": "Provided custom slug when the error type is https:\/\/shlink.io\/api\/error\/non-unique-slug" + }, + "domain": { + "type": "string", + "description": "The domain for which you were trying to create the new short URL" + } + } + } + ] + }, + "examples": { + "Invalid arguments": { + "value": { + "title": "Invalid data", + "type": "https:\/\/shlink.io\/api\/error\/invalid-data", + "detail": "Provided data is not valid", + "status": 400, + "invalidElements": [ + "maxVisits", + "validSince" + ] + } + }, + "Non-unique slug": { + "value": { + "title": "Invalid custom slug", + "type": "https:\/\/shlink.io\/api\/error\/non-unique-slug", + "detail": "Provided slug \"my-slug\" is already in use.", + "status": 400, + "customSlug": "my-slug" + } + } + } + } + } + }, + "default": { + "description": "Unexpected error.", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKey": [] + } + ] + } + }, + "\/rest\/v{version}\/short-urls\/shorten": { + "get": { + "tags": [ + "Short URLs" + ], + "summary": "Create a short URL", + "description": "**[Deprecated]** Use [Create short URL](#\/Short%20URLs\/createShortUrl) instead", + "operationId": "shortenUrl", + "parameters": [ + { + "name": "version", + "in": "path", + "description": "The API version to be consumed", + "required": true, + "schema": { + "enum": [ + "3", + "2", + "1" + ], + "type": "string" + } + }, + { + "name": "apiKey", + "in": "query", + "description": "The API key used to authenticate the request", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "longUrl", + "in": "query", + "description": "The URL to be shortened", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "format", + "in": "query", + "description": "The format in which you want the response to be returned. You can also use the \"Accept\" header instead of this", + "required": false, + "schema": { + "enum": [ + "txt", + "json" + ], + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The list of short URLs", + "content": { + "application\/json": { + "schema": { + "required": [ + "shortCode", + "shortUrl", + "longUrl", + "dateCreated", + "visitsSummary", + "tags", + "meta", + "domain", + "title", + "crawlable", + "forwardQuery" + ], + "type": "object", + "properties": { + "shortCode": { + "type": "string", + "description": "The short code for this short URL." + }, + "shortUrl": { + "type": "string", + "description": "The short URL." + }, + "longUrl": { + "type": "string", + "description": "The original long URL." + }, + "dateCreated": { + "type": "string", + "description": "The date in which the short URL was created in ISO format.", + "format": "date-time" + }, + "visitsSummary": { + "required": [ + "total", + "nonBots", + "bots" + ], + "type": "object", + "properties": { + "total": { + "type": "integer", + "description": "The total amount of visits." + }, + "nonBots": { + "type": "integer", + "description": "The amount of visits which were not identified as bots." + }, + "bots": { + "type": "integer", + "description": "The amount of visits that were identified as potential bots." + } + } + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "A list of tags applied to this short URL" + }, + "meta": { + "required": [ + "validSince", + "validUntil", + "maxVisits" + ], + "type": "object", + "properties": { + "validSince": { + "type": [ + "string", + "null" + ], + "description": "The date (in ISO-8601 format) from which this short code will be valid" + }, + "validUntil": { + "type": [ + "string", + "null" + ], + "description": "The date (in ISO-8601 format) until which this short code will be valid" + }, + "maxVisits": { + "type": [ + "number", + "null" + ], + "description": "The maximum number of allowed visits for this short code" + } + } + }, + "domain": { + "type": [ + "string", + "null" + ], + "description": "The domain in which the short URL was created. Null if it belongs to default domain." + }, + "title": { + "type": [ + "string", + "null" + ], + "description": "A descriptive title of the short URL." + }, + "crawlable": { + "type": "boolean", + "description": "Tells if this URL will be included as 'Allow' in Shlink's robots.txt." + }, + "forwardQuery": { + "type": "boolean", + "description": "Tells if this URL will forward the query params to the long URL when visited, as explained in [the docs](https:\/\/shlink.io\/documentation\/some-features\/#query-params-forwarding)." + } + } + }, + "example": { + "longUrl": "https:\/\/github.com\/shlinkio\/shlink", + "shortUrl": "https:\/\/s.test\/abc123", + "shortCode": "abc123", + "dateCreated": "2016-08-21T20:34:16+02:00", + "visitsSummary": { + "total": 0, + "nonBots": 0, + "bots": 0 + }, + "tags": [ + "games", + "tech" + ], + "meta": { + "validSince": "2017-01-21T00:00:00+02:00", + "validUntil": null, + "maxVisits": 100 + }, + "domain": null, + "title": null, + "crawlable": false + } + }, + "text\/plain": { + "schema": { + "type": "string" + }, + "example": "https:\/\/s.test\/abc123" + } + } + }, + "default": { + "description": "Unexpected error.", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + } + }, + "text\/plain": { + "schema": { + "type": "string" + } + } + } + } + }, + "deprecated": true + } + }, + "\/rest\/v{version}\/short-urls\/{shortCode}": { + "get": { + "tags": [ + "Short URLs" + ], + "summary": "Parse short code", + "description": "Get the long URL behind a short URL's short code.", + "operationId": "getShortUrl", + "parameters": [ + { + "name": "version", + "in": "path", + "description": "The API version to be consumed", + "required": true, + "schema": { + "enum": [ + "3", + "2", + "1" + ], + "type": "string" + } + }, + { + "name": "shortCode", + "in": "path", + "description": "The short code for the short URL.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "domain", + "in": "query", + "description": "The domain in which the short code should be searched for.", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The URL info behind a short code.", + "content": { + "application\/json": { + "schema": { + "required": [ + "shortCode", + "shortUrl", + "longUrl", + "dateCreated", + "visitsSummary", + "tags", + "meta", + "domain", + "title", + "crawlable", + "forwardQuery" + ], + "type": "object", + "properties": { + "shortCode": { + "type": "string", + "description": "The short code for this short URL." + }, + "shortUrl": { + "type": "string", + "description": "The short URL." + }, + "longUrl": { + "type": "string", + "description": "The original long URL." + }, + "dateCreated": { + "type": "string", + "description": "The date in which the short URL was created in ISO format.", + "format": "date-time" + }, + "visitsSummary": { + "required": [ + "total", + "nonBots", + "bots" + ], + "type": "object", + "properties": { + "total": { + "type": "integer", + "description": "The total amount of visits." + }, + "nonBots": { + "type": "integer", + "description": "The amount of visits which were not identified as bots." + }, + "bots": { + "type": "integer", + "description": "The amount of visits that were identified as potential bots." + } + } + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "A list of tags applied to this short URL" + }, + "meta": { + "required": [ + "validSince", + "validUntil", + "maxVisits" + ], + "type": "object", + "properties": { + "validSince": { + "type": [ + "string", + "null" + ], + "description": "The date (in ISO-8601 format) from which this short code will be valid" + }, + "validUntil": { + "type": [ + "string", + "null" + ], + "description": "The date (in ISO-8601 format) until which this short code will be valid" + }, + "maxVisits": { + "type": [ + "number", + "null" + ], + "description": "The maximum number of allowed visits for this short code" + } + } + }, + "domain": { + "type": [ + "string", + "null" + ], + "description": "The domain in which the short URL was created. Null if it belongs to default domain." + }, + "title": { + "type": [ + "string", + "null" + ], + "description": "A descriptive title of the short URL." + }, + "crawlable": { + "type": "boolean", + "description": "Tells if this URL will be included as 'Allow' in Shlink's robots.txt." + }, + "forwardQuery": { + "type": "boolean", + "description": "Tells if this URL will forward the query params to the long URL when visited, as explained in [the docs](https:\/\/shlink.io\/documentation\/some-features\/#query-params-forwarding)." + } + } + }, + "example": { + "shortCode": "12Kb3", + "shortUrl": "https:\/\/s.test\/12Kb3", + "longUrl": "https:\/\/shlink.io", + "dateCreated": "2016-05-01T20:34:16+02:00", + "visitsSummary": { + "total": 1029, + "nonBots": 820, + "bots": 209 + }, + "tags": [ + "shlink" + ], + "meta": { + "validSince": "2017-01-21T00:00:00+02:00", + "validUntil": null, + "maxVisits": 100 + }, + "domain": null, + "title": null, + "crawlable": false + } + } + } + }, + "404": { + "description": "No URL was found for provided short code.", + "content": { + "application\/problem+json": { + "schema": { + "allOf": [ + { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + }, + { + "required": [ + "shortCode" + ], + "type": "object", + "properties": { + "shortCode": { + "type": "string", + "description": "The short code with which we tried to find the short URL" + }, + "domain": { + "type": "string", + "description": "The domain with which we tried to find the short URL" + } + } + } + ] + }, + "examples": { + "Short URL not found": { + "value": { + "detail": "No URL found with short code \"abc123\"", + "title": "Short URL not found", + "type": "https:\/\/shlink.io\/api\/error\/short-url-not-found", + "status": 404, + "shortCode": "abc123" + } + } + } + } + } + }, + "default": { + "description": "Unexpected error.", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKey": [] + } + ] + }, + "delete": { + "tags": [ + "Short URLs" + ], + "summary": "Delete short URL", + "description": "Deletes the short URL for provided short code.", + "operationId": "deleteShortUrl", + "parameters": [ + { + "name": "version", + "in": "path", + "description": "The API version to be consumed", + "required": true, + "schema": { + "enum": [ + "3", + "2", + "1" + ], + "type": "string" + } + }, + { + "name": "shortCode", + "in": "path", + "description": "The short code for the short URL.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "domain", + "in": "query", + "description": "The domain in which the short code should be searched for.", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "204": { + "description": "The short URL has been properly deleted." + }, + "422": { + "description": "The visits threshold in shlink does not allow this short URL to be deleted.", + "content": { + "application\/problem+json": { + "schema": { + "allOf": [ + { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + }, + { + "required": [ + "shortCode", + "threshold" + ], + "type": "object", + "properties": { + "shortCode": { + "type": "string", + "description": "The short code with which we tried to find the short URL to delete" + }, + "domain": { + "type": "string", + "description": "The domain with which we tried to find the short URL to delete" + }, + "threshold": { + "type": "number", + "description": "The amount of visits currently configured as threshold to allow deleting short URLs or not" + } + } + } + ] + }, + "examples": { + "API v3 and newer": { + "value": { + "title": "Cannot delete short URL", + "type": "https:\/\/shlink.io\/api\/error\/invalid-short-url-deletion", + "detail": "Impossible to delete short URL with short code \"abc123\", since it has more than \"15\" visits.", + "status": 422, + "shortCode": "abc123", + "threshold": 15 + } + }, + "Previous to API v3": { + "value": { + "title": "Cannot delete short URL", + "type": "INVALID_SHORT_URL_DELETION", + "detail": "Impossible to delete short URL with short code \"abc123\", since it has more than \"15\" visits.", + "status": 422, + "shortCode": "abc123", + "threshold": 15 + } + } + } + } + } + }, + "404": { + "description": "No URL was found for provided short code.", + "content": { + "application\/problem+json": { + "schema": { + "allOf": [ + { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + }, + { + "required": [ + "shortCode" + ], + "type": "object", + "properties": { + "shortCode": { + "type": "string", + "description": "The short code with which we tried to find the short URL" + }, + "domain": { + "type": "string", + "description": "The domain with which we tried to find the short URL" + } + } + } + ] + }, + "examples": { + "Short URL not found": { + "value": { + "detail": "No URL found with short code \"abc123\"", + "title": "Short URL not found", + "type": "https:\/\/shlink.io\/api\/error\/short-url-not-found", + "status": 404, + "shortCode": "abc123" + } + } + } + } + } + }, + "default": { + "description": "Unexpected error.", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKey": [] + } + ] + }, + "patch": { + "tags": [ + "Short URLs" + ], + "summary": "Edit short URL", + "description": "Update certain meta arguments from an existing short URL.", + "operationId": "editShortUrl", + "parameters": [ + { + "name": "version", + "in": "path", + "description": "The API version to be consumed", + "required": true, + "schema": { + "enum": [ + "3", + "2", + "1" + ], + "type": "string" + } + }, + { + "name": "shortCode", + "in": "path", + "description": "The short code for the short URL.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "domain", + "in": "query", + "description": "The domain in which the short code should be searched for.", + "required": false, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "Request body.", + "content": { + "application\/json": { + "schema": { + "type": "object", + "properties": { + "longUrl": { + "type": "string", + "description": "The long URL this short URL will redirect to" + }, + "validSince": { + "type": [ + "string", + "null" + ], + "description": "The date (in ISO-8601 format) from which this short code will be valid" + }, + "validUntil": { + "type": [ + "string", + "null" + ], + "description": "The date (in ISO-8601 format) until which this short code will be valid" + }, + "maxVisits": { + "type": [ + "number", + "null" + ], + "description": "The maximum number of allowed visits for this short code" + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "The list of tags to set to the short URL." + }, + "title": { + "type": [ + "string", + "null" + ], + "description": "A descriptive title of the short URL." + }, + "crawlable": { + "type": "boolean", + "description": "Tells if this URL will be included as 'Allow' in Shlink's robots.txt." + }, + "forwardQuery": { + "type": "boolean", + "description": "Tells if the query params should be forwarded from the short URL to the long one, as explained in [the docs](https:\/\/shlink.io\/documentation\/some-features\/#query-params-forwarding)." + } + } + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "The short URL has been properly updated.", + "content": { + "application\/json": { + "schema": { + "required": [ + "shortCode", + "shortUrl", + "longUrl", + "dateCreated", + "visitsSummary", + "tags", + "meta", + "domain", + "title", + "crawlable", + "forwardQuery" + ], + "type": "object", + "properties": { + "shortCode": { + "type": "string", + "description": "The short code for this short URL." + }, + "shortUrl": { + "type": "string", + "description": "The short URL." + }, + "longUrl": { + "type": "string", + "description": "The original long URL." + }, + "dateCreated": { + "type": "string", + "description": "The date in which the short URL was created in ISO format.", + "format": "date-time" + }, + "visitsSummary": { + "required": [ + "total", + "nonBots", + "bots" + ], + "type": "object", + "properties": { + "total": { + "type": "integer", + "description": "The total amount of visits." + }, + "nonBots": { + "type": "integer", + "description": "The amount of visits which were not identified as bots." + }, + "bots": { + "type": "integer", + "description": "The amount of visits that were identified as potential bots." + } + } + }, + "tags": { + "type": "array", + "items": { + "type": "string" + }, + "description": "A list of tags applied to this short URL" + }, + "meta": { + "required": [ + "validSince", + "validUntil", + "maxVisits" + ], + "type": "object", + "properties": { + "validSince": { + "type": [ + "string", + "null" + ], + "description": "The date (in ISO-8601 format) from which this short code will be valid" + }, + "validUntil": { + "type": [ + "string", + "null" + ], + "description": "The date (in ISO-8601 format) until which this short code will be valid" + }, + "maxVisits": { + "type": [ + "number", + "null" + ], + "description": "The maximum number of allowed visits for this short code" + } + } + }, + "domain": { + "type": [ + "string", + "null" + ], + "description": "The domain in which the short URL was created. Null if it belongs to default domain." + }, + "title": { + "type": [ + "string", + "null" + ], + "description": "A descriptive title of the short URL." + }, + "crawlable": { + "type": "boolean", + "description": "Tells if this URL will be included as 'Allow' in Shlink's robots.txt." + }, + "forwardQuery": { + "type": "boolean", + "description": "Tells if this URL will forward the query params to the long URL when visited, as explained in [the docs](https:\/\/shlink.io\/documentation\/some-features\/#query-params-forwarding)." + } + } + }, + "example": { + "shortCode": "12Kb3", + "shortUrl": "https:\/\/s.test\/12Kb3", + "longUrl": "https:\/\/shlink.io", + "dateCreated": "2016-05-01T20:34:16+02:00", + "visitsSummary": { + "total": 1029, + "nonBots": 900, + "bots": 129 + }, + "tags": [ + "shlink" + ], + "meta": { + "validSince": "2017-01-21T00:00:00+02:00", + "validUntil": null, + "maxVisits": 100 + }, + "domain": null, + "title": "Shlink - The URL shortener", + "crawlable": false + } + } + } + }, + "400": { + "description": "Provided meta arguments are invalid.", + "content": { + "application\/problem+json": { + "schema": { + "type": "object", + "allOf": [ + { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + }, + { + "required": [ + "invalidElements" + ], + "type": "object", + "properties": { + "invalidElements": { + "type": "array", + "items": { + "enum": [ + "longUrl", + "validSince", + "validUntil", + "maxVisits" + ], + "type": "string" + } + } + } + } + ] + }, + "examples": { + "Invalid arguments": { + "value": { + "title": "Invalid data", + "type": "https:\/\/shlink.io\/api\/error\/invalid-data", + "detail": "Provided data is not valid", + "status": 400, + "invalidElements": [ + "maxVisits", + "validSince" + ] + } + } + } + } + } + }, + "404": { + "description": "No URL was found for provided short code.", + "content": { + "application\/problem+json": { + "schema": { + "allOf": [ + { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + }, + { + "required": [ + "shortCode" + ], + "type": "object", + "properties": { + "shortCode": { + "type": "string", + "description": "The short code with which we tried to find the short URL" + }, + "domain": { + "type": "string", + "description": "The domain with which we tried to find the short URL" + } + } + } + ] + }, + "examples": { + "Short URL not found": { + "value": { + "detail": "No URL found with short code \"abc123\"", + "title": "Short URL not found", + "type": "https:\/\/shlink.io\/api\/error\/short-url-not-found", + "status": 404, + "shortCode": "abc123" + } + } + } + } + } + }, + "default": { + "description": "Unexpected error.", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKey": [] + } + ] + } + }, + "\/rest\/v{version}\/short-urls\/{shortCode}\/redirect-rules": { + "get": { + "tags": [ + "Redirect rules" + ], + "summary": "List short URL redirect rules", + "description": "Returns the list of redirect rules for a short URL.", + "operationId": "listShortUrlRedirectRules", + "parameters": [ + { + "name": "version", + "in": "path", + "description": "The API version to be consumed", + "required": true, + "schema": { + "enum": [ + "3", + "2", + "1" + ], + "type": "string" + } + }, + { + "name": "shortCode", + "in": "path", + "description": "The short code for the short URL.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "domain", + "in": "query", + "description": "The domain in which the short code should be searched for.", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The list of rules", + "content": { + "application\/json": { + "schema": { + "required": [ + "defaultLongUrl", + "redirectRules" + ], + "type": "object", + "properties": { + "defaultLongUrl": { + "type": "string" + }, + "redirectRules": { + "type": "array", + "items": { + "required": [ + "priority" + ], + "type": "object", + "allOf": [ + { + "required": [ + "longUrl", + "conditions" + ], + "type": "object", + "properties": { + "longUrl": { + "type": "string", + "description": "Long URL to redirect to when this condition matches" + }, + "conditions": { + "type": "array", + "items": { + "required": [ + "type", + "matchKey", + "matchValue" + ], + "type": "object", + "properties": { + "type": { + "enum": [ + "device", + "language", + "query-param", + "ip-address" + ], + "type": "string", + "description": "The type of the condition, which will determine the logic used to match it" + }, + "matchKey": { + "type": [ + "string", + "null" + ] + }, + "matchValue": { + "type": "string" + } + } + }, + "description": "List of conditions that need to match in order to consider this rule matches" + } + } + } + ], + "properties": { + "priority": { + "type": "number", + "description": "Order in which attempting to match the rule. Lower goes first" + } + } + } + } + } + }, + "example": { + "defaultLongUrl": "https:\/\/example.com", + "redirectRules": [ + { + "longUrl": "https:\/\/example.com\/android-en-us", + "priority": 1, + "conditions": [ + { + "type": "device", + "matchValue": "android", + "matchKey": null + }, + { + "type": "language", + "matchValue": "en-US", + "matchKey": null + } + ] + }, + { + "longUrl": "https:\/\/example.com\/fr", + "priority": 2, + "conditions": [ + { + "type": "language", + "matchValue": "fr", + "matchKey": null + } + ] + }, + { + "longUrl": "https:\/\/example.com\/query-foo-bar-hello-world", + "priority": 3, + "conditions": [ + { + "type": "query-param", + "matchKey": "foo", + "matchValue": "bar" + }, + { + "type": "query-param", + "matchKey": "hello", + "matchValue": "world" + } + ] + } + ] + } + } + } + }, + "404": { + "description": "No URL was found for provided short code.", + "content": { + "application\/problem+json": { + "schema": { + "allOf": [ + { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + }, + { + "required": [ + "shortCode" + ], + "type": "object", + "properties": { + "shortCode": { + "type": "string", + "description": "The short code with which we tried to find the short URL" + }, + "domain": { + "type": "string", + "description": "The domain with which we tried to find the short URL" + } + } + } + ] + }, + "examples": { + "Short URL not found": { + "value": { + "detail": "No URL found with short code \"abc123\"", + "title": "Short URL not found", + "type": "https:\/\/shlink.io\/api\/error\/short-url-not-found", + "status": 404, + "shortCode": "abc123" + } + } + } + } + } + }, + "default": { + "description": "Unexpected error.", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKey": [] + } + ] + }, + "post": { + "tags": [ + "Redirect rules" + ], + "summary": "Set short URL redirect rules", + "description": "Sets redirect rules for a short URL, with priorities matching the order in which they are provided.", + "operationId": "setShortUrlRedirectRules", + "parameters": [ + { + "name": "version", + "in": "path", + "description": "The API version to be consumed", + "required": true, + "schema": { + "enum": [ + "3", + "2", + "1" + ], + "type": "string" + } + }, + { + "name": "shortCode", + "in": "path", + "description": "The short code for the short URL.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "domain", + "in": "query", + "description": "The domain in which the short code should be searched for.", + "required": false, + "schema": { + "type": "string" + } + } + ], + "requestBody": { + "description": "Request body.", + "content": { + "application\/json": { + "schema": { + "type": "object", + "properties": { + "redirectRules": { + "type": "array", + "items": { + "required": [ + "longUrl", + "conditions" + ], + "type": "object", + "properties": { + "longUrl": { + "type": "string", + "description": "Long URL to redirect to when this condition matches" + }, + "conditions": { + "type": "array", + "items": { + "required": [ + "type", + "matchKey", + "matchValue" + ], + "type": "object", + "properties": { + "type": { + "enum": [ + "device", + "language", + "query-param", + "ip-address" + ], + "type": "string", + "description": "The type of the condition, which will determine the logic used to match it" + }, + "matchKey": { + "type": [ + "string", + "null" + ] + }, + "matchValue": { + "type": "string" + } + } + }, + "description": "List of conditions that need to match in order to consider this rule matches" + } + } + } + } + } + }, + "example": { + "redirectRules": [ + { + "longUrl": "https:\/\/example.com\/android-en-us", + "conditions": [ + { + "type": "device", + "matchValue": "android", + "matchKey": null + }, + { + "type": "language", + "matchValue": "en-US", + "matchKey": null + } + ] + }, + { + "longUrl": "https:\/\/example.com\/fr", + "conditions": [ + { + "type": "language", + "matchValue": "fr", + "matchKey": null + } + ] + }, + { + "longUrl": "https:\/\/example.com\/query-foo-bar-hello-world", + "conditions": [ + { + "type": "query-param", + "matchKey": "foo", + "matchValue": "bar" + }, + { + "type": "query-param", + "matchKey": "hello", + "matchValue": "world" + } + ] + } + ] + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "The list of rules", + "content": { + "application\/json": { + "schema": { + "required": [ + "defaultLongUrl", + "redirectRules" + ], + "type": "object", + "properties": { + "defaultLongUrl": { + "type": "string" + }, + "redirectRules": { + "type": "array", + "items": { + "required": [ + "priority" + ], + "type": "object", + "allOf": [ + { + "required": [ + "longUrl", + "conditions" + ], + "type": "object", + "properties": { + "longUrl": { + "type": "string", + "description": "Long URL to redirect to when this condition matches" + }, + "conditions": { + "type": "array", + "items": { + "required": [ + "type", + "matchKey", + "matchValue" + ], + "type": "object", + "properties": { + "type": { + "enum": [ + "device", + "language", + "query-param", + "ip-address" + ], + "type": "string", + "description": "The type of the condition, which will determine the logic used to match it" + }, + "matchKey": { + "type": [ + "string", + "null" + ] + }, + "matchValue": { + "type": "string" + } + } + }, + "description": "List of conditions that need to match in order to consider this rule matches" + } + } + } + ], + "properties": { + "priority": { + "type": "number", + "description": "Order in which attempting to match the rule. Lower goes first" + } + } + } + } + } + }, + "example": { + "defaultLongUrl": "https:\/\/example.com", + "redirectRules": [ + { + "longUrl": "https:\/\/example.com\/android-en-us", + "priority": 1, + "conditions": [ + { + "type": "device", + "matchValue": "android", + "matchKey": null + }, + { + "type": "language", + "matchValue": "en-US", + "matchKey": null + } + ] + }, + { + "longUrl": "https:\/\/example.com\/fr", + "priority": 2, + "conditions": [ + { + "type": "language", + "matchValue": "fr", + "matchKey": null + } + ] + }, + { + "longUrl": "https:\/\/example.com\/query-foo-bar-hello-world", + "priority": 3, + "conditions": [ + { + "type": "query-param", + "matchKey": "foo", + "matchValue": "bar" + }, + { + "type": "query-param", + "matchKey": "hello", + "matchValue": "world" + } + ] + } + ] + } + } + } + }, + "404": { + "description": "No URL was found for provided short code.", + "content": { + "application\/problem+json": { + "schema": { + "allOf": [ + { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + }, + { + "required": [ + "shortCode" + ], + "type": "object", + "properties": { + "shortCode": { + "type": "string", + "description": "The short code with which we tried to find the short URL" + }, + "domain": { + "type": "string", + "description": "The domain with which we tried to find the short URL" + } + } + } + ] + }, + "examples": { + "Short URL not found": { + "value": { + "detail": "No URL found with short code \"abc123\"", + "title": "Short URL not found", + "type": "https:\/\/shlink.io\/api\/error\/short-url-not-found", + "status": 404, + "shortCode": "abc123" + } + } + } + } + } + }, + "default": { + "description": "Unexpected error.", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKey": [] + } + ] + } + }, + "\/rest\/v{version}\/tags": { + "get": { + "tags": [ + "Tags" + ], + "summary": "List existing tags", + "description": "Returns the list of all tags used in any short URL", + "operationId": "listTags", + "parameters": [ + { + "name": "version", + "in": "path", + "description": "The API version to be consumed", + "required": true, + "schema": { + "enum": [ + "3", + "2", + "1" + ], + "type": "string" + } + }, + { + "name": "page", + "in": "query", + "description": "The page to display. Defaults to 1", + "required": false, + "schema": { + "type": "number" + } + }, + { + "name": "itemsPerPage", + "in": "query", + "description": "The amount of items to return on every page. Defaults to all the items", + "required": false, + "schema": { + "type": "number" + } + }, + { + "name": "searchTerm", + "in": "query", + "description": "A query used to filter results by searching for it on the tag name.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "orderBy", + "in": "query", + "description": "To determine how to order the results.", + "required": false, + "schema": { + "enum": [ + "tag-ASC", + "tag-DESC" + ], + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The list of tags", + "content": { + "application\/json": { + "schema": { + "type": "object", + "properties": { + "tags": { + "required": [ + "data" + ], + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "type": "string" + } + }, + "pagination": { + "type": "object", + "properties": { + "currentPage": { + "type": "integer", + "description": "The number of current page." + }, + "pagesCount": { + "type": "integer", + "description": "The total number of pages that can be obtained." + }, + "itemsPerPage": { + "type": "integer", + "description": "The number of items for every page." + }, + "itemsInCurrentPage": { + "type": "integer", + "description": "The number of items in current page (could be smaller than itemsPerPage)." + }, + "totalItems": { + "type": "integer", + "description": "The total number of items among all pages." + } + } + } + } + } + } + }, + "example": { + "tags": { + "data": [ + "games", + "php", + "shlink", + "tech" + ], + "pagination": { + "currentPage": 5, + "pagesCount": 10, + "itemsPerPage": 4, + "itemsInCurrentPage": 4, + "totalItems": 38 + } + } + } + } + } + }, + "default": { + "description": "Unexpected error.", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKey": [] + } + ] + }, + "put": { + "tags": [ + "Tags" + ], + "summary": "Rename tag", + "description": "Renames one existing tag", + "operationId": "renameTag", + "parameters": [ + { + "name": "version", + "in": "path", + "description": "The API version to be consumed", + "required": true, + "schema": { + "enum": [ + "3", + "2", + "1" + ], + "type": "string" + } + } + ], + "requestBody": { + "description": "Request body.", + "content": { + "application\/json": { + "schema": { + "required": [ + "oldName", + "newName" + ], + "type": "object", + "properties": { + "oldName": { + "type": "string", + "description": "Current name of the tag" + }, + "newName": { + "type": "string", + "description": "New name of the tag" + } + } + } + } + }, + "required": true + }, + "responses": { + "204": { + "description": "The tag has been properly renamed" + }, + "400": { + "description": "You have not provided either the oldName or the newName params.", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + }, + "examples": { + "API v3 and newer": { + "value": { + "title": "Invalid data", + "type": "https:\/\/shlink.io\/api\/error\/invalid-data", + "detail": "Provided data is not valid", + "status": 400, + "invalidElements": [ + "oldName", + "newName" + ] + } + }, + "Previous to API v3": { + "value": { + "title": "Invalid data", + "type": "INVALID_ARGUMENT", + "detail": "Provided data is not valid", + "status": 400, + "invalidElements": [ + "oldName", + "newName" + ] + } + } + } + } + } + }, + "403": { + "description": "The API key you used does not have permissions to rename tags.", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + }, + "examples": { + "API v3 and newer": { + "value": { + "detail": "You are not allowed to rename tags", + "title": "Forbidden tag operation", + "type": "https:\/\/shlink.io\/api\/error\/forbidden-tag-operation", + "status": 403 + } + }, + "Previous to API v3": { + "value": { + "detail": "You are not allowed to rename tags", + "title": "Forbidden tag operation", + "type": "FORBIDDEN_OPERATION", + "status": 403 + } + } + } + } + } + }, + "404": { + "description": "There's no tag found with the name provided in oldName param.", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + }, + "examples": { + "API v3 and newer": { + "value": { + "detail": "Tag with name \"foo\" could not be found", + "title": "Tag not found", + "type": "https:\/\/shlink.io\/api\/error\/tag-not-found", + "status": 404, + "tag": "foo" + } + } + } + } + } + }, + "409": { + "description": "The name provided in newName param is already in use for another tag.", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + }, + "examples": { + "API v3 and newer": { + "value": { + "detail": "You cannot rename tag foo, because it already exists", + "title": "Tag conflict", + "type": "https:\/\/shlink.io\/api\/error\/tag-conflict", + "status": 409, + "oldName": "bar", + "newName": "foo" + } + }, + "Previous to API v3": { + "value": { + "detail": "You cannot rename tag foo, because it already exists", + "title": "Tag conflict", + "type": "TAG_CONFLICT", + "status": 409, + "oldName": "bar", + "newName": "foo" + } + } + } + } + } + }, + "default": { + "description": "Unexpected error.", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKey": [] + } + ] + }, + "delete": { + "tags": [ + "Tags" + ], + "summary": "Delete tags", + "description": "Deletes provided list of tags", + "operationId": "deleteTags", + "parameters": [ + { + "name": "version", + "in": "path", + "description": "The API version to be consumed", + "required": true, + "schema": { + "enum": [ + "3", + "2", + "1" + ], + "type": "string" + } + }, + { + "name": "tags[]", + "in": "query", + "description": "The names of the tags to delete", + "required": true, + "schema": { + "type": "array", + "items": { + "type": "string" + } + } + } + ], + "responses": { + "204": { + "description": "Tags properly deleted" + }, + "403": { + "description": "The API key you used does not have permissions to delete tags.", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + }, + "examples": { + "API v3 and newer": { + "value": { + "detail": "You are not allowed to delete tags", + "title": "Forbidden tag operation", + "type": "https:\/\/shlink.io\/api\/error\/forbidden-tag-operation", + "status": 403 + } + }, + "Previous to API v3": { + "value": { + "detail": "You are not allowed to delete tags", + "title": "Forbidden tag operation", + "type": "FORBIDDEN_OPERATION", + "status": 403 + } + } + } + } + } + }, + "default": { + "description": "Unexpected error.", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKey": [] + } + ] + } + }, + "\/rest\/v{version}\/tags\/stats": { + "get": { + "tags": [ + "Tags" + ], + "summary": "Get tags with stats", + "description": "Returns the list of all tags used in any short URL, together with the amount of short URLs and visits for it", + "operationId": "tagsWithStats", + "parameters": [ + { + "name": "version", + "in": "path", + "description": "The API version to be consumed", + "required": true, + "schema": { + "enum": [ + "3", + "2", + "1" + ], + "type": "string" + } + }, + { + "name": "page", + "in": "query", + "description": "The page to display. Defaults to 1", + "required": false, + "schema": { + "type": "number" + } + }, + { + "name": "itemsPerPage", + "in": "query", + "description": "The amount of items to return on every page. Defaults to all the items", + "required": false, + "schema": { + "type": "number" + } + }, + { + "name": "searchTerm", + "in": "query", + "description": "A query used to filter results by searching for it on the tag name.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "orderBy", + "in": "query", + "description": "To determine how to order the results.

**Important!** Ordering by `shortUrlsCount`, `visits` or `nonBotVisits` has a [known performance issue](https:\/\/github.com\/shlinkio\/shlink\/issues\/1346) which makes loading a subset of the list take as much as loading the whole list.
If you plan to order by any of these fields, it's worth loading the whole list with no pagination.", + "required": false, + "schema": { + "enum": [ + "tag-ASC", + "tag-DESC", + "shortUrlsCount-ASC", + "shortUrlsCount-DESC", + "visits-ASC", + "visits-DESC", + "nonBotVisits-ASC", + "nonBotVisits-DESC" + ], + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The list of tags", + "content": { + "application\/json": { + "schema": { + "type": "object", + "properties": { + "tags": { + "required": [ + "data" + ], + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "required": [ + "tag", + "shortUrlsCount", + "visitsSummary" + ], + "type": "object", + "properties": { + "tag": { + "type": "string", + "description": "The unique tag name" + }, + "shortUrlsCount": { + "type": "number", + "description": "The amount of short URLs using this tag" + }, + "visitsSummary": { + "required": [ + "total", + "nonBots", + "bots" + ], + "type": "object", + "properties": { + "total": { + "type": "integer", + "description": "The total amount of visits." + }, + "nonBots": { + "type": "integer", + "description": "The amount of visits which were not identified as bots." + }, + "bots": { + "type": "integer", + "description": "The amount of visits that were identified as potential bots." + } + } + } + } + } + }, + "pagination": { + "type": "object", + "properties": { + "currentPage": { + "type": "integer", + "description": "The number of current page." + }, + "pagesCount": { + "type": "integer", + "description": "The total number of pages that can be obtained." + }, + "itemsPerPage": { + "type": "integer", + "description": "The number of items for every page." + }, + "itemsInCurrentPage": { + "type": "integer", + "description": "The number of items in current page (could be smaller than itemsPerPage)." + }, + "totalItems": { + "type": "integer", + "description": "The total number of items among all pages." + } + } + } + } + } + } + }, + "example": { + "tags": { + "data": [ + { + "tag": "games", + "shortUrlsCount": 10, + "visitsSummary": { + "total": 521, + "nonBots": 521, + "bots": 0 + } + }, + { + "tag": "shlink", + "shortUrlsCount": 7, + "visitsSummary": { + "total": 1087, + "nonBots": 1000, + "bots": 87 + } + } + ], + "pagination": { + "currentPage": 5, + "pagesCount": 5, + "itemsPerPage": 10, + "itemsInCurrentPage": 2, + "totalItems": 42 + } + } + } + } + } + }, + "default": { + "description": "Unexpected error.", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKey": [] + } + ] + } + }, + "\/rest\/v{version}\/visits": { + "get": { + "tags": [ + "Visits" + ], + "summary": "Get general visits stats", + "description": "Get general visits stats not linked to one specific short URL.", + "operationId": "getGlobalVisits", + "parameters": [ + { + "name": "version", + "in": "path", + "description": "The API version to be consumed", + "required": true, + "schema": { + "enum": [ + "3", + "2", + "1" + ], + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Visits stats.", + "content": { + "application\/json": { + "schema": { + "type": "object", + "properties": { + "visits": { + "required": [ + "nonOrphanVisits", + "orphanVisits" + ], + "type": "object", + "properties": { + "nonOrphanVisits": { + "required": [ + "total", + "nonBots", + "bots" + ], + "type": "object", + "properties": { + "total": { + "type": "integer", + "description": "The total amount of visits." + }, + "nonBots": { + "type": "integer", + "description": "The amount of visits which were not identified as bots." + }, + "bots": { + "type": "integer", + "description": "The amount of visits that were identified as potential bots." + } + } + }, + "orphanVisits": { + "required": [ + "total", + "nonBots", + "bots" + ], + "type": "object", + "properties": { + "total": { + "type": "integer", + "description": "The total amount of visits." + }, + "nonBots": { + "type": "integer", + "description": "The amount of visits which were not identified as bots." + }, + "bots": { + "type": "integer", + "description": "The amount of visits that were identified as potential bots." + } + } + } + } + } + } + }, + "example": { + "visits": { + "nonOrphanVisits": { + "total": 64994, + "nonBots": 64986, + "bots": 8 + }, + "orphanVisits": { + "total": 37, + "nonBots": 34, + "bots": 3 + } + } + } + } + } + }, + "default": { + "description": "Unexpected error.", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKey": [] + } + ] + } + }, + "\/rest\/v{version}\/short-urls\/{shortCode}\/visits": { + "get": { + "tags": [ + "Visits" + ], + "summary": "List visits for short URL", + "description": "Get the list of visits on the short URL behind provided short code.", + "operationId": "getShortUrlVisits", + "parameters": [ + { + "name": "version", + "in": "path", + "description": "The API version to be consumed", + "required": true, + "schema": { + "enum": [ + "3", + "2", + "1" + ], + "type": "string" + } + }, + { + "name": "shortCode", + "in": "path", + "description": "The short code for the short URL.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "domain", + "in": "query", + "description": "The domain in which the short code should be searched for.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "startDate", + "in": "query", + "description": "The date (in ISO-8601 format) from which we want to get visits.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "endDate", + "in": "query", + "description": "The date (in ISO-8601 format) until which we want to get visits.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "page", + "in": "query", + "description": "The page to display. Defaults to 1", + "required": false, + "schema": { + "type": "number" + } + }, + { + "name": "itemsPerPage", + "in": "query", + "description": "The amount of items to return on every page. Defaults to all the items", + "required": false, + "schema": { + "type": "number" + } + }, + { + "name": "excludeBots", + "in": "query", + "description": "Tells if visits from potential bots should be excluded from the result set", + "required": false, + "schema": { + "enum": [ + "true" + ], + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "List of visits.", + "content": { + "application\/json": { + "schema": { + "type": "object", + "properties": { + "visits": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "required": [ + "referer", + "date", + "userAgent", + "visitLocation", + "potentialBot", + "visitedUrl" + ], + "type": "object", + "properties": { + "referer": { + "type": "string", + "description": "The origin from which the visit was performed" + }, + "date": { + "type": "string", + "description": "The date in which the visit was performed", + "format": "date-time" + }, + "userAgent": { + "type": "string", + "description": "The user agent from which the visit was performed" + }, + "visitLocation": { + "type": "object", + "properties": { + "cityName": { + "type": "string" + }, + "countryCode": { + "type": "string" + }, + "countryName": { + "type": "string" + }, + "latitude": { + "type": "number" + }, + "longitude": { + "type": "number" + }, + "regionName": { + "type": "string" + }, + "timezone": { + "type": "string" + } + } + }, + "potentialBot": { + "type": "boolean", + "description": "Tells if Shlink thinks this visit comes potentially from a bot or crawler" + }, + "visitedUrl": { + "type": [ + "string", + "null" + ], + "description": "The originally visited URL that triggered the tracking of this visit" + } + } + } + }, + "pagination": { + "type": "object", + "properties": { + "currentPage": { + "type": "integer", + "description": "The number of current page." + }, + "pagesCount": { + "type": "integer", + "description": "The total number of pages that can be obtained." + }, + "itemsPerPage": { + "type": "integer", + "description": "The number of items for every page." + }, + "itemsInCurrentPage": { + "type": "integer", + "description": "The number of items in current page (could be smaller than itemsPerPage)." + }, + "totalItems": { + "type": "integer", + "description": "The total number of items among all pages." + } + } + } + } + } + } + }, + "example": { + "visits": { + "data": [ + { + "referer": "https:\/\/twitter.com", + "date": "2015-08-20T05:05:03+04:00", + "userAgent": "Mozilla\/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko\/20100101 Firefox\/47.0 Mozilla\/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko\/20100101 Firefox\/42.0", + "visitLocation": null, + "potentialBot": false, + "visitedUrl": "https:\/\/s.test" + }, + { + "referer": "https:\/\/t.co", + "date": "2015-08-20T05:05:03+04:00", + "userAgent": "Mozilla\/5.0 (X11; Linux x86_64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/51.0.2704.103 Safari\/537.36", + "visitLocation": { + "cityName": "Cupertino", + "countryCode": "US", + "countryName": "United States", + "latitude": 37.3042, + "longitude": -122.0946, + "regionName": "California", + "timezone": "America\/Los_Angeles" + }, + "potentialBot": false, + "visitedUrl": "https:\/\/s.test" + }, + { + "referer": null, + "date": "2015-08-20T05:05:03+04:00", + "userAgent": "some_web_crawler\/1.4", + "visitLocation": null, + "potentialBot": true, + "visitedUrl": "https:\/\/s.test" + } + ], + "pagination": { + "currentPage": 5, + "pagesCount": 12, + "itemsPerPage": 10, + "itemsInCurrentPage": 10, + "totalItems": 115 + } + } + } + } + } + }, + "404": { + "description": "The short code does not belong to any short URL.", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + }, + "examples": { + "Short URL not found": { + "value": { + "detail": "No URL found with short code \"abc123\"", + "title": "Short URL not found", + "type": "https:\/\/shlink.io\/api\/error\/short-url-not-found", + "status": 404, + "shortCode": "abc123" + } + } + } + } + } + }, + "default": { + "description": "Unexpected error.", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKey": [] + } + ] + }, + "delete": { + "tags": [ + "Visits" + ], + "summary": "Delete visits for short URL", + "description": "Delete all existing visits on the short URL behind provided short code.", + "operationId": "deleteShortUrlVisits", + "parameters": [ + { + "name": "version", + "in": "path", + "description": "The API version to be consumed", + "required": true, + "schema": { + "enum": [ + "3", + "2", + "1" + ], + "type": "string" + } + }, + { + "name": "shortCode", + "in": "path", + "description": "The short code for the short URL.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "domain", + "in": "query", + "description": "The domain in which the short code should be searched for.", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Deleted visits", + "content": { + "application\/json": { + "schema": { + "type": "object", + "properties": { + "deletedVisits": { + "type": "number", + "description": "Amount of affected visits" + } + } + }, + "example": { + "deletedVisits": 536 + } + } + } + }, + "404": { + "description": "The short code does not belong to any short URL.", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + }, + "examples": { + "Short URL not found": { + "value": { + "detail": "No URL found with short code \"abc123\"", + "title": "Short URL not found", + "type": "https:\/\/shlink.io\/api\/error\/short-url-not-found", + "status": 404, + "shortCode": "abc123" + } + } + } + } + } + }, + "default": { + "description": "Unexpected error.", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKey": [] + } + ] + } + }, + "\/rest\/v{version}\/tags\/{tag}\/visits": { + "get": { + "tags": [ + "Visits" + ], + "summary": "List visits for tag", + "description": "Get the list of visits on any short URL which is tagged with provided tag.", + "operationId": "getTagVisits", + "parameters": [ + { + "name": "version", + "in": "path", + "description": "The API version to be consumed", + "required": true, + "schema": { + "enum": [ + "3", + "2", + "1" + ], + "type": "string" + } + }, + { + "name": "tag", + "in": "path", + "description": "The tag from which we want to get the visits.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "startDate", + "in": "query", + "description": "The date (in ISO-8601 format) from which we want to get visits.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "endDate", + "in": "query", + "description": "The date (in ISO-8601 format) until which we want to get visits.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "page", + "in": "query", + "description": "The page to display. Defaults to 1", + "required": false, + "schema": { + "type": "number" + } + }, + { + "name": "itemsPerPage", + "in": "query", + "description": "The amount of items to return on every page. Defaults to all the items", + "required": false, + "schema": { + "type": "number" + } + }, + { + "name": "excludeBots", + "in": "query", + "description": "Tells if visits from potential bots should be excluded from the result set", + "required": false, + "schema": { + "enum": [ + "true" + ], + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "List of visits.", + "content": { + "application\/json": { + "schema": { + "type": "object", + "properties": { + "visits": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "required": [ + "referer", + "date", + "userAgent", + "visitLocation", + "potentialBot", + "visitedUrl" + ], + "type": "object", + "properties": { + "referer": { + "type": "string", + "description": "The origin from which the visit was performed" + }, + "date": { + "type": "string", + "description": "The date in which the visit was performed", + "format": "date-time" + }, + "userAgent": { + "type": "string", + "description": "The user agent from which the visit was performed" + }, + "visitLocation": { + "type": "object", + "properties": { + "cityName": { + "type": "string" + }, + "countryCode": { + "type": "string" + }, + "countryName": { + "type": "string" + }, + "latitude": { + "type": "number" + }, + "longitude": { + "type": "number" + }, + "regionName": { + "type": "string" + }, + "timezone": { + "type": "string" + } + } + }, + "potentialBot": { + "type": "boolean", + "description": "Tells if Shlink thinks this visit comes potentially from a bot or crawler" + }, + "visitedUrl": { + "type": [ + "string", + "null" + ], + "description": "The originally visited URL that triggered the tracking of this visit" + } + } + } + }, + "pagination": { + "type": "object", + "properties": { + "currentPage": { + "type": "integer", + "description": "The number of current page." + }, + "pagesCount": { + "type": "integer", + "description": "The total number of pages that can be obtained." + }, + "itemsPerPage": { + "type": "integer", + "description": "The number of items for every page." + }, + "itemsInCurrentPage": { + "type": "integer", + "description": "The number of items in current page (could be smaller than itemsPerPage)." + }, + "totalItems": { + "type": "integer", + "description": "The total number of items among all pages." + } + } + } + } + } + } + }, + "example": { + "visits": { + "data": [ + { + "referer": "https:\/\/twitter.com", + "date": "2015-08-20T05:05:03+04:00", + "userAgent": "Mozilla\/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko\/20100101 Firefox\/47.0 Mozilla\/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko\/20100101 Firefox\/42.0", + "visitLocation": null, + "potentialBot": false, + "visitedUrl": "https:\/\/s.test" + }, + { + "referer": "https:\/\/t.co", + "date": "2015-08-20T05:05:03+04:00", + "userAgent": "Mozilla\/5.0 (X11; Linux x86_64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/51.0.2704.103 Safari\/537.36", + "visitLocation": { + "cityName": "Cupertino", + "countryCode": "US", + "countryName": "United States", + "latitude": 37.3042, + "longitude": -122.0946, + "regionName": "California", + "timezone": "America\/Los_Angeles" + }, + "potentialBot": false, + "visitedUrl": "https:\/\/s.test" + }, + { + "referer": null, + "date": "2015-08-20T05:05:03+04:00", + "userAgent": "some_web_crawler\/1.4", + "visitLocation": null, + "potentialBot": true, + "visitedUrl": "https:\/\/s.test" + } + ], + "pagination": { + "currentPage": 5, + "pagesCount": 12, + "itemsPerPage": 10, + "itemsInCurrentPage": 10, + "totalItems": 115 + } + } + } + } + } + }, + "404": { + "description": "The tag does not exist.", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + }, + "examples": { + "Tag not found": { + "value": { + "detail": "Tag with name \"foo\" could not be found", + "title": "Tag not found", + "type": "https:\/\/shlink.io\/api\/error\/tag-not-found", + "status": 404, + "tag": "foo" + } + } + } + } + } + }, + "default": { + "description": "Unexpected error.", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKey": [] + } + ] + } + }, + "\/rest\/v{version}\/domains\/{domain}\/visits": { + "get": { + "tags": [ + "Visits" + ], + "summary": "List visits for domain", + "description": "Get the list of visits on any short URL which belongs to provided domain.", + "operationId": "getDomainVisits", + "parameters": [ + { + "name": "version", + "in": "path", + "description": "The API version to be consumed", + "required": true, + "schema": { + "enum": [ + "3", + "2", + "1" + ], + "type": "string" + } + }, + { + "name": "domain", + "in": "path", + "description": "The domain from which we want to get the visits, or **DEFAULT** keyword for default domain.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "startDate", + "in": "query", + "description": "The date (in ISO-8601 format) from which we want to get visits.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "endDate", + "in": "query", + "description": "The date (in ISO-8601 format) until which we want to get visits.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "page", + "in": "query", + "description": "The page to display. Defaults to 1", + "required": false, + "schema": { + "type": "number" + } + }, + { + "name": "itemsPerPage", + "in": "query", + "description": "The amount of items to return on every page. Defaults to all the items", + "required": false, + "schema": { + "type": "number" + } + }, + { + "name": "excludeBots", + "in": "query", + "description": "Tells if visits from potential bots should be excluded from the result set", + "required": false, + "schema": { + "enum": [ + "true" + ], + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "List of visits.", + "content": { + "application\/json": { + "schema": { + "type": "object", + "properties": { + "visits": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "required": [ + "referer", + "date", + "userAgent", + "visitLocation", + "potentialBot", + "visitedUrl" + ], + "type": "object", + "properties": { + "referer": { + "type": "string", + "description": "The origin from which the visit was performed" + }, + "date": { + "type": "string", + "description": "The date in which the visit was performed", + "format": "date-time" + }, + "userAgent": { + "type": "string", + "description": "The user agent from which the visit was performed" + }, + "visitLocation": { + "type": "object", + "properties": { + "cityName": { + "type": "string" + }, + "countryCode": { + "type": "string" + }, + "countryName": { + "type": "string" + }, + "latitude": { + "type": "number" + }, + "longitude": { + "type": "number" + }, + "regionName": { + "type": "string" + }, + "timezone": { + "type": "string" + } + } + }, + "potentialBot": { + "type": "boolean", + "description": "Tells if Shlink thinks this visit comes potentially from a bot or crawler" + }, + "visitedUrl": { + "type": [ + "string", + "null" + ], + "description": "The originally visited URL that triggered the tracking of this visit" + } + } + } + }, + "pagination": { + "type": "object", + "properties": { + "currentPage": { + "type": "integer", + "description": "The number of current page." + }, + "pagesCount": { + "type": "integer", + "description": "The total number of pages that can be obtained." + }, + "itemsPerPage": { + "type": "integer", + "description": "The number of items for every page." + }, + "itemsInCurrentPage": { + "type": "integer", + "description": "The number of items in current page (could be smaller than itemsPerPage)." + }, + "totalItems": { + "type": "integer", + "description": "The total number of items among all pages." + } + } + } + } + } + } + }, + "example": { + "visits": { + "data": [ + { + "referer": "https:\/\/twitter.com", + "date": "2015-08-20T05:05:03+04:00", + "userAgent": "Mozilla\/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko\/20100101 Firefox\/47.0 Mozilla\/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko\/20100101 Firefox\/42.0", + "visitLocation": null, + "potentialBot": false, + "visitedUrl": "https:\/\/s.test" + }, + { + "referer": "https:\/\/t.co", + "date": "2015-08-20T05:05:03+04:00", + "userAgent": "Mozilla\/5.0 (X11; Linux x86_64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/51.0.2704.103 Safari\/537.36", + "visitLocation": { + "cityName": "Cupertino", + "countryCode": "US", + "countryName": "United States", + "latitude": 37.3042, + "longitude": -122.0946, + "regionName": "California", + "timezone": "America\/Los_Angeles" + }, + "potentialBot": false, + "visitedUrl": "https:\/\/s.test" + }, + { + "referer": null, + "date": "2015-08-20T05:05:03+04:00", + "userAgent": "some_web_crawler\/1.4", + "visitLocation": null, + "potentialBot": true, + "visitedUrl": "https:\/\/s.test" + } + ], + "pagination": { + "currentPage": 5, + "pagesCount": 12, + "itemsPerPage": 10, + "itemsInCurrentPage": 10, + "totalItems": 115 + } + } + } + } + } + }, + "404": { + "description": "The domain does not exist.", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + }, + "examples": { + "API v3 and newer": { + "value": { + "detail": "Domain with authority \"example.com\" could not be found", + "title": "Domain not found", + "type": "https:\/\/shlink.io\/api\/error\/domain-not-found", + "status": 404, + "authority": "example.com" + } + }, + "Previous to API v3": { + "value": { + "detail": "Domain with authority \"example.com\" could not be found", + "title": "Domain not found", + "type": "DOMAIN_NOT_FOUND", + "status": 404, + "authority": "example.com" + } + } + } + } + } + }, + "default": { + "description": "Unexpected error.", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKey": [] + } + ] + } + }, + "\/rest\/v{version}\/visits\/orphan": { + "get": { + "tags": [ + "Visits" + ], + "summary": "List orphan visits", + "description": "Get the list of visits to invalid short URLs, the base URL or any other 404.", + "operationId": "getOrphanVisits", + "parameters": [ + { + "name": "version", + "in": "path", + "description": "The API version to be consumed", + "required": true, + "schema": { + "enum": [ + "3", + "2", + "1" + ], + "type": "string" + } + }, + { + "name": "startDate", + "in": "query", + "description": "The date (in ISO-8601 format) from which we want to get visits.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "endDate", + "in": "query", + "description": "The date (in ISO-8601 format) until which we want to get visits.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "page", + "in": "query", + "description": "The page to display. Defaults to 1", + "required": false, + "schema": { + "type": "number" + } + }, + { + "name": "itemsPerPage", + "in": "query", + "description": "The amount of items to return on every page. Defaults to all the items", + "required": false, + "schema": { + "type": "number" + } + }, + { + "name": "excludeBots", + "in": "query", + "description": "Tells if visits from potential bots should be excluded from the result set", + "required": false, + "schema": { + "enum": [ + "true" + ], + "type": "string" + } + }, + { + "name": "type", + "in": "query", + "description": "The type of visits to return. All visits are returned when not provided.", + "required": false, + "schema": { + "enum": [ + "invalid_short_url", + "base_url", + "regular_404" + ], + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "List of visits.", + "content": { + "application\/json": { + "schema": { + "type": "object", + "properties": { + "visits": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "required": [ + "type" + ], + "type": "object", + "allOf": [ + { + "required": [ + "referer", + "date", + "userAgent", + "visitLocation", + "potentialBot", + "visitedUrl" + ], + "type": "object", + "properties": { + "referer": { + "type": "string", + "description": "The origin from which the visit was performed" + }, + "date": { + "type": "string", + "description": "The date in which the visit was performed", + "format": "date-time" + }, + "userAgent": { + "type": "string", + "description": "The user agent from which the visit was performed" + }, + "visitLocation": { + "type": "object", + "properties": { + "cityName": { + "type": "string" + }, + "countryCode": { + "type": "string" + }, + "countryName": { + "type": "string" + }, + "latitude": { + "type": "number" + }, + "longitude": { + "type": "number" + }, + "regionName": { + "type": "string" + }, + "timezone": { + "type": "string" + } + } + }, + "potentialBot": { + "type": "boolean", + "description": "Tells if Shlink thinks this visit comes potentially from a bot or crawler" + }, + "visitedUrl": { + "type": [ + "string", + "null" + ], + "description": "The originally visited URL that triggered the tracking of this visit" + } + } + } + ], + "properties": { + "type": { + "enum": [ + "invalid_short_url", + "base_url", + "regular_404" + ], + "type": "string", + "description": "Tells the type of orphan visit" + } + } + } + }, + "pagination": { + "type": "object", + "properties": { + "currentPage": { + "type": "integer", + "description": "The number of current page." + }, + "pagesCount": { + "type": "integer", + "description": "The total number of pages that can be obtained." + }, + "itemsPerPage": { + "type": "integer", + "description": "The number of items for every page." + }, + "itemsInCurrentPage": { + "type": "integer", + "description": "The number of items in current page (could be smaller than itemsPerPage)." + }, + "totalItems": { + "type": "integer", + "description": "The total number of items among all pages." + } + } + } + } + } + } + }, + "example": { + "visits": { + "data": [ + { + "referer": "https:\/\/twitter.com", + "date": "2015-08-20T05:05:03+04:00", + "userAgent": "Mozilla\/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko\/20100101 Firefox\/47.0 Mozilla\/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko\/20100101 Firefox\/42.0", + "visitLocation": null, + "potentialBot": false, + "visitedUrl": "https:\/\/s.test", + "type": "base_url" + }, + { + "referer": "https:\/\/t.co", + "date": "2015-08-20T05:05:03+04:00", + "userAgent": "Mozilla\/5.0 (X11; Linux x86_64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/51.0.2704.103 Safari\/537.36", + "visitLocation": { + "cityName": "Cupertino", + "countryCode": "US", + "countryName": "United States", + "latitude": 37.3042, + "longitude": -122.0946, + "regionName": "California", + "timezone": "America\/Los_Angeles" + }, + "potentialBot": false, + "visitedUrl": "https:\/\/s.test\/foo", + "type": "invalid_short_url" + }, + { + "referer": null, + "date": "2015-08-20T05:05:03+04:00", + "userAgent": "some_web_crawler\/1.4", + "visitLocation": null, + "potentialBot": true, + "visitedUrl": "https:\/\/s.test\/foo\/bar\/baz", + "type": "regular_404" + } + ], + "pagination": { + "currentPage": 5, + "pagesCount": 12, + "itemsPerPage": 10, + "itemsInCurrentPage": 10, + "totalItems": 115 + } + } + } + } + } + }, + "400": { + "description": "Provided query arguments are invalid.", + "content": { + "application\/problem+json": { + "schema": { + "type": "object", + "allOf": [ + { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + }, + { + "required": [ + "invalidElements" + ], + "type": "object", + "properties": { + "invalidElements": { + "type": "array", + "items": { + "enum": [ + "type" + ], + "type": "string" + } + } + } + } + ] + }, + "examples": { + "API v3 and newer": { + "value": { + "title": "Invalid data", + "type": "https:\/\/shlink.io\/api\/error\/invalid-data", + "detail": "Provided data is not valid", + "status": 400, + "invalidElements": [ + "type" + ] + } + }, + "Previous to API v3": { + "value": { + "title": "Invalid data", + "type": "INVALID_ARGUMENT", + "detail": "Provided data is not valid", + "status": 400, + "invalidElements": [ + "type" + ] + } + } + } + } + } + }, + "default": { + "description": "Unexpected error.", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKey": [] + } + ] + }, + "delete": { + "tags": [ + "Visits" + ], + "summary": "Delete orphan visits", + "description": "Delete all visits to invalid short URLs, the base URL or any other 404.", + "operationId": "deleteOrphanVisits", + "parameters": [ + { + "name": "version", + "in": "path", + "description": "The API version to be consumed", + "required": true, + "schema": { + "enum": [ + "3", + "2", + "1" + ], + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Deleted visits", + "content": { + "application\/json": { + "schema": { + "type": "object", + "properties": { + "deletedVisits": { + "type": "number", + "description": "Amount of affected visits" + } + } + }, + "example": { + "deletedVisits": 536 + } + } + } + }, + "default": { + "description": "Unexpected error.", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKey": [] + } + ] + } + }, + "\/rest\/v{version}\/visits\/non-orphan": { + "get": { + "tags": [ + "Visits" + ], + "summary": "List non-orphan visits", + "description": "Get the list of visits to any short URL.", + "operationId": "getNonOrphanVisits", + "parameters": [ + { + "name": "version", + "in": "path", + "description": "The API version to be consumed", + "required": true, + "schema": { + "enum": [ + "3", + "2", + "1" + ], + "type": "string" + } + }, + { + "name": "startDate", + "in": "query", + "description": "The date (in ISO-8601 format) from which we want to get visits.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "endDate", + "in": "query", + "description": "The date (in ISO-8601 format) until which we want to get visits.", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "page", + "in": "query", + "description": "The page to display. Defaults to 1", + "required": false, + "schema": { + "type": "number" + } + }, + { + "name": "itemsPerPage", + "in": "query", + "description": "The amount of items to return on every page. Defaults to all the items", + "required": false, + "schema": { + "type": "number" + } + }, + { + "name": "excludeBots", + "in": "query", + "description": "Tells if visits from potential bots should be excluded from the result set", + "required": false, + "schema": { + "enum": [ + "true" + ], + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "List of visits.", + "content": { + "application\/json": { + "schema": { + "type": "object", + "properties": { + "visits": { + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "required": [ + "referer", + "date", + "userAgent", + "visitLocation", + "potentialBot", + "visitedUrl" + ], + "type": "object", + "properties": { + "referer": { + "type": "string", + "description": "The origin from which the visit was performed" + }, + "date": { + "type": "string", + "description": "The date in which the visit was performed", + "format": "date-time" + }, + "userAgent": { + "type": "string", + "description": "The user agent from which the visit was performed" + }, + "visitLocation": { + "type": "object", + "properties": { + "cityName": { + "type": "string" + }, + "countryCode": { + "type": "string" + }, + "countryName": { + "type": "string" + }, + "latitude": { + "type": "number" + }, + "longitude": { + "type": "number" + }, + "regionName": { + "type": "string" + }, + "timezone": { + "type": "string" + } + } + }, + "potentialBot": { + "type": "boolean", + "description": "Tells if Shlink thinks this visit comes potentially from a bot or crawler" + }, + "visitedUrl": { + "type": [ + "string", + "null" + ], + "description": "The originally visited URL that triggered the tracking of this visit" + } + } + } + }, + "pagination": { + "type": "object", + "properties": { + "currentPage": { + "type": "integer", + "description": "The number of current page." + }, + "pagesCount": { + "type": "integer", + "description": "The total number of pages that can be obtained." + }, + "itemsPerPage": { + "type": "integer", + "description": "The number of items for every page." + }, + "itemsInCurrentPage": { + "type": "integer", + "description": "The number of items in current page (could be smaller than itemsPerPage)." + }, + "totalItems": { + "type": "integer", + "description": "The total number of items among all pages." + } + } + } + } + } + } + }, + "example": { + "visits": { + "data": [ + { + "referer": "https:\/\/twitter.com", + "date": "2015-08-20T05:05:03+04:00", + "userAgent": "Mozilla\/5.0 (Windows NT 6.1; Win64; x64; rv:47.0) Gecko\/20100101 Firefox\/47.0 Mozilla\/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko\/20100101 Firefox\/42.0", + "visitLocation": null, + "potentialBot": false, + "visitedUrl": "https:\/\/s.test" + }, + { + "referer": "https:\/\/t.co", + "date": "2015-08-20T05:05:03+04:00", + "userAgent": "Mozilla\/5.0 (X11; Linux x86_64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/51.0.2704.103 Safari\/537.36", + "visitLocation": { + "cityName": "Cupertino", + "countryCode": "US", + "countryName": "United States", + "latitude": 37.3042, + "longitude": -122.0946, + "regionName": "California", + "timezone": "America\/Los_Angeles" + }, + "potentialBot": false, + "visitedUrl": "https:\/\/s.test" + }, + { + "referer": null, + "date": "2015-08-20T05:05:03+04:00", + "userAgent": "some_web_crawler\/1.4", + "visitLocation": null, + "potentialBot": true, + "visitedUrl": "https:\/\/s.test" + } + ], + "pagination": { + "currentPage": 5, + "pagesCount": 12, + "itemsPerPage": 10, + "itemsInCurrentPage": 10, + "totalItems": 115 + } + } + } + } + } + }, + "default": { + "description": "Unexpected error.", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKey": [] + } + ] + } + }, + "\/rest\/v{version}\/domains": { + "get": { + "tags": [ + "Domains" + ], + "summary": "List configured domains", + "description": "Returns the list of all domains that have been either used for some short URL, or have explicitly configured redirects.It also includes the domain redirects, plus the default redirects that will be used for any non-explicitly-configured one.", + "operationId": "listDomains", + "parameters": [ + { + "name": "version", + "in": "path", + "description": "The API version to be consumed", + "required": true, + "schema": { + "enum": [ + "3", + "2", + "1" + ], + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The list of domains", + "content": { + "application\/json": { + "schema": { + "required": [ + "domains" + ], + "type": "object", + "properties": { + "domains": { + "required": [ + "data" + ], + "type": "object", + "properties": { + "data": { + "type": "array", + "items": { + "required": [ + "domain", + "isDefault", + "redirects" + ], + "type": "object", + "properties": { + "domain": { + "type": "string" + }, + "isDefault": { + "type": "boolean" + }, + "redirects": { + "type": "object", + "properties": { + "baseUrlRedirect": { + "type": [ + "string", + "null" + ], + "description": "URL to redirect to when a user hits the domain's base URL" + }, + "regular404Redirect": { + "type": [ + "string", + "null" + ], + "description": "URL to redirect to when a user hits a not found URL other than an invalid short URL" + }, + "invalidShortUrlRedirect": { + "type": [ + "string", + "null" + ], + "description": "URL to redirect to when a user hits an invalid short URL" + } + } + } + } + } + }, + "defaultRedirects": { + "type": "object", + "properties": { + "baseUrlRedirect": { + "type": [ + "string", + "null" + ], + "description": "URL to redirect to when a user hits the domain's base URL" + }, + "regular404Redirect": { + "type": [ + "string", + "null" + ], + "description": "URL to redirect to when a user hits a not found URL other than an invalid short URL" + }, + "invalidShortUrlRedirect": { + "type": [ + "string", + "null" + ], + "description": "URL to redirect to when a user hits an invalid short URL" + } + } + } + } + } + } + }, + "example": { + "domains": { + "data": [ + { + "domain": "example.com", + "isDefault": true, + "redirects": { + "baseUrlRedirect": "https:\/\/example.com\/my-landing-page", + "regular404Redirect": null, + "invalidShortUrlRedirect": "https:\/\/example.com\/invalid-url" + } + }, + { + "domain": "aaa.com", + "isDefault": false, + "redirects": { + "baseUrlRedirect": null, + "regular404Redirect": null, + "invalidShortUrlRedirect": null + } + }, + { + "domain": "bbb.com", + "isDefault": false, + "redirects": { + "baseUrlRedirect": null, + "regular404Redirect": null, + "invalidShortUrlRedirect": "https:\/\/example.com\/invalid-url" + } + } + ], + "defaultRedirects": { + "baseUrlRedirect": "https:\/\/somewhere.com", + "regular404Redirect": null, + "invalidShortUrlRedirect": null + } + } + } + } + } + }, + "default": { + "description": "Unexpected error.", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKey": [] + } + ] + } + }, + "\/rest\/v{version}\/domains\/redirects": { + "patch": { + "tags": [ + "Domains" + ], + "summary": "Sets domain \"not found\" redirects", + "description": "Sets the URLs that you want a visitor to get redirected to for \"not found\" URLs for a specific domain", + "operationId": "setDomainRedirects", + "parameters": [ + { + "name": "version", + "in": "path", + "description": "The API version to be consumed", + "required": true, + "schema": { + "enum": [ + "3", + "2", + "1" + ], + "type": "string" + } + } + ], + "requestBody": { + "description": "Request body.", + "content": { + "application\/json": { + "schema": { + "type": "object", + "allOf": [ + { + "required": [ + "domain" + ], + "properties": { + "domain": { + "type": "string", + "description": "The domain's authority for which you want to set redirects" + } + } + }, + { + "type": "object", + "properties": { + "baseUrlRedirect": { + "type": [ + "string", + "null" + ], + "description": "URL to redirect to when a user hits the domain's base URL" + }, + "regular404Redirect": { + "type": [ + "string", + "null" + ], + "description": "URL to redirect to when a user hits a not found URL other than an invalid short URL" + }, + "invalidShortUrlRedirect": { + "type": [ + "string", + "null" + ], + "description": "URL to redirect to when a user hits an invalid short URL" + } + } + } + ] + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "The domain's redirects after the update, when existing redirects have been merged with provided ones.", + "content": { + "application\/json": { + "schema": { + "allOf": [ + { + "required": [ + "baseUrlRedirect", + "regular404Redirect", + "invalidShortUrlRedirect" + ] + }, + { + "type": "object", + "properties": { + "baseUrlRedirect": { + "type": [ + "string", + "null" + ], + "description": "URL to redirect to when a user hits the domain's base URL" + }, + "regular404Redirect": { + "type": [ + "string", + "null" + ], + "description": "URL to redirect to when a user hits a not found URL other than an invalid short URL" + }, + "invalidShortUrlRedirect": { + "type": [ + "string", + "null" + ], + "description": "URL to redirect to when a user hits an invalid short URL" + } + } + } + ] + }, + "example": { + "baseUrlRedirect": "https:\/\/example.com\/my-landing-page", + "regular404Redirect": null, + "invalidShortUrlRedirect": "https:\/\/example.com\/invalid-url" + } + } + } + }, + "400": { + "description": "Provided data is invalid.", + "content": { + "application\/problem+json": { + "schema": { + "type": "object", + "allOf": [ + { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + }, + { + "required": [ + "invalidElements" + ], + "type": "object", + "properties": { + "invalidElements": { + "type": "array", + "items": { + "enum": [ + "domain", + "baseUrlRedirect", + "regular404Redirect", + "invalidShortUrlRedirect" + ], + "type": "string" + } + } + } + } + ] + }, + "examples": { + "API v3 and newer": { + "value": { + "title": "Invalid data", + "type": "https:\/\/shlink.io\/api\/error\/invalid-data", + "detail": "Provided data is not valid", + "status": 400, + "invalidElements": [ + "domain", + "invalidShortUrlRedirect" + ] + } + }, + "Previous to API v3": { + "value": { + "title": "Invalid data", + "type": "INVALID_ARGUMENT", + "detail": "Provided data is not valid", + "status": 400, + "invalidElements": [ + "domain", + "invalidShortUrlRedirect" + ] + } + } + } + } + } + }, + "default": { + "description": "Unexpected error.", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKey": [] + } + ] + } + }, + "\/rest\/v{version}\/mercure-info": { + "get": { + "tags": [ + "Integrations" + ], + "summary": "Get mercure integration info", + "description": "Returns information to consume updates published by Shlink on a mercure hub. https:\/\/mercure.rocks\/", + "operationId": "mercureInfo", + "parameters": [ + { + "name": "version", + "in": "path", + "description": "The API version to be consumed", + "required": true, + "schema": { + "enum": [ + "3", + "2", + "1" + ], + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "The mercure integration info", + "content": { + "application\/json": { + "schema": { + "required": [ + "mercureHubUrl", + "jwt", + "jwtExpiration" + ], + "type": "object", + "properties": { + "mercureHubUrl": { + "type": "string", + "description": "The public URL of the mercure hub that can be used to get real-time updates published by Shlink" + }, + "jwt": { + "type": "string", + "description": "A JWT with subscribe permissions which is valid with the mercure hub" + }, + "jwtExpiration": { + "type": "string", + "description": "The date (in ISO-8601 format) in which the JWT will expire" + } + } + }, + "example": { + "mercureHubUrl": "https:\/\/example.com\/.well-known\/mercure", + "jwt": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJTaGxpbmsiLCJpYXQiOjE1ODY2ODY3MzIsImV4cCI6MTU4Njk0NTkzMiwibWVyY3VyZSI6eyJzdWJzY3JpYmUiOltdfX0.P-519lgU7dFz0bbNlRG1CXyqugGbaHon4kw6fu4QBdQ", + "jwtExpiration": "2020-04-15T12:18:52+02:00" + } + } + } + }, + "501": { + "description": "This Shlink instance is not integrated with a mercure hub", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + }, + "examples": { + "API v3 and newer": { + "value": { + "title": "Mercure integration not configured", + "type": "https:\/\/shlink.io\/api\/error\/mercure-not-configured", + "detail": "This Shlink instance is not integrated with a mercure hub.", + "status": 501 + } + }, + "Previous to API v3": { + "value": { + "title": "Mercure integration not configured", + "type": "MERCURE_NOT_CONFIGURED", + "detail": "This Shlink instance is not integrated with a mercure hub.", + "status": 501 + } + } + } + } + } + }, + "default": { + "description": "Unexpected error.", + "content": { + "application\/problem+json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + } + } + } + } + }, + "security": [ + { + "ApiKey": [] + } + ] + } + }, + "\/rest\/health": { + "get": { + "tags": [ + "Monitoring" + ], + "summary": "Check healthiness", + "description": "Checks the healthiness of the service, making sure it can access required resources.", + "operationId": "health", + "responses": { + "200": { + "description": "The passing health status", + "content": { + "application\/json": { + "schema": { + "type": "object", + "properties": { + "status": { + "enum": [ + "pass", + "fail" + ], + "type": "string", + "description": "The status of the service" + }, + "version": { + "type": "string", + "description": "Shlink version" + }, + "links": { + "type": "object", + "properties": { + "about": { + "type": "string", + "description": "About shlink" + }, + "project": { + "type": "string", + "description": "Shlink project repository" + } + }, + "description": "A list of links" + } + } + }, + "example": { + "status": "pass", + "version": "2.10.0", + "links": { + "about": "https:\/\/shlink.io", + "project": "https:\/\/github.com\/shlinkio\/shlink" + } + } + } + } + }, + "503": { + "description": "The failing health status", + "content": { + "application\/json": { + "schema": { + "type": "object", + "properties": { + "status": { + "enum": [ + "pass", + "fail" + ], + "type": "string", + "description": "The status of the service" + }, + "version": { + "type": "string", + "description": "Shlink version" + }, + "links": { + "type": "object", + "properties": { + "about": { + "type": "string", + "description": "About shlink" + }, + "project": { + "type": "string", + "description": "Shlink project repository" + } + }, + "description": "A list of links" + } + } + }, + "example": { + "status": "fail", + "version": "2.10.0", + "links": { + "about": "https:\/\/shlink.io", + "project": "https:\/\/github.com\/shlinkio\/shlink" + } + } + } + } + }, + "default": { + "description": "Unexpected error.", + "content": { + "application\/json": { + "schema": { + "required": [ + "type", + "title", + "detail", + "status" + ], + "type": "object", + "properties": { + "type": { + "type": "string", + "description": "A machine unique code" + }, + "title": { + "type": "string", + "description": "A unique title" + }, + "detail": { + "type": "string", + "description": "A human-friendly error description" + }, + "status": { + "type": "number", + "description": "HTTP response status code" + } + } + } + } + } + } + } + } + }, + "\/{shortCode}": { + "get": { + "tags": [ + "URL Shortener" + ], + "summary": "Short URL", + "description": "Represents a short URL. Tracks the visit and redirects tio the corresponding long URL", + "operationId": "shortUrl", + "parameters": [ + { + "name": "shortCode", + "in": "path", + "description": "The short code for the short URL.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "302": { + "description": "Visit properly tracked and redirected" + } + } + } + }, + "\/{shortCode}\/track": { + "get": { + "tags": [ + "URL Shortener" + ], + "summary": "Short URL tracking pixel", + "description": "Generates a 1px transparent image which can be used to track emails with a short URL", + "operationId": "trackShortUrl", + "parameters": [ + { + "name": "shortCode", + "in": "path", + "description": "The short code for the short URL.", + "required": true, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Image in GIF format", + "content": { + "image\/gif": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + } + } + } + }, + "\/{shortCode}\/qr-code": { + "get": { + "tags": [ + "URL Shortener" + ], + "summary": "Short URL QR code", + "description": "Generates a QR code image pointing to a short URL.
Since this is not an API endpoint but an image one, when an invalid value is provided for any of the query params, they will fall to their default values instead of throwing an error.", + "operationId": "shortUrlQrCode", + "parameters": [ + { + "name": "shortCode", + "in": "path", + "description": "The short code for the short URL.", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "size", + "in": "query", + "description": "The size of the image to be returned.", + "required": false, + "schema": { + "maximum": 1000, + "minimum": 50, + "type": "integer", + "default": 300 + } + }, + { + "name": "format", + "in": "query", + "description": "The format for the QR code image, being valid values png and svg. Not providing the param or providing any other value will fall back to png.", + "required": false, + "schema": { + "enum": [ + "png", + "svg" + ], + "type": "string", + "default": "png" + } + }, + { + "name": "margin", + "in": "query", + "description": "The margin around the QR code image.", + "required": false, + "schema": { + "minimum": 0, + "type": "integer", + "default": 0 + } + }, + { + "name": "errorCorrection", + "in": "query", + "description": "The error correction level to apply to the QR code: **[L]**ow, **[M]**edium, **[Q]**uartile or **[H]**igh. See [docs](https:\/\/www.qrcode.com\/en\/about\/error_correction.html).", + "required": false, + "schema": { + "enum": [ + "L", + "M", + "Q", + "H" + ], + "type": "string", + "default": "L" + } + }, + { + "name": "roundBlockSize", + "in": "query", + "description": "Allows to disable block size rounding, which might reduce the readability of the QR code, but ensures no extra margin is added.", + "required": false, + "schema": { + "enum": [ + "true", + "false" + ], + "type": "string", + "default": "false" + } + }, + { + "name": "color", + "in": "query", + "description": "The QR code foreground color. It should be an hex representation of a color, in 3 or 6 characters, optionally preceded by the \"#\" character.", + "required": false, + "schema": { + "type": "string", + "default": "#000000" + } + }, + { + "name": "bgColor", + "in": "query", + "description": "The QR code background color. It should be an hex representation of a color, in 3 or 6 characters, optionally preceded by the \"#\" character.", + "required": false, + "schema": { + "type": "string", + "default": "#ffffff" + } + } + ], + "responses": { + "200": { + "description": "QR code in PNG format", + "content": { + "image\/png": { + "schema": { + "type": "string", + "format": "binary" + } + }, + "image\/svg+xml": { + "schema": { + "type": "string", + "format": "binary" + } + } + } + } + } + } + } + }, + "components": { + "securitySchemes": { + "ApiKey": { + "type": "apiKey", + "description": "A valid shlink API key", + "name": "X-Api-Key", + "in": "header" + } + } + }, + "tags": [ + { + "name": "Short URLs", + "description": "Operations that can be performed on short URLs" + }, + { + "name": "Redirect rules", + "description": "Handle dynamic rule-based redirects" + }, + { + "name": "Tags", + "description": "Let you handle the list of available tags" + }, + { + "name": "Visits", + "description": "Operations to manage visits on short URLs" + }, + { + "name": "Domains", + "description": "Operations to manage domains used on short URLs" + }, + { + "name": "Integrations", + "description": "Handle services with which shlink is integrated" + }, + { + "name": "Monitoring", + "description": "Public endpoints designed to monitor the service" + }, + { + "name": "URL Shortener", + "description": "Non-rest endpoints, used to be publicly exposed" + } + ], + "externalDocs": { + "description": "Find more info on how to start using this API here", + "url": "https:\/\/shlink.io\/documentation\/api-docs" + } +} \ No newline at end of file