openapi: 3.0.0
servers:
  - url: https://api.shorten.rest
info:
  description: |-
    ## Introduction


    The Shorten.rest API allows you to programmatically create short URLs (an &apos;alias&apos;) for longer URL (a &apos;destination&apos;).

    Each alias you create can be used to redirect the end user (person clicking on the link) to one or more destination URLs

    A default destination is always set and specific destinations can be set to redirect the end user to preferred destinations based on the user&apos;s geographical location (country) and device Operating System.

    In 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 

     ### Destination Matching 

     When creating or editing a short URL (&apos;alias&apos;) you can choose to specify a destination for each country and OS ([Supported OSes list](#tag/OperatingSystems)) combination. 

     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. 

     (*) If no destination is set for a specific request combination Shorten.rest will use the default destination that exists within each short URL 

     (**) 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. 

     (***) Operating System (OS) destinations are stronger than a country destination! 
     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. 

     | OS  | Country  | Destination |
    | :------------: |:---------------:| -----|
    | iOS      |  | YourDestination.com/ios |
    |       | US        |   YourDestination.com/usa | 

     Shorten.rest will choose the YourDestination.com/ios url as the most suitable destination.

     ### Branded Domain Attributes 

     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. 

     By default the parameters you set in the domain setting will be included in all Short URLs associated with that domain. 

     You can always override the domain defaults for each URL by passing the appropriate variables when creating or updating a short URL 

     ### Setting a Custom string for an Alias (short.fyi/alias) 

     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. 

     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.

     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. 

     ### Random Aliases 

     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 &apos;alias&apos; 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. 

     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. 

     ### NOTES 

     ( * ) All methods of the Shorten.REST API require that your API key be provided in **x-api-key** header. 

     (**) 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 

         **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!)

         ### NOTE: 

         ( * )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 

         ( ** ) 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

         ( *** ) 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. 

         If no domain is specified you will receive a list of all the alias names you have created using the Short.fyi domain. 

         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. 

         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: 2001-05-02
          type: string
        dateTo:
          description: date To
          example: 2001-05-02
          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
