openapi-directory/api/shorten.rest.json

Building & bundling https://github.com/APIs-guru/openapi-directory for easy use from JS

{"openapi":"3.0.0","servers":[{"url":"https://api.shorten.rest"}],"info":{"description":"## Introduction\n\n\nThe Shorten.rest API allows you to programmatically create short URLs (an 'alias') for longer URL (a 'destination').\n\nEach alias you create can be used to redirect the end user (person clicking on the link) to one or more destination URLs\n\nA default destination is always set and specific destinations can be set to redirect the end user to preferred destinations based on the user's geographical location (country) and device Operating System.\n\nIn order to use the Shorten.Rest URL Shortening API you can choose to bind your own branded domain, sub-domain or to use our default domain - Short.FYI \n\n ### Destination Matching \n\n When creating or editing a short URL ('alias') you can choose to specify a destination for each country and OS ([Supported OSes list](#tag/OperatingSystems)) combination. \n\n When a user clicks on the short link, Shorten.rest will examine the end user's country (determined by User's IP) and OS (User agent) and match the most suitable destination for each user. \n\n (*) If no destination is set for a specific request combination Shorten.rest will use the default destination that exists within each short URL \n\n (**) BRANDED DOMAINS: If the requested alias does not exist in our database - Shorten.rest will redirect the user to the default fallback you set within your dashboard under the ‘Alias Not Found Page Url’ value for a custom domain. \n\n (***) Operating System (OS) destinations are stronger than a country destination! \n For example - if you have a custom landing page that is targeting people in the USA and a second landing page that is hyper focused for people who use iOS devices - a person clicking on your link in the USA that is on an iPhone will be redirected to the iOS landing page, while all other devices will be redirected to the USA landing page. \n\n | OS  | Country  | Destination |\n| :------------: |:---------------:| -----|\n| iOS      |  | YourDestination.com/ios |\n|       | US        |   YourDestination.com/usa | \n\n Shorten.rest will choose the YourDestination.com/ios url as the most suitable destination.\n\n ### Branded Domain Attributes \n\n When setting up your custom domain you can include optional metatags and snippets ([Supported snippets list](#tag/Snippets)). These parameters (such as retargeting, tracking and conversion pixels) are populated and fired on click - at the time of the redirect. \n\n By default the parameters you set in the domain setting will be included in all Short URLs associated with that domain. \n\n You can always override the domain defaults for each URL by passing the appropriate variables when creating or updating a short URL \n\n ### Setting a Custom string for an Alias (short.fyi/alias) \n\n While creating a short URL you can specify which domain to use. You can choose to use your own branded domain or our default domain - Short.fyi. \n\n Each Alias is unique within a domain they are related to. This means that if multiple accounts use you the same domain (for example short.fyi), if an alias is already taken you may not create a new destination for it.\n\n That said - If you would like to use a specific alias which is already taken - the only way to do so is to create it on a new domain you own and have attached to your Shorten.rest account. \n\n ### Random Aliases \n\n By default - unless you specify a vanity URI for your alias each URL that is shortened on our platform will have a random string generated by the API. This means that if the 'alias' attribute of a /aliases POST request is not provided, or is an empty string, a random string of seven characters will be generated and returned as part of the POST response. \n\n You can also place the @**rnd** macro within the alias field when you create a new alias, for example /vanity/@rnd, which might return an alias like /vanity/ZMAefRt, or /vanity@rnd, which might produce something like /vanityMRtvxadf. Only the first @rnd in an alias attribute will be replaced. \n\n ### NOTES \n\n ( * ) All methods of the Shorten.REST API require that your API key be provided in **x-api-key** header. \n\n (**) All API parameters are case sensitive","title":"Shorten.REST API Documentation","version":"1.0.0","x-apisguru-categories":["developer_tools"],"x-logo":{"backgroundColor":"rgb(236, 236, 236)","href":"https://shorten.rest","url":"https://docs.shorten.rest/assets/logo.png"},"x-origin":[{"format":"openapi","url":"https://docs.shorten.rest/swagger.json","version":"3.0"}],"x-providerName":"shorten.rest"},"externalDocs":{"description":"Visit main site","url":"https://shorten.rest"},"tags":[{"description":"**Operations:** Create, Get, Update, Delete, Get List","name":"Alias"},{"description":"**Operations:** Get List","name":"Click"}],"paths":{"/aliases":{"delete":{"description":"Deletes a single alias by providing alias and domain. If no domain is provided the API will search for the matching alias within the Short.fyi domain","operationId":"DeleteAlias","parameters":[{"description":"domain which alias belongs to (string without `http/https` or `/`)","example":"your.domain.com","in":"query","name":"domainName","required":false,"schema":{"default":"short.fyi","type":"string"}},{"description":"alias (without `/` at the beginning)","example":"aBcDe012","in":"query","name":"aliasName","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Empty response"}},"security":[{"ApiKeyAuth":[]}],"summary":"Delete alias","tags":["Alias"]},"get":{"description":"Get detailed information for a single alias by providing its alias and domain name","operationId":"GetAlias","parameters":[{"description":"domain which alias belongs to (string without `http/https` or `/`)","example":"your.domain.com","in":"query","name":"domainName","required":false,"schema":{"default":"short.fyi","type":"string"}},{"description":"alias value (without `/` at the beginning)","example":"aBcDe012","in":"query","name":"aliasName","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AliasModel"}}},"description":"Alias model or **null**"}},"security":[{"ApiKeyAuth":[]}],"summary":"Get alias","tags":["Alias"]},"post":{"description":"This POST method creates a new alias under a specified domain. If no domain is specified in the request the alias will be attached to the default domain Short.fyi \n\n **NOTE:** You can override the domain level Meta Tags and Tracking Snippets by specifying them for each URL. Any variables you add to a specific URL will always override domain level settings.","operationId":"CreateAlias","parameters":[{"description":"domain which alias will belong to (string without `http/https` or `/`)","example":"your.domain.com","in":"query","name":"domainName","required":false,"schema":{"default":"short.fyi","type":"string"}},{"description":"alias (without `/` at the beginning)","example":"aBcDe012","in":"query","name":"aliasName","required":false,"schema":{"default":"@rnd","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAliasModel"}}},"description":"alias properties","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAliasResponseModel"}}},"description":"Response contains aliasName, domainName and full generated short link"}},"security":[{"ApiKeyAuth":[]}],"summary":"Create alias","tags":["Alias"]},"put":{"description":"Update a single short URL by providing its alias and domain as a parameter, and the data you wish to update in the body of the request. If no domain is provided you will receive the alias found attached to the Short.fyi domain (if it exists and is linked to your account!)\n\n ### NOTE: \n\n ( * )If you add a metatag or a snippet with a same name to an alias and the domain it's related to, the value will be taken from the alias and not the domain \n\n ( ** ) When you update any array property (like destinations) the block is updated **completely** so you have to specify the old records to avoid deleting them\n\n ( *** ) The method updates only the specified properties so if there was no change in one of them you don't have to send it.","operationId":"UpdateAlias","parameters":[{"description":"domain which alias belongs to (string without `http/https` or `/`)","example":"your.domain.com","in":"query","name":"domainName","required":false,"schema":{"default":"short.fyi","type":"string"}},{"description":"alias (without `/` at the beginning)","example":"aBcDe012","in":"query","name":"aliasName","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateAliasModel"}}},"description":"alias properties you wish to be updated","required":true},"responses":{"200":{"description":"Empty response"}},"security":[{"ApiKeyAuth":[]}],"summary":"Update alias","tags":["Alias"]}},"/aliases/all":{"get":{"description":"Obtain a list of all alias names associated with your account and given domain. Result array is in descending order by creation date. \n\n If no domain is specified you will receive a list of all the alias names you have created using the Short.fyi domain. \n\n If there are more results than the limit for the request the response will return you a value in lastId property you can specify it in the continueFrom query parameter to get the next batch of records.","operationId":"GetAliases","parameters":[{"description":"The domain name to get the aliases for (string without `http/https` or `/`)","example":"your.domain.com","in":"query","name":"domainName","required":false,"schema":{"default":"short.fyi","type":"string"}},{"description":"An ID returned by a previous query to continue aliases retrieval (see lastId in response)","example":"1588788835614657618","in":"query","name":"continueFrom","required":false,"schema":{"type":"string"}},{"description":"Number of results to return per request","example":100,"in":"query","name":"limit","schema":{"default":1000,"maximum":1000,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetAliasesModel"}}},"description":"returns Array of aliases with lastId"}},"security":[{"ApiKeyAuth":[]}],"summary":"Get aliases by domain","tags":["Alias"]}},"/clicks":{"get":{"description":"Retrieve the raw click data for your account. Clicks are retrieved by creation date in descending order. \n\n If there are more results than the limit for the request the response will return you a value in lastId property you can specify it in the continueFrom query parameter to get the next batch of records.","operationId":"GetClicks","parameters":[{"description":"An ID returned by a previous query to continue clicks retrieval (see lastId in response)","example":"1588788835614657618","in":"query","name":"continueFrom","required":false,"schema":{"type":"string"}},{"description":"Number of results to return per request","example":100,"in":"query","name":"limit","schema":{"default":1000,"maximum":1000,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetClicksModel"}}},"description":"returns Array of Click models, also returns lastId"}},"security":[{"ApiKeyAuth":[]}],"summary":"Get clicks","tags":["Click"]}},"/clicks/pg":{"post":{"description":"Retrieve the raw click statistics for your account. Clicks are retrieved by creation date in descending order.","operationId":"GetStatistics","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClicksFilterModel"}}},"description":"Filter","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClickModelPg"}}},"description":"returns Array of Click models, also returns lastId"}},"security":[{"ApiKeyAuth":[]}],"summary":"Get clicks statistics","tags":["Statistics"]}}},"components":{"schemas":{"AliasModel":{"properties":{"createdAt":{"example":1595845801514,"format":"int64","type":"integer"},"destinations":{"items":{"$ref":"#/components/schemas/DestinationModel"},"type":"array"},"domainName":{"example":"your.domain.com","type":"string"},"metatags":{"items":{"$ref":"#/components/schemas/MetaTagModel"},"type":"array"},"name":{"example":"aBcDe012","type":"string"},"snippets":{"items":{"$ref":"#/components/schemas/SnippetModel"},"type":"array"},"updatedAt":{"example":1595845801514,"format":"int64","type":"integer"}},"required":["name"],"type":"object"},"ClickModel":{"properties":{"alias":{"type":"string"},"aliasId":{"type":"string"},"browser":{"type":"string"},"country":{"type":"string"},"createdAt":{"format":"int64","type":"integer"},"destination":{"type":"string"},"domain":{"type":"string"},"os":{"type":"string"},"referrer":{"type":"string"},"userAgent":{"type":"string"}},"type":"object"},"ClickModelPg":{"properties":{"accountId":{"type":"string"},"alias":{"type":"string"},"aliasId":{"type":"string"},"browser":{"type":"string"},"country":{"type":"string"},"createdAt":{"format":"int64","type":"integer"},"destination":{"type":"string"},"domain":{"type":"string"},"id":{"type":"integer"},"os":{"type":"string"},"referrer":{"type":"string"},"userAgent":{"type":"string"}},"type":"object"},"ClicksFilterModel":{"properties":{"aliasId":{"description":"Alias Id","example":"aBcDe012","type":"string"},"dateFrom":{"description":"date From","example":"2025-04-15T13:50:53.855Z","type":"string"},"dateTo":{"description":"date To","example":"2025-04-15T13:50:53.855Z","type":"string"},"domain":{"description":"Domain name","example":"short.fyi","type":"string"},"lastId":{"description":"last Id","example":100,"type":"integer"}},"type":"object"},"CreateAliasModel":{"properties":{"destinations":{"items":{"$ref":"#/components/schemas/DestinationModel"},"type":"array"},"metatags":{"items":{"$ref":"#/components/schemas/MetaTagModel"},"type":"array"},"snippets":{"items":{"$ref":"#/components/schemas/SnippetModel"},"type":"array"}},"type":"object"},"CreateAliasResponseModel":{"properties":{"aliasName":{"example":"aBcDe012","type":"string"},"domainName":{"example":"your.domain.com","type":"string"},"shortUrl":{"example":"https://your.domain.com/aBcDe012","type":"string"}},"type":"object"},"DestinationModel":{"properties":{"country":{"description":"ISO alpha-2 [country code](//en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements)","type":"string"},"os":{"description":"Please check the [supported OS list](#tag/OperatingSystems)","type":"string"},"url":{"type":"string"}},"required":["url"],"type":"object"},"GetAliasModel":{"additionalProperties":{"$ref":"#/components/schemas/CreateAliasModel"},"properties":{"createdAt":{"format":"int64","type":"integer"},"domainName":{"example":"your.domain.com","type":"string"},"name":{"type":"string"},"updatedAt":{"format":"int64","type":"integer"}},"type":"object"},"GetAliasesModel":{"properties":{"aliases":{"items":{"type":"string"},"type":"array"},"lastId":{"type":"string"}},"type":"object"},"GetClicksModel":{"properties":{"clicks":{"items":{"$ref":"#/components/schemas/ClickModel"},"type":"array"},"lastId":{"type":"string"}},"type":"object"},"MetaTagModel":{"properties":{"content":{"type":"string"},"name":{"type":"string"}},"required":["name","content"],"type":"object"},"SnippetModel":{"properties":{"id":{"description":"Please check the [supported snippets list](#tag/Snippets)","type":"string"},"parameters":{"additionalProperties":{"type":"string"},"type":"object"}},"required":["id"],"type":"object"}},"securitySchemes":{"ApiKeyAuth":{"in":"header","name":"x-api-key","type":"apiKey"}}}}