openapi: 3.0.0
info:
  description: "
LinkMngr use the OAuth 2.0 protocol for authentication and authorization. You can find out more about LinkMngr at [http://linkmngr.com](http://linkmngr.com) .

1. <h3>Get an API Key</h3>

Create a new API key from *[your LinkMngr account](https://app.linkmngr.com/developers)*.

2. <h3>Configure your API client</h3>

Within your application/script, you can access LinkMngr API via HTTP protocol.
"

  version: "v1"
  title: LinkMngr API
  termsOfService: https://linkmngr.com/terms/
  contact:
    email: support@linkmngr.com
externalDocs:
  description: "Find out more about LinkMngr"
  url: "http://linkmngr.com"

security:
  - bearerAuth: []
  - oauth2: []
paths:
  /links:
    post:
      tags:
        - Links
      summary: Creates a shortened link
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                destination:
                  description: URL that you want to shorten
                  type: string
                domain:
                  description: Short domain that you want to use. This should already be available in your account.
                  type: string
                  default: linkmngr.link
                slug:
                  description: URL slug that you want to use. If not supplied, a randomly generated slug will be used
                  type: string
                  default: random
                brand_id:
                  description: Brand that this link will belong to. If not set, the default brand will be used
                  type: integer
              required:
                - destination
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Link"
    get:
      tags:
        - Links
      summary: Gets all created links
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            default: 1
            description: Page to get results for
        - in: query
          name: brand_id
          schema:
            type: integer
            description: Brand to get results for
        - in: query
          name: domain
          schema:
            type: string
            description: Domain to filter results by
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedResults"
  /links/{linkId}:
    get:
      tags:
        - Links
      summary: Gets a specific link
      parameters:
        - in: path
          name: linkId
          description: Link ID
          required: true
          schema:
            type: number
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Link"
  /links/{linkId}/stats:
    get:
      tags:
      - Links
      summary: Gets links stats
      parameters:
        - in: path
          name: linkId
          description: Link ID
          required: true
          schema:
            type: number
        - in: query
          name: start
          description: Start date
          required: true
          schema:
            $ref: "#/components/schemas/UTCDateTime"
        - in: query
          name: end
          description: End date
          required: true
          schema:
            $ref: "#/components/schemas/UTCDateTime"
        - in: query
          name: time_unit
          required: true
          schema:
            type: string
            enum: [hour, day, week, month, year]
            default: day
        - in: query
          name: group_by
          required: false
          schema:
            type: string
            enum: [device, device_type, country, browser, platform, referrer]
            default: platform
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  clicks:
                    type: integer
                    description: Total clicks
                  unique_clicks:
                    type: integer
                    description: Total unique clicks
                  metrics:
                    type: array
                    items:
                      type: object
                      properties:
                        group:
                          type: string
                          example: Windows
                          description: If a group_by parameter is set, it will have the group name
                        clicks:
                          type: integer
                        unique_clicks:
                          type: integer
                        timestamp:
                          $ref: "#/components/schemas/UTCDateTime"

  /brands:
    post:
      tags:
        - Brands
      summary: Creates a new brand
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BrandObjectForRequest"
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Brand"
    get:
      summary: Gets all brands
      tags:
        - Brands
      parameters:
        - in: query
          name: page
          schema:
            type: integer
            default: 1
            description: Page to get results for
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PaginatedResults"
  /brands/{brandId}:
    get:
      tags:
        - Brands
      summary: Gets specific brandId
      parameters:
        - in: path
          name: brandId
          description: Brand ID
          required: true
          schema:
            type: integer
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Brand"
    patch:
      tags:
        - Brands
      summary: Modify a brand
      parameters:
        - in: path
          name: brandId
          description: Brand ID
          required: true
          schema:
            type: number
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/BrandObjectForRequest"
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Brand"
    delete:
      tags:
        - Brands
      summary: Delete a brand
      parameters:
        - in: path
          name: brandId
          description: Brand ID
          required: true
          schema:
            type: number
      responses:
        "204":
          description: successful operation
  /brands/{brandId}/check_domain:
    post:
      tags:
        - Brands
      summary: Check if a domain is set up correctly
      parameters:
        - in: path
          name: brandId
          description: Brand ID
          required: true
          schema:
            type: integer
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                domain:
                  type: string
                  example: linkmngr.link
                  description: It should already be added to the Brand
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BrandDomain"

  /analytics:
    get:
      tags:
        - Analytics
      summary: Gets metrics about your links
      parameters:
        - in: query
          name: brand_id
          description: Brand ID
          required: false
          schema:
            type: number
        - in: query
          name: start
          description: Start date
          required: true
          schema:
            $ref: "#/components/schemas/UTCDateTime"
        - in: query
          name: end
          description: End date
          required: true
          schema:
            $ref: "#/components/schemas/UTCDateTime"
        - in: query
          name: time_unit
          required: true
          schema:
            type: string
            enum: [hour, day, week, month, year]
            default: day
        - in: query
          name: group_by
          required: false
          schema:
            type: string
            enum: [device, device_type, country, browser, platform, referrer]
            default: platform
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  clicks:
                    type: integer
                    description: Total clicks
                  unique_clicks:
                    type: integer
                    description: Total unique clicks
                  metrics:
                    type: array
                    items:
                      type: object
                      properties:
                        group:
                          type: string
                          example: Windows
                          description: If a group_by parameter is set, it will have the group name
                        clicks:
                          type: integer
                        unique_clicks:
                          type: integer
                        timestamp:
                          $ref: "#/components/schemas/UTCDateTime"

  /domains:
    get:
      tags:
        - Domains
      summary: Get all available domains
      responses:
        200:
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

  /auth/user:
    get:
      tags:
        - User
      summary: Gets currently authenticated user
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: integer
                  name:
                    type: integer
                  email:
                    type: integer
                  email_verified:
                    type: boolean
                    example: true
                  default_brand_id:
                    type: integer
                    description: Default brand ID that will be used for requests where it is needed and if a brand_id is not specified
  /auth/revoke:
    post:
      tags:
        - User
      summary: Revokes currently authenticated user's token
      responses:
        "204":
          description: successful operation

servers:
  - url: https://api.linkmngr.com/v1
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.linkmngr.com/oauth/authorize
          tokenUrl: https://app.linkmngr.com/oauth/access_token
          scopes: {}
        password:
          tokenUrl: https://app.linkmngr.com/oauth/access_token
          scopes: {}
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  schemas:
    Brand:
      type: object
      properties:
        id:
          type: integer
        name:
          type: string
          default: Default
        domains:
          type: array
          items:
            $ref: "#/components/schemas/BrandDomain"
        users:
          type: array
          items:
            $ref: "#/components/schemas/BrandUser"
        settings:
          type: object
          properties:
            scripts:
              description: Scripts to execute for every link belonging to this Brand
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                    example: Facebook Pixel
                  script:
                    type: string
                    example: console.log('hello world')
            privacy_popup:
              type: object
              properties:
                active:
                  type: boolean
                  description: Set to true if you want to show a privacy policy prompt before executing any scripts
                link:
                  type: string
                  description: Link to the privacy policy page
                title:
                  type: string
                  description: Title of the popup
                content:
                  type: string
                  description: Simple text content of the popup
            query_parameters:
              type: object
              description: The default query parameters (or utm paramters)
              properties:
                '*':
                  type: string
    BrandObjectForRequest:
      type: object
      properties:
        name:
          type: string
        users:
          type: array
          items:
            type: object
            properties:
              email:
                type: string
              permissions:
                type: array
                items:
                  type: string
        domains:
          type: array
          items:
            type: object
            properties:
              domain:
                type: string
                default: linkmngr.link
        settings:
          type: object
          properties:
            scripts:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  script:
                    type: string
            privacy_popup:
              type: object
              properties:
                active:
                  type: boolean
                  description: Set to true if you want to show a privacy policy prompt before executing any scripts
                link:
                  type: string
                  description: Link to the privacy policy page
                title:
                  type: string
                  description: Title of the popup
                content:
                  type: string
                  description: Simple text content of the popup
            query_parameters:
              type: array
              items:
                type: object
                properties:
                  name:
                    type: string
                  value:
                    type: string
      required:
            - name
    Link:
      type: object
      properties:
        id:
          type: integer
        domain:
          type: string
          example: linkmngr.link
        link:
          type: string
          example: https://linkmngr.link/test
        slug:
          type: string
          example: F5rgTf
        destination:
          type: string
          example: https://socialbu.com
        brand_id:
          type: integer
        clicks:
          type: integer
        unique_clicks:
          type: integer
        created_at:
          $ref: "#/components/schemas/UTCDateTime"
    BrandUser:
      type: object
      properties:
        name:
          type: string
        email:
          type: string
        permissions:
          type: array
          items:
            type: string
            enum: [links.create, links.view, brand.admin]
    BrandDomain:
      type: object
      properties:
        domain:
          type: string
          example: linkmngr.link
        active:
          type: boolean
          example: true
        type:
          type: string
          example: internal
    PaginatedResults:
      type: object
      properties:
        total:
          type: integer
          example: 1
        perPage:
          type: integer
          default: 100
        currentPage:
          type: integer
          default: 1
        nextPage:
          type: integer
          example: null
        lastPage:
          type: integer
          example: 1
        items:
          type: array
          description: Array of items
          items:
            type: object
    UTCDateTime:
      type: string
      description: ISO 8601 datetime string
      example: "2021-01-01T03:45:27+00:00"
