openapi: 3.1.0
info:
  title: Bitly API v4 Bitlinks Metrics API
  description: 'REST API for creating and managing Bitlinks, custom domains, groups,

    organizations, campaigns, channels, QR codes, and click analytics.


    Best-effort OpenAPI reconstruction from Bitly''s public API reference at

    https://dev.bitly.com/api-reference. Bitly also publishes an authoritative

    spec at https://dev.bitly.com/v4/v4.json.

    '
  version: 4.0.0
  contact:
    name: Bitly API
    url: https://dev.bitly.com/api-reference
  license:
    name: Proprietary
servers:
- url: https://api-ssl.bitly.com/v4
  description: Bitly v4 REST API
security:
- bearerAuth: []
tags:
- name: Metrics
paths:
  /bitlinks/{bitlink}/clicks:
    parameters:
    - $ref: '#/components/parameters/Bitlink'
    - $ref: '#/components/parameters/Unit'
    - $ref: '#/components/parameters/Units'
    - $ref: '#/components/parameters/Size'
    - $ref: '#/components/parameters/UnitReference'
    get:
      tags:
      - Metrics
      summary: Get clicks for a Bitlink
      operationId: getBitlinkClicks
      responses:
        '200':
          description: Click data.
  /bitlinks/{bitlink}/clicks/summary:
    parameters:
    - $ref: '#/components/parameters/Bitlink'
    - $ref: '#/components/parameters/Unit'
    - $ref: '#/components/parameters/Units'
    - $ref: '#/components/parameters/UnitReference'
    get:
      tags:
      - Metrics
      summary: Get summary of clicks for a Bitlink
      operationId: getBitlinkClicksSummary
      responses:
        '200':
          description: Click summary.
  /bitlinks/{bitlink}/engagements:
    parameters:
    - $ref: '#/components/parameters/Bitlink'
    get:
      tags:
      - Metrics
      summary: Get engagements (clicks and scans) for a Bitlink
      operationId: getBitlinkEngagements
      responses:
        '200':
          description: Engagement data.
  /bitlinks/{bitlink}/countries:
    parameters:
    - $ref: '#/components/parameters/Bitlink'
    - $ref: '#/components/parameters/Unit'
    - $ref: '#/components/parameters/Units'
    get:
      tags:
      - Metrics
      summary: Get countries by clicks for a Bitlink
      operationId: getBitlinkCountries
      responses:
        '200':
          description: Country breakdown.
  /bitlinks/{bitlink}/cities:
    parameters:
    - $ref: '#/components/parameters/Bitlink'
    - $ref: '#/components/parameters/Unit'
    - $ref: '#/components/parameters/Units'
    get:
      tags:
      - Metrics
      summary: Get cities by clicks for a Bitlink
      operationId: getBitlinkCities
      responses:
        '200':
          description: City breakdown.
  /bitlinks/{bitlink}/devices:
    parameters:
    - $ref: '#/components/parameters/Bitlink'
    get:
      tags:
      - Metrics
      summary: Get device type breakdown
      operationId: getBitlinkDevices
      responses:
        '200':
          description: Device breakdown.
  /bitlinks/{bitlink}/referrers:
    parameters:
    - $ref: '#/components/parameters/Bitlink'
    - $ref: '#/components/parameters/Unit'
    - $ref: '#/components/parameters/Units'
    get:
      tags:
      - Metrics
      summary: Get referrers for a Bitlink
      operationId: getBitlinkReferrers
      responses:
        '200':
          description: Referrer breakdown.
  /bitlinks/{bitlink}/referring_domains:
    parameters:
    - $ref: '#/components/parameters/Bitlink'
    - $ref: '#/components/parameters/Unit'
    - $ref: '#/components/parameters/Units'
    get:
      tags:
      - Metrics
      summary: Get referring domains for a Bitlink
      operationId: getBitlinkReferringDomains
      responses:
        '200':
          description: Referring domains.
components:
  parameters:
    Unit:
      name: unit
      in: query
      schema:
        type: string
        enum:
        - minute
        - hour
        - day
        - week
        - month
    Size:
      name: size
      in: query
      schema:
        type: integer
        default: 50
    Units:
      name: units
      in: query
      schema:
        type: integer
        default: -1
    Bitlink:
      name: bitlink
      in: path
      required: true
      description: A Bitlink (e.g. `bit.ly/abc123`).
      schema:
        type: string
    UnitReference:
      name: unit_reference
      in: query
      schema:
        type: string
        format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Bearer token issued from Bitly account settings, or obtained via OAuth 2.0.

        Send as `Authorization: Bearer {token}`.

        '