openapi: 3.1.0
info:
  title: URLdn API
  version: 1.0.0
  description: |
    Create and manage short links, tags and custom domains, read click analytics, generate
    QR codes and ask the AI analyst. Included on every plan, with limits by plan. Limits apply
    to your whole account, across all its keys.

    Keep API keys on your server: anything in front-end code can be read by anyone.
servers:
  - url: https://api.urldn.com/v1
security:
  - apiKey: []
tags:
  - name: Links
  - name: Tags
  - name: Domains
  - name: Analytics
  - name: QR codes
  - name: AI analyst
  - name: Account

paths:
  /me:
    get:
      tags: [Account]
      operationId: getMe
      summary: Retrieve account
      description: |
        Returns your plan, usage and limits, and works with any key, whatever its scopes. A limit
        of `-1` means unlimited. The `links` and `qrCodes` limits count what is in your account
        now, not what you created this month.
      responses:
        '200':
          description: The account the key belongs to
          headers:
            X-Request-Id: { $ref: '#/components/headers/RequestId' }
            X-RateLimit-Limit: { $ref: '#/components/headers/RateLimitLimit' }
            X-RateLimit-Remaining: { $ref: '#/components/headers/RateLimitRemaining' }
            X-RateLimit-Reset: { $ref: '#/components/headers/RateLimitReset' }
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Me' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /links:
    post:
      tags: [Links]
      operationId: createLink
      summary: Create link
      description: |
        Requires the `links:write` scope. Internal and private addresses, and destinations flagged
        as phishing or malware, return `400 blocked_destination`.
      parameters:
        - { $ref: '#/components/parameters/IdempotencyKey' }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateLink' }
      responses:
        '201':
          description: The new link
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Link' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/QuotaExceeded' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409':
          description: '`slug_taken`, or `idempotency_in_progress` when a request with this key is still running'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '422':
          description: '`idempotency_key_reused`: this key was used with a different body'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '429': { $ref: '#/components/responses/RateLimited' }
    get:
      tags: [Links]
      operationId: listLinks
      summary: List links
      description: |
        Requires the `links:read` scope. Returns your links, newest first. Pass `nextCursor` back
        as `cursor` to get the next page, until `hasMore` is `false`.
      parameters:
        - name: limit
          in: query
          schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
        - name: cursor
          in: query
          description: The `nextCursor` of the previous page
          schema: { type: string }
        - { $ref: '#/components/parameters/FilterDomain' }
        - { $ref: '#/components/parameters/FilterTag' }
        - { $ref: '#/components/parameters/FilterSearch' }
        - { $ref: '#/components/parameters/FilterIsActive' }
      responses:
        '200':
          description: One page of links
          content:
            application/json:
              schema:
                type: object
                required: [data, hasMore, nextCursor]
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/Link' }
                  hasMore: { type: boolean }
                  nextCursor: { type: [string, 'null'] }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /links/count:
    get:
      tags: [Links]
      operationId: countLinks
      summary: Count links
      description: Requires the `links:read` scope. Takes the same filters as listing links.
      parameters:
        - { $ref: '#/components/parameters/FilterDomain' }
        - { $ref: '#/components/parameters/FilterTag' }
        - { $ref: '#/components/parameters/FilterSearch' }
        - { $ref: '#/components/parameters/FilterIsActive' }
      responses:
        '200':
          description: How many links match
          content:
            application/json:
              schema:
                type: object
                required: [count]
                properties:
                  count: { type: integer }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /links/upsert:
    put:
      tags: [Links]
      operationId: upsertLink
      summary: Upsert link
      description: |
        Requires the `links:write` scope. If you already have a link to this exact `url` on the
        same domain, it updates that link's `customSlug`, `title` and `tags` and returns `200`.
        If not, it creates one and returns `201`. With several matches, it updates the newest.

        Two upserts for the same new `url` at the same moment can create two links.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateLink' }
      responses:
        '200':
          description: The existing link, updated
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Link' }
        '201':
          description: The new link
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Link' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/QuotaExceeded' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409':
          description: '`slug_taken`'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /links/bulk:
    post:
      tags: [Links]
      operationId: bulkCreateLinks
      summary: Bulk create links
      description: |
        Requires the `links:write` scope and a plan with bulk operations, from Pro. Creates up to 100 links, each with the same checks as
        creating one. A link that fails doesn't stop the others, so check `errors`: `index` is
        its position in your request. Limited to 30 bulk requests per minute per account.
      parameters:
        - { $ref: '#/components/parameters/IdempotencyKey' }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              minItems: 1
              maxItems: 100
              items: { $ref: '#/components/schemas/CreateLink' }
      responses:
        '200':
          description: The links created, and the rows that failed
          content:
            application/json:
              schema:
                type: object
                required: [created, errors]
                properties:
                  created:
                    type: array
                    items: { $ref: '#/components/schemas/Link' }
                  errors:
                    type: array
                    items:
                      allOf:
                        - { $ref: '#/components/schemas/Error' }
                        - type: object
                          required: [index]
                          properties:
                            index: { type: integer }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409':
          description: '`idempotency_in_progress`: a request with this key is still running'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '422':
          description: '`idempotency_key_reused`: this key was used with a different body'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '429': { $ref: '#/components/responses/RateLimited' }
    patch:
      tags: [Links]
      operationId: bulkUpdateLinks
      summary: Bulk update links
      description: |
        Requires the `links:write` scope and a plan with bulk operations, from Pro. Applies the same change to up to 100 links. It can't set
        `customSlug`, since an alias belongs to one link. A link that fails doesn't stop the others,
        so check `errors`. Limited to 30 bulk requests per minute per account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [linkIds, data]
              properties:
                linkIds:
                  type: array
                  minItems: 1
                  maxItems: 100
                  uniqueItems: true
                  items: { type: string, pattern: '^[a-f0-9]{24}$' }
                data:
                  type: object
                  additionalProperties: false
                  minProperties: 1
                  properties:
                    url: { type: string, format: uri, maxLength: 2048 }
                    domain: { type: [string, 'null'], description: 'null moves the links back to the default domain' }
                    title: { type: [string, 'null'], maxLength: 120 }
                    tags: { type: array, maxItems: 20, items: { type: string, maxLength: 40 } }
                    isActive: { type: boolean }
      responses:
        '200':
          description: The links updated, and the ones that failed
          content:
            application/json:
              schema:
                type: object
                required: [updated, errors]
                properties:
                  updated:
                    type: array
                    items: { $ref: '#/components/schemas/Link' }
                  errors:
                    type: array
                    items:
                      allOf:
                        - { $ref: '#/components/schemas/Error' }
                        - type: object
                          required: [id]
                          properties:
                            id: { type: string }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }
    delete:
      tags: [Links]
      operationId: bulkDeleteLinks
      summary: Bulk delete links
      description: |
        Requires the `links:write` scope and a plan with bulk operations, from Pro. Deletes up to 100 links and their click data. You can't
        undo this. Limited to 30 bulk requests per minute per account.
      parameters:
        - name: linkIds
          in: query
          required: true
          description: Up to 100 link ids, separated by commas
          schema: { type: string }
      responses:
        '200':
          description: The ids deleted, and the ones not found in your account
          content:
            application/json:
              schema:
                type: object
                required: [deleted, notFound]
                properties:
                  deleted: { type: array, items: { type: string } }
                  notFound: { type: array, items: { type: string } }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /links/{id}:
    parameters:
      - { $ref: '#/components/parameters/LinkId' }
    get:
      tags: [Links]
      operationId: getLink
      summary: Retrieve link
      description: Requires the `links:read` scope. A link in another account returns `404`, the same as one that doesn't exist.
      responses:
        '200':
          description: The link
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Link' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }
    patch:
      tags: [Links]
      operationId: updateLink
      summary: Update link
      description: |
        Requires the `links:write` scope. Send only the fields to change. A link with UTM tags
        keeps them on a new `url`.

        Changing `customSlug` or `domain` changes the short URL. Anything already shared with the
        old one, including printed QR codes, stops working.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/UpdateLink' }
      responses:
        '200':
          description: The updated link
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Link' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409':
          description: '`slug_taken`'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '429': { $ref: '#/components/responses/RateLimited' }
    delete:
      tags: [Links]
      operationId: deleteLink
      summary: Delete link
      description: Requires the `links:write` scope. Also deletes the link's click data. You can't undo this.
      responses:
        '204':
          description: Deleted
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /tags:
    get:
      tags: [Tags]
      operationId: listTags
      summary: List tags
      description: |
        Requires the `links:read` scope. Returns your tags with how many links use each, most used
        first, up to 1000. A tag exists while a link uses it, so you create one by adding it to a link.
      responses:
        '200':
          description: Your tags
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/Tag' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /tags/{name}:
    parameters:
      - { $ref: '#/components/parameters/TagName' }
    patch:
      tags: [Tags]
      operationId: updateTag
      summary: Update tag
      description: |
        Requires the `links:write` scope. Renames the tag on every link that has it. If a link already
        has a tag with the new name, it keeps one copy.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [name]
              properties:
                name: { type: string, minLength: 1, maxLength: 40 }
      responses:
        '200':
          description: The tag under its new name
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Tag' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }
    delete:
      tags: [Tags]
      operationId: deleteTag
      summary: Delete tag
      description: Requires the `links:write` scope. Removes the tag from every link that has it. The links stay.
      responses:
        '204':
          description: Deleted
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /domains:
    get:
      tags: [Domains]
      operationId: listDomains
      summary: List domains
      description: Requires the `domains:read` scope. Returns your custom domains, newest first.
      responses:
        '200':
          description: Your domains
          content:
            application/json:
              schema:
                type: object
                required: [data]
                properties:
                  data:
                    type: array
                    items: { $ref: '#/components/schemas/Domain' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }
    post:
      tags: [Domains]
      operationId: createDomain
      summary: Create domain
      description: |
        Requires the `domains:write` scope. Connects a domain you already own. Add the returned
        `dnsRecords` at your DNS provider, then call verify. A two-part domain such as `mybrand.com`
        (`isApex: true`) needs a provider that supports CNAME flattening.

        Limited to 10 domain requests per minute per account, together with verify.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [domain]
              properties:
                domain: { type: string, maxLength: 253, examples: [links.mybrand.com] }
      responses:
        '201':
          description: The domain, with the DNS records to add
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Domain' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/QuotaExceeded' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409':
          description: |
            `domain_exists` (already in your account), `domain_taken` (connected to another account)
            or `domain_cooldown` (released recently and still reserved)
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /domains/{id}:
    parameters:
      - { $ref: '#/components/parameters/DomainId' }
    get:
      tags: [Domains]
      operationId: getDomain
      summary: Retrieve domain
      description: Requires the `domains:read` scope. Use `state` to follow setup, from `dns_pending` to `active`.
      responses:
        '200':
          description: The domain
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Domain' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }
    delete:
      tags: [Domains]
      operationId: deleteDomain
      summary: Delete domain
      description: |
        Requires the `domains:write` scope. Removes the domain and moves its links to the default
        domain, so short URLs on the old domain stop working, including printed QR codes. Links on your
        other domains don't change. You can't undo this.
      responses:
        '204':
          description: Deleted
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /domains/{id}/verify:
    parameters:
      - { $ref: '#/components/parameters/DomainId' }
    post:
      tags: [Domains]
      operationId: verifyDomain
      summary: Verify domain
      description: |
        Requires the `domains:write` scope. Checks your DNS records now and returns `200` either way:
        read `verified` and `checks`. Verifying doesn't move any links. To use the domain, set `domain`
        when you create or update a link.

        Limited to 10 domain requests per minute per account, together with create.
      responses:
        '200':
          description: The domain and what the check found
          content:
            application/json:
              schema:
                allOf:
                  - { $ref: '#/components/schemas/Domain' }
                  - type: object
                    required: [checks, message]
                    properties:
                      checks:
                        type: object
                        required: [cname, txt]
                        properties:
                          cname: { type: boolean }
                          txt: { type: boolean }
                      message: { type: string }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /links/{id}/analytics:
    parameters:
      - { $ref: '#/components/parameters/LinkId' }
    get:
      tags: [Analytics]
      operationId: getLinkAnalytics
      summary: Retrieve analytics
      description: |
        Requires the `analytics:read` scope. On Free, this is clicks by day for up to the last 7
        days, which is also the default range there; anything else returns `403 plan_required`.
        Days are in UTC. `total` always counts every
        click in the range, also when `data` is cut at 1000 rows (`truncated: true`).
      parameters:
        - name: range
          in: query
          schema: { type: string, enum: ['24h', '7d', '30d', '90d', '365d', all], default: '30d' }
        - name: groupBy
          in: query
          schema: { type: string, enum: [day, country, device, referrer], default: day }
      responses:
        '200':
          description: Click counts
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Analytics' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /links/{id}/qr:
    parameters:
      - { $ref: '#/components/parameters/LinkId' }
    post:
      tags: [QR codes]
      operationId: createLinkQr
      summary: Create QR code
      description: |
        Requires the `qr:write` scope. The first call for a link marks it as a QR code and
        counts against your QR quota; later calls only return fresh URLs. The URLs need no API
        key and expire after 7 days. Call again for new ones: the QR code itself doesn't change.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                size: { type: integer, enum: [512, 1024, 2048], default: 512 }
      responses:
        '201':
          description: Image URLs
          content:
            application/json:
              schema: { $ref: '#/components/schemas/QrCode' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/QuotaExceeded' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '422':
          description: '`qr_not_scannable`: the saved design does not scan'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /qr/{id}.{format}:
    get:
      tags: [QR codes]
      operationId: getQrImage
      summary: Retrieve QR image
      description: Use the URLs returned by `POST /links/{id}/qr` as they are. No API key needed.
      security: []
      parameters:
        - { $ref: '#/components/parameters/LinkId' }
        - { name: format, in: path, required: true, schema: { type: string, enum: [png, svg] } }
        - { name: size, in: query, required: true, schema: { type: integer } }
        - { name: exp, in: query, required: true, schema: { type: integer } }
        - { name: sig, in: query, required: true, schema: { type: string } }
      responses:
        '200':
          description: The image
          content:
            image/png:
              schema: { type: string, contentEncoding: binary }
            image/svg+xml:
              schema: { type: string }
        '403':
          description: '`invalid_signature`: the URL was changed or has expired'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }
        '404': { $ref: '#/components/responses/NotFound' }
        '429': { $ref: '#/components/responses/RateLimited' }

  /health:
    get:
      tags: [Account]
      operationId: getHealth
      summary: Check API health
      security: []
      responses:
        '200':
          description: The API is up
          content:
            application/json:
              schema:
                type: object
                required: [ok]
                properties:
                  ok: { type: boolean, const: true }
        '429': { $ref: '#/components/responses/RateLimited' }

  /openapi.yaml:
    get:
      tags: [Account]
      operationId: getOpenApiSpec
      summary: Retrieve OpenAPI spec
      security: []
      responses:
        '200':
          description: The spec
          content:
            text/yaml:
              schema: { type: string }

  /ask:
    post:
      tags: [AI analyst]
      operationId: ask
      summary: Ask a question
      description: |
        Requires the `ai:ask` scope and a paid plan. The analyst answers from your account's data only. Counts
        against your monthly AI question quota, shared with the dashboard chat, and is also limited
        to 30 questions per minute per account. A failed answer is not charged.

        Each question stands alone: the analyst doesn't remember earlier ones, and API questions
        don't appear in your dashboard chat history. It can't create links here.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [question]
              properties:
                question: { type: string, minLength: 1, maxLength: 500 }
      responses:
        '200':
          description: The answer
          content:
            application/json:
              schema:
                type: object
                required: [answer]
                properties:
                  answer: { type: string }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '402': { $ref: '#/components/responses/QuotaExceeded' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '429': { $ref: '#/components/responses/RateLimited' }
        '503':
          description: '`ai_unavailable`: try again later. Your quota was not charged.'
          content:
            application/json:
              schema: { $ref: '#/components/schemas/Error' }

components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: 'Your API key: `Authorization: Bearer urldn_live_...`'

  parameters:
    LinkId:
      name: id
      in: path
      required: true
      schema: { type: string, pattern: '^[a-f0-9]{24}$' }
    DomainId:
      name: id
      in: path
      required: true
      schema: { type: string, pattern: '^[a-f0-9]{24}$' }
    TagName:
      name: name
      in: path
      required: true
      description: The tag's exact name, URL-encoded
      schema: { type: string, maxLength: 40 }
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      description: |
        Any unique value of up to 255 printable characters. Retrying with the same key and
        body within 24 hours returns the first response with `Idempotent-Replayed: true`
        and creates nothing. A failed attempt frees the key.
      schema: { type: string, maxLength: 255 }
    FilterDomain:
      name: domain
      in: query
      description: Only links on this custom domain. `default` means links on the default domain.
      schema: { type: string }
    FilterTag:
      name: tag
      in: query
      description: Only links with this tag
      schema: { type: string, maxLength: 40 }
    FilterSearch:
      name: search
      in: query
      description: Text to find in the destination, alias or title. Case doesn't matter.
      schema: { type: string, maxLength: 100 }
    FilterIsActive:
      name: isActive
      in: query
      description: Only active or only inactive links
      schema: { type: boolean }

  headers:
    RequestId:
      description: Quote this if you contact support. Sent on every response.
      schema: { type: string }
    RateLimitLimit:
      description: Requests allowed per minute for your account
      schema: { type: integer }
    RateLimitRemaining:
      description: Requests left in this window
      schema: { type: integer }
    RateLimitReset:
      description: When the window resets, in Unix seconds
      schema: { type: integer }

  responses:
    BadRequest:
      description: '`invalid_request`, `invalid_json`, `invalid_cursor` or `blocked_destination`'
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    Unauthorized:
      description: '`missing_api_key`, `invalid_api_key` or `revoked_api_key`'
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    QuotaExceeded:
      description: '`quota_exceeded`: your plan''s limit is used up. `details` has the limit and an upgrade link.'
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    Forbidden:
      description: '`plan_required`, `insufficient_scope` or `domain_not_allowed`'
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    NotFound:
      description: '`not_found`. Anything in another account also returns this.'
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }
    RateLimited:
      description: '`rate_limited`, `monthly_quota_exceeded` or `too_many_auth_failures`. Wait for `Retry-After` seconds.'
      headers:
        Retry-After:
          description: Seconds to wait before retrying
          schema: { type: integer }
      content:
        application/json:
          schema: { $ref: '#/components/schemas/Error' }

  schemas:
    Error:
      type: object
      required: [error, message]
      properties:
        error: { type: string, description: A stable machine-readable code, examples: [quota_exceeded] }
        message: { type: string }
        details: { type: object, additionalProperties: true }

    Link:
      type: object
      required: [id, shortUrl, shortCode, url, domain, title, tags, isActive, isQrCode, hasPassword, expiresAt, createdAt]
      properties:
        id: { type: string }
        shortUrl: { type: string, format: uri }
        shortCode: { type: string }
        url: { type: string, format: uri, description: The destination }
        domain: { type: [string, 'null'], description: 'Your custom domain, or null for the default' }
        title: { type: [string, 'null'] }
        tags: { type: array, items: { type: string } }
        isActive: { type: boolean }
        isQrCode: { type: boolean }
        hasPassword: { type: boolean }
        expiresAt: { type: [string, 'null'], format: date-time }
        createdAt: { type: string, format: date-time }

    CreateLink:
      type: object
      additionalProperties: false
      required: [url]
      properties:
        url: { type: string, format: uri, maxLength: 2048, description: 'Must be https. Internal and private addresses are rejected.' }
        customSlug: { type: string, pattern: '^[A-Za-z0-9_-]{4,14}$' }
        domain: { type: string, description: 'One of your verified custom domains, by name or id' }
        title: { type: string, maxLength: 120 }
        tags: { type: array, maxItems: 20, items: { type: string, maxLength: 40 } }

    UpdateLink:
      type: object
      additionalProperties: false
      minProperties: 1
      properties:
        url: { type: string, format: uri, maxLength: 2048 }
        customSlug: { type: string, pattern: '^[A-Za-z0-9_-]{4,14}$' }
        domain: { type: [string, 'null'], description: 'null moves the link back to the default domain' }
        title: { type: [string, 'null'], maxLength: 120 }
        tags: { type: array, maxItems: 20, items: { type: string, maxLength: 40 } }
        isActive: { type: boolean }

    Tag:
      type: object
      required: [name, links]
      properties:
        name: { type: string }
        links: { type: integer, description: How many links have this tag }

    Domain:
      type: object
      required: [id, domain, state, verified, sslStatus, isApex, dnsRecords, verificationExpiresAt, lastVerified, createdAt]
      properties:
        id: { type: string }
        domain: { type: string, examples: [links.mybrand.com] }
        state: { type: string, enum: [dns_pending, dns_failed, dns_broken, ssl_issuing, active] }
        verified: { type: boolean }
        sslStatus: { type: string, enum: [pending, active, failed, broken] }
        isApex: { type: boolean, description: 'True for a two-part domain such as mybrand.com' }
        dnsRecords:
          type: array
          description: The records to add at your DNS provider. Names are full names.
          items:
            type: object
            required: [type, name, value]
            properties:
              type: { type: string, enum: [CNAME, TXT] }
              name: { type: string }
              value: { type: string }
        verificationExpiresAt: { type: [string, 'null'], format: date-time }
        lastVerified: { type: [string, 'null'], format: date-time }
        createdAt: { type: string, format: date-time }

    Analytics:
      type: object
      required: [linkId, range, start, end, groupBy, total, data, truncated]
      properties:
        linkId: { type: string }
        range: { type: string }
        start: { type: [string, 'null'], format: date-time }
        end: { type: string, format: date-time }
        groupBy: { type: string, enum: [day, country, device, referrer] }
        total: { type: integer }
        data:
          type: array
          items:
            type: object
            required: [key, clicks]
            properties:
              key: { type: string, examples: ['2026-11-02', US, mobile, Direct] }
              clicks: { type: integer }
        truncated: { type: boolean }

    QrCode:
      type: object
      required: [linkId, size, png, svg, expiresAt]
      properties:
        linkId: { type: string }
        size: { type: integer }
        png: { type: string, format: uri }
        svg: { type: string, format: uri }
        expiresAt: { type: string, format: date-time }

    Usage:
      type: object
      required: [used, limit]
      properties:
        used: { type: integer }
        limit: { type: integer, description: '-1 means unlimited' }

    Me:
      type: object
      required: [plan, usage, limits, apiKey]
      properties:
        plan: { type: string, enum: [free, pro, business, enterprise] }
        usage:
          type: object
          properties:
            links:
              allOf: [{ $ref: '#/components/schemas/Usage' }]
              description: Links in your account, not per month
            qrCodes: { $ref: '#/components/schemas/Usage' }
            aiQuestions:
              allOf:
                - { $ref: '#/components/schemas/Usage' }
                - type: object
                  properties:
                    resetsAt: { type: string, format: date-time }
            requests:
              allOf:
                - { $ref: '#/components/schemas/Usage' }
                - type: object
                  properties:
                    resetsAt: { type: string, format: date-time }
              description: API requests this period, across all your keys
        limits:
          type: object
          properties:
            requestsPerMinute: { type: integer }
            monthlyRequests: { type: integer, description: '-1 means unlimited' }
            activeKeys: { type: integer }
            customDomains: { type: integer, description: '-1 means unlimited' }
        apiKey:
          type: object
          properties:
            id: { type: string }
            name: { type: string }
            scopes:
              type: array
              items: { type: string, enum: ['links:read', 'links:write', 'domains:read', 'domains:write', 'analytics:read', 'qr:write', 'ai:ask'] }
