> ## Documentation Index
> Fetch the complete documentation index at: https://learn.biq.li/llms.txt
> Use this file to discover all available pages before exploring further.

# Create a link

> Create a short link, configure its behavior, and optionally attach workspace resources or an SVG QR code.

Create one short link in the workspace bound to your API key. Only `long_url` is required.

<Note>
  You do not send a workspace ID. A `biqli_` API key belongs to exactly one
  workspace, and every resource created or attached by this request is scoped
  to that workspace.
</Note>

## Authentication and permissions

Send your workspace API key as a Bearer token:

```http theme={null}
Authorization: Bearer biqli_your_workspace_api_key
Content-Type: application/json
Accept: application/json
```

The key always needs **Links: Write** (`links.create`). If you attach existing
workspace resources, it also needs the matching read permission.

| Request field | Additional API key permission                      |
| ------------- | -------------------------------------------------- |
| `domain_id`   | **Custom domains: Read** (`custom_domains.view`)   |
| `folder_ids`  | **Folders: Read** (`link_groups.view`)             |
| `pixel_ids`   | **Tracking pixels: Read** (`tracking_pixels.view`) |
| `tag_ids`     | **Tags: Read** (`tags.view`)                       |

Creating a QR code attached to the new link only needs **Links: Write**. It does
not need a standalone QR code permission and does not consume standalone QR
code quota.

The user who created the key must still have access to the workspace and be
allowed to create links there. Revoking the key or removing that workspace
access immediately prevents new requests.

## Minimal request

```bash theme={null}
curl --request POST \
  --url https://biq.li/api/v1/link \
  --header 'Authorization: Bearer biqli_your_workspace_api_key' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "long_url": "https://example.com/product"
  }'
```

Biqli normalizes a destination without a scheme to HTTPS. For example,
`example.com/product` becomes `https://example.com/product`.

## Link identity and destination

| Field         | Type             | Behavior                                                                                                         |
| ------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------- |
| `long_url`    | string, required | Primary destination. Maximum 1,000 characters by default.                                                        |
| `name`        | string or null   | Internal link name. Maximum 150 characters.                                                                      |
| `external_id` | string or null   | Your identifier for this link. Maximum 255 characters and unique within the workspace.                           |
| `domain_id`   | string or null   | Public custom domain ID such as `biq_dom_...`. Omit it to use the default Biqli domain.                          |
| `alias`       | string or null   | Custom short-link alias. Workspace alias character, minimum, maximum, reserved-word, and blacklist rules apply.  |
| `active`      | boolean          | Whether the link can redirect. Defaults to `true`. A pending or quarantined safety state still blocks redirects. |

Custom aliases are unique per domain across short links, folders, and bio
pages. A duplicate alias returns `409 alias_taken` and does not create a link.
An `external_id` is unique within the API key's workspace. A duplicate returns
`409 external_id_taken`.

```json theme={null}
{
  "long_url": "https://example.com/product",
  "name": "Summer campaign",
  "external_id": "campaign-link-1842",
  "domain_id": "biq_dom_01M14C6KQ6SG2GKMCV7HQ9A1QT",
  "alias": "summer-product",
  "active": true
}
```

## Access and expiration

| Field                   | Type                       | Behavior                                                                                                          |
| ----------------------- | -------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `password`              | string or null             | Password visitors must enter before redirecting. Maximum 250 characters. The response never returns the password. |
| `activates_at`          | ISO 8601 date-time or null | Date and time when the link becomes active.                                                                       |
| `expires_at`            | ISO 8601 date-time or null | Future expiration date and time. It must be later than `activates_at`.                                            |
| `exp_clicks_rule.key`   | integer                    | Number of clicks after which the link expires. Minimum `1`.                                                       |
| `exp_clicks_rule.value` | string or null             | Optional destination used after the click threshold is reached.                                                   |

```json theme={null}
{
  "long_url": "https://example.com/launch",
  "password": "launch-2026",
  "activates_at": "2026-09-01T08:00:00Z",
  "expires_at": "2026-10-01T08:00:00Z",
  "exp_clicks_rule": {
    "key": 1000,
    "value": "https://example.com/campaign-ended"
  }
}
```

## UTM parameters

Use `utm` for an ampersand-separated query string without a leading `?`.
Biqli prefixes keys with `utm_` when the prefix is missing, then appends the
parameters to the destination without replacing its existing query string.

```json theme={null}
{
  "long_url": "https://example.com/product?variant=blue",
  "utm": "source=newsletter&medium=email&utm_campaign=summer"
}
```

The redirect destination becomes:

```text theme={null}
https://example.com/product?variant=blue&utm_source=newsletter&utm_medium=email&utm_campaign=summer
```

## Dynamic routing

Use targeting rules to override the destination for matching visitors. Each
rule has a `key` and destination `value`. Biqli uses the first matching rule.

| Field            | Match value                                                                                |
| ---------------- | ------------------------------------------------------------------------------------------ |
| `geo_rules`      | Lowercase ISO 3166-1 alpha-2 country code, such as `us` or `ma`.                           |
| `device_rules`   | `desktop`, `mobile`, or `tablet`.                                                          |
| `platform_rules` | Normalized platform such as `ios`, `androidos`, `windows`, `os x`, `chromeos`, or `linux`. |

Each list accepts up to 100 rules. Rule keys are limited to 250 characters and
destinations to 1,000 characters.

```json theme={null}
{
  "long_url": "https://example.com/product",
  "geo_rules": [
    {
      "key": "us",
      "value": "https://example.com/us/product"
    },
    {
      "key": "ma",
      "value": "https://example.com/ma/product"
    }
  ],
  "device_rules": [
    {
      "key": "mobile",
      "value": "https://m.example.com/product"
    }
  ],
  "platform_rules": [
    {
      "key": "ios",
      "value": "https://apps.apple.com/app/example"
    }
  ]
}
```

All rule destinations, including the click-expiration destination, pass through
the same URL validation and safety flow as `long_url`.

## Attach workspace resources

Pass public IDs to attach resources that already exist in the key's workspace.
Internal numeric database IDs are not accepted.

```json theme={null}
{
  "long_url": "https://example.com/product",
  "folder_ids": [
    "biq_fld_01M14C93RJD7W46PFJX9B1TVYH"
  ],
  "pixel_ids": [
    "biq_pxl_01M14CBJNRXPW4Y22ZTA7F9W3J"
  ],
  "tag_ids": [
    "biq_tag_01M14CC1TW7AQ6DWZG9TMRH0PQ"
  ]
}
```

| Resource           | Public ID prefix |
| ------------------ | ---------------- |
| Link               | `biq_lnk_`       |
| Workspace          | `biq_ws_`        |
| Custom domain      | `biq_dom_`       |
| Folder             | `biq_fld_`       |
| Bio page           | `biq_bio_`       |
| Tracking pixel     | `biq_pxl_`       |
| Tag                | `biq_tag_`       |
| Standalone QR code | `biq_qr_`        |

If any supplied ID is malformed or uses the wrong resource prefix, validation
returns `422`. If it is valid but missing or belongs to another workspace, the
API returns `404 resource_not_found`. This prevents cross-workspace resource
disclosure.

## Conversion tracking and indexing

Set `conversion_tracking_enabled` to append a Biqli click ID to the destination
for conversion attribution. It defaults to `false`.

Set `allow_search_engine_indexing` to `true` only when you want search engines
to index the short-link page. It defaults to `false`, which sends no-index
instructions.

```json theme={null}
{
  "long_url": "https://example.com/checkout",
  "conversion_tracking_enabled": true,
  "allow_search_engine_indexing": false
}
```

## Custom social preview

Set `proxy` to `true` to use your own social preview metadata. You can provide
any combination of `title`, `description`, and `image`.

```json theme={null}
{
  "long_url": "https://example.com/product",
  "proxy": true,
  "title": "Summer sale",
  "description": "Explore the summer collection.",
  "image": "https://cdn.example.com/previews/summer.jpg"
}
```

| Field         | Limit                                      |
| ------------- | ------------------------------------------ |
| `title`       | 255 characters                             |
| `description` | 1,000 characters                           |
| `image`       | Public HTTPS URL, maximum 2,048 characters |

`image` rejects local hostnames, private or reserved IP literals, and non-HTTPS
URLs. Providing preview metadata without `proxy: true` returns a validation
error. Set `proxy` to `false` or omit it to use destination metadata instead.

## Create an attached QR code

Set `create_qr_code` to `true` to generate a 1,024-pixel SVG QR code that points
to the new short URL.

```json theme={null}
{
  "long_url": "https://example.com/product",
  "create_qr_code": true,
  "qr_logo": "app"
}
```

`qr_logo` accepts:

* `app`: Include the Biqli logo. This is the default.
* `none`: Generate the QR code without a center logo. This option requires the
  workspace plan permission for unbranded QR codes.

You can only send `qr_logo` when `create_qr_code` is `true`. The response
includes the stored SVG URL, format, and selected logo mode.

## Complete request

```bash theme={null}
curl --request POST \
  --url https://biq.li/api/v1/link \
  --header 'Authorization: Bearer biqli_your_workspace_api_key' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{
    "long_url": "https://example.com/product",
    "name": "Summer campaign",
    "external_id": "campaign-link-1842",
    "domain_id": "biq_dom_01M14C6KQ6SG2GKMCV7HQ9A1QT",
    "alias": "summer-product",
    "active": true,
    "password": "launch-2026",
    "activates_at": "2026-09-01T08:00:00Z",
    "expires_at": "2026-10-01T08:00:00Z",
    "exp_clicks_rule": {
      "key": 1000,
      "value": "https://example.com/campaign-ended"
    },
    "utm": "source=newsletter&medium=email&campaign=summer",
    "geo_rules": [
      {
        "key": "us",
        "value": "https://example.com/us/product"
      }
    ],
    "device_rules": [
      {
        "key": "mobile",
        "value": "https://m.example.com/product"
      }
    ],
    "platform_rules": [
      {
        "key": "ios",
        "value": "https://apps.apple.com/app/example"
      }
    ],
    "folder_ids": [
      "biq_fld_01M14C93RJD7W46PFJX9B1TVYH"
    ],
    "pixel_ids": [
      "biq_pxl_01M14CBJNRXPW4Y22ZTA7F9W3J"
    ],
    "tag_ids": [
      "biq_tag_01M14CC1TW7AQ6DWZG9TMRH0PQ"
    ],
    "conversion_tracking_enabled": true,
    "allow_search_engine_indexing": false,
    "proxy": true,
    "title": "Summer sale",
    "description": "Explore the summer collection.",
    "image": "https://cdn.example.com/previews/summer.jpg",
    "create_qr_code": true,
    "qr_logo": "app"
  }'
```

## Successful response

A link that clears synchronous safety checks returns `201 Created`.

```json theme={null}
{
  "link": {
    "id": "biq_lnk_01M14D2M8VFKYQCE7Z3A6HRXWP",
    "short_url": "https://go.example.com/summer-product",
    "long_url": "https://example.com/product",
    "name": "Summer campaign",
    "external_id": "campaign-link-1842",
    "domain_id": "biq_dom_01M14C6KQ6SG2GKMCV7HQ9A1QT",
    "alias": "summer-product",
    "active": true,
    "has_password": true,
    "activates_at": "2026-09-01T08:00:00+00:00",
    "expires_at": "2026-10-01T08:00:00+00:00",
    "exp_clicks_rule": {
      "key": 1000,
      "value": "https://example.com/campaign-ended"
    },
    "utm": "source=newsletter&medium=email&campaign=summer",
    "geo_rules": [
      {
        "key": "us",
        "value": "https://example.com/us/product"
      }
    ],
    "device_rules": [
      {
        "key": "mobile",
        "value": "https://m.example.com/product"
      }
    ],
    "platform_rules": [
      {
        "key": "ios",
        "value": "https://apps.apple.com/app/example"
      }
    ],
    "folder_ids": [
      "biq_fld_01M14C93RJD7W46PFJX9B1TVYH"
    ],
    "pixel_ids": [
      "biq_pxl_01M14CBJNRXPW4Y22ZTA7F9W3J"
    ],
    "tag_ids": [
      "biq_tag_01M14CC1TW7AQ6DWZG9TMRH0PQ"
    ],
    "conversion_tracking_enabled": true,
    "allow_search_engine_indexing": false,
    "proxy": true,
    "title": "Summer sale",
    "description": "Explore the summer collection.",
    "image": "https://cdn.example.com/previews/summer.jpg",
    "qr_code": {
      "url": "https://biq.li/storage/workspaces/biq_ws_01M14ABP8W2BBMZ06SZKBJ283C/qr-codes/qr-biq_lnk_01M14D2M8VFKYQCE7Z3A6HRXWP.svg",
      "format": "svg",
      "logo": "app"
    },
    "clicks_count": 0,
    "leads_count": 0,
    "sales_count": 0,
    "revenue": 0,
    "revenue_currency": "USD",
    "clicked_at": null,
    "safety_status": "clear",
    "created_at": "2026-08-28T16:42:19+00:00",
    "updated_at": "2026-08-28T16:42:19+00:00"
  },
  "status": "success"
}
```

The API never returns the internal numeric link or workspace ID. It also never
returns the password hash or plaintext password.

## Pending safety response

If a destination redirects or needs deeper inspection, Biqli atomically creates
the link and returns `202 Accepted` with `safety_status: "pending"`.

The following abridged response highlights the pending state:

```json theme={null}
{
  "link": {
    "id": "biq_lnk_01M14D2M8VFKYQCE7Z3A6HRXWP",
    "short_url": "https://biq.li/summer-product",
    "long_url": "https://redirect.example.com/product",
    "safety_status": "pending"
  },
  "status": "pending",
  "message": "The link was created and is pending a safety check."
}
```

The short URL shows a pending-safety response and does not redirect until the
background check marks every destination clear. A failed background check
quarantines the link. A destination blocked by the synchronous checks returns
`422 url_blocked` and no link is created.

## Plans, quotas, and atomicity

Workspace plan permissions and quotas apply before Biqli writes the link.
Plan-gated options include custom aliases, passwords, activation and expiration,
click expiration, UTM parameters, dynamic routing, and unbranded QR codes.

* A missing plan entitlement returns `403 upgrade_required`.
* Exhausted monthly link quota returns `403 quota_exceeded`.
* The API rate limit uses the plan attached to the key's workspace, not another
  workspace owned by the same user.
* Link fields, rules, tags, folders, pixels, and the attached QR code are created
  as one operation. A failure rolls back the database changes and removes a QR
  file created by that failed operation.

The endpoint rejects unknown top-level fields. It also rejects `workspaceId`,
`workspace_id`, `accessToken`, `type`, and `type_id`; those are internal or
legacy fields and are never part of the workspace API contract.

## Errors

Every error uses the same envelope:

```json theme={null}
{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key requires the tags.view permission to use this resource.",
    "details": {
      "required_permission": "tags.view"
    }
  },
  "request_id": "ae437f49-30a3-4d55-bca6-dc523f2efcb3"
}
```

The same request ID is returned in the `X-Biq-Request-Id` response header. You
can send your own `X-Biq-Request-Id` value up to 100 characters for distributed
tracing. Include it when contacting support.

| HTTP status | Error code              | Meaning                                                                                          |
| ----------- | ----------------------- | ------------------------------------------------------------------------------------------------ |
| `401`       | `invalid_token`         | The workspace API key is missing, malformed, invalid, or revoked.                                |
| `403`       | `insufficient_scope`    | The key lacks a required API permission, or its user cannot perform the action in the workspace. |
| `403`       | `upgrade_required`      | The workspace plan does not include a requested feature.                                         |
| `403`       | `quota_exceeded`        | The workspace has exhausted its link creation quota.                                             |
| `404`       | `resource_not_found`    | An attached public ID is unavailable in this workspace.                                          |
| `409`       | `alias_taken`           | The requested alias already exists on the selected domain.                                       |
| `409`       | `external_id_taken`     | The external ID already exists in the workspace.                                                 |
| `422`       | `url_blocked`           | A destination failed synchronous URL safety checks.                                              |
| `422`       | `validation_error`      | A field is invalid, unsupported, or inconsistent with another field.                             |
| `429`       | `rate_limit_exceeded`   | The workspace exceeded its plan's API request limit.                                             |
| `500`       | `internal_server_error` | An unexpected server error occurred.                                                             |

Validation errors include an `error.details.errors` object keyed by field.
Upgrade errors can include `current_plan`, `required_plan`, and `feature`.
Quota errors include current workspace usage details.

<Warning>
  This endpoint does not currently accept an idempotency key. Retrying a request
  after an ambiguous network failure can create another random-alias link. A
  caller-controlled `alias` or unique `external_id` provides conflict protection
  for workflows that require retry-safe creation.
</Warning>

## Shared API behavior

Authentication is workspace-scoped; see [Authentication](/docs/api-reference/authentication). Errors use the standard envelope and request IDs described in [Errors](/docs/api-reference/errors), and requests are subject to [Rate limits](/docs/api-reference/rate-limits).


## OpenAPI

````yaml POST /v1/link
openapi: 3.1.0
info:
  title: Biqli API
  version: 1.0.0
  description: Workspace-scoped REST API for Biqli.
servers:
  - url: https://biq.li/api
security:
  - bearerAuth: []
paths:
  /v1/link:
    post:
      tags:
        - Links
      summary: Create a link
      description: >-
        Creates one short link in the workspace bound to the API key. Requires
        links.create.
      operationId: link.store
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateLinkRequest'
            examples:
              minimal:
                summary: Minimal link
                value:
                  long_url: https://example.com/product
              complete:
                summary: Link with routing, preview, attachments, and QR code
                value:
                  long_url: https://example.com/product
                  name: Summer campaign
                  external_id: campaign-link-1842
                  domain_id: biq_dom_01M14C6KQ6SG2GKMCV7HQ9A1QT
                  alias: summer-product
                  active: true
                  password: launch-2026
                  activates_at: '2026-09-01T08:00:00Z'
                  expires_at: '2026-10-01T08:00:00Z'
                  exp_clicks_rule:
                    key: 1000
                    value: https://example.com/campaign-ended
                  utm: source=newsletter&medium=email&campaign=summer
                  geo_rules:
                    - key: us
                      value: https://example.com/us
                  device_rules:
                    - key: mobile
                      value: https://m.example.com/product
                  platform_rules:
                    - key: ios
                      value: https://apps.apple.com/app/example
                  folder_ids:
                    - biq_fld_01M14C93RJD7W46PFJX9B1TVYH
                  pixel_ids:
                    - biq_pxl_01M14CBJNRXPW4Y22ZTA7F9W3J
                  tag_ids:
                    - biq_tag_01M14CC1TW7AQ6DWZG9TMRH0PQ
                  conversion_tracking_enabled: true
                  allow_search_engine_indexing: false
                  proxy: true
                  title: Summer sale
                  description: Explore the summer collection.
                  image: https://cdn.example.com/previews/summer.jpg
                  create_qr_code: true
                  qr_logo: app
      responses:
        '201':
          description: The link was created and is ready to redirect.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateLinkResponse'
        '202':
          description: >-
            The link was created but remains unavailable until its asynchronous
            safety check clears.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PendingLinkResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    CreateLinkRequest:
      type: object
      additionalProperties: false
      required:
        - long_url
      properties:
        long_url:
          type: string
          description: Destination URL. Biqli normalizes a missing scheme to HTTPS.
          minLength: 3
          maxLength: 1000
          examples:
            - https://example.com/product
        name:
          type:
            - string
            - 'null'
          description: Internal label for the link.
          maxLength: 150
        external_id:
          type:
            - string
            - 'null'
          description: Caller-controlled identifier, unique within the API key's workspace.
          maxLength: 255
        domain_id:
          type:
            - string
            - 'null'
          description: >-
            Public ID of a custom domain available to this workspace. Omit it to
            use the Biqli default domain.
          pattern: ^biq_dom_[0-9A-HJKMNP-TV-Z]{26}$
        alias:
          type:
            - string
            - 'null'
          description: >-
            Requested short-link alias. The configured alias character and
            length rules apply.
          maxLength: 50
        active:
          type: boolean
          description: Whether the link can redirect after it passes safety checks.
          default: true
        password:
          type:
            - string
            - 'null'
          description: Password visitors must enter before redirecting.
          maxLength: 250
        activates_at:
          type:
            - string
            - 'null'
          format: date-time
          description: ISO 8601 date and time when the link becomes active.
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
          description: >-
            Future ISO 8601 expiration date and time. It must be later than
            activates_at.
        exp_clicks_rule:
          oneOf:
            - $ref: '#/components/schemas/ClickExpirationRule'
            - type: 'null'
        utm:
          type:
            - string
            - 'null'
          description: >-
            Ampersand-separated UTM parameters without a leading question mark.
            Biqli prefixes keys with utm_ when needed.
          maxLength: 2000
          examples:
            - source=newsletter&medium=email&campaign=summer
        geo_rules:
          $ref: '#/components/schemas/TargetingRules'
        device_rules:
          $ref: '#/components/schemas/TargetingRules'
        platform_rules:
          $ref: '#/components/schemas/TargetingRules'
        folder_ids:
          type:
            - array
            - 'null'
          description: Unique public IDs of folders in this workspace.
          maxItems: 100
          uniqueItems: true
          items:
            type: string
            pattern: ^biq_fld_[0-9A-HJKMNP-TV-Z]{26}$
        pixel_ids:
          type:
            - array
            - 'null'
          description: Unique public IDs of tracking pixels in this workspace.
          maxItems: 100
          uniqueItems: true
          items:
            type: string
            pattern: ^biq_pxl_[0-9A-HJKMNP-TV-Z]{26}$
        tag_ids:
          type:
            - array
            - 'null'
          description: Unique public IDs of tags in this workspace.
          maxItems: 100
          uniqueItems: true
          items:
            type: string
            pattern: ^biq_tag_[0-9A-HJKMNP-TV-Z]{26}$
        conversion_tracking_enabled:
          type: boolean
          description: Append a Biqli click ID for conversion attribution.
          default: false
        allow_search_engine_indexing:
          type: boolean
          description: Allow search engines to index the short-link page.
          default: false
        proxy:
          type: boolean
          description: >-
            Enable the custom social preview supplied by title, description, and
            image.
          default: false
        title:
          type:
            - string
            - 'null'
          description: Custom social preview title. Requires proxy=true.
          maxLength: 255
        description:
          type:
            - string
            - 'null'
          description: Custom social preview description. Requires proxy=true.
          maxLength: 1000
        image:
          type:
            - string
            - 'null'
          format: uri
          description: >-
            Public HTTPS URL for the custom social preview image. Requires
            proxy=true. Private and local hosts are rejected.
          maxLength: 2048
        create_qr_code:
          type: boolean
          description: Generate and attach an SVG QR code for this short link.
          default: false
        qr_logo:
          type:
            - string
            - 'null'
          description: >-
            Use the Biqli app logo or no center logo. Requires
            create_qr_code=true. The none option is plan-gated.
          enum:
            - app
            - none
            - null
          default: app
    CreateLinkResponse:
      type: object
      required:
        - link
        - status
      properties:
        link:
          $ref: '#/components/schemas/CreatedLink'
        status:
          type: string
          const: success
    PendingLinkResponse:
      type: object
      required:
        - link
        - status
        - message
      properties:
        link:
          $ref: '#/components/schemas/CreatedLink'
        status:
          type: string
          const: pending
        message:
          type: string
          examples:
            - The link was created and is pending a safety check.
    ClickExpirationRule:
      type: object
      additionalProperties: false
      required:
        - key
      properties:
        key:
          type: integer
          minimum: 1
          description: Number of clicks after which the link expires.
        value:
          type:
            - string
            - 'null'
          description: Optional URL to use after the click threshold is reached.
          maxLength: 1000
    TargetingRules:
      type:
        - array
        - 'null'
      description: Destination overrides evaluated for matching visitors.
      maxItems: 100
      items:
        $ref: '#/components/schemas/TargetingRule'
    CreatedLink:
      type: object
      required:
        - id
        - external_id
        - short_url
        - long_url
        - name
        - domain_id
        - alias
        - active
        - has_password
        - activates_at
        - expires_at
        - exp_clicks_rule
        - utm
        - folder_ids
        - pixel_ids
        - tag_ids
        - conversion_tracking_enabled
        - allow_search_engine_indexing
        - proxy
        - title
        - description
        - image
        - qr_code
        - geo_rules
        - device_rules
        - platform_rules
        - clicks_count
        - leads_count
        - sales_count
        - revenue
        - revenue_currency
        - clicked_at
        - safety_status
        - created_at
        - updated_at
      properties:
        id:
          type: string
          description: Public link ID. Internal numeric IDs are never returned.
          pattern: ^biq_lnk_[0-9A-HJKMNP-TV-Z]{26}$
        external_id:
          type:
            - string
            - 'null'
          description: Caller-controlled identifier, unique within the workspace.
        short_url:
          type: string
          format: uri
        long_url:
          type: string
        name:
          type:
            - string
            - 'null'
        domain_id:
          type:
            - string
            - 'null'
          pattern: ^biq_dom_[0-9A-HJKMNP-TV-Z]{26}$
        alias:
          type:
            - string
            - 'null'
        active:
          type: boolean
        has_password:
          type: boolean
        activates_at:
          type:
            - string
            - 'null'
          format: date-time
        expires_at:
          type:
            - string
            - 'null'
          format: date-time
        exp_clicks_rule:
          oneOf:
            - $ref: '#/components/schemas/ClickExpirationRule'
            - type: 'null'
        utm:
          type:
            - string
            - 'null'
        geo_rules:
          type: array
          items:
            $ref: '#/components/schemas/TargetingRule'
        device_rules:
          type: array
          items:
            $ref: '#/components/schemas/TargetingRule'
        platform_rules:
          type: array
          items:
            $ref: '#/components/schemas/TargetingRule'
        folder_ids:
          type: array
          items:
            type: string
        pixel_ids:
          type: array
          items:
            type: string
        tag_ids:
          type: array
          items:
            type: string
        conversion_tracking_enabled:
          type: boolean
        allow_search_engine_indexing:
          type: boolean
        proxy:
          type: boolean
        title:
          type:
            - string
            - 'null'
        description:
          type:
            - string
            - 'null'
        image:
          type:
            - string
            - 'null'
        qr_code:
          oneOf:
            - $ref: '#/components/schemas/AttachedQrCode'
            - type: 'null'
        clicks_count:
          type: integer
          minimum: 0
          description: Total recorded clicks.
        leads_count:
          type: integer
          minimum: 0
          description: Total attributed lead events.
        sales_count:
          type: integer
          minimum: 0
          description: Total attributed sale events.
        revenue:
          type: number
          minimum: 0
          description: Attributed sales amount normalized to USD.
        revenue_currency:
          type: string
          const: USD
        clicked_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Time of the most recent recorded click.
        safety_status:
          type: string
          enum:
            - clear
            - pending
            - quarantined
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    ApiError:
      type: object
      required:
        - error
        - request_id
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - invalid_token
                - insufficient_scope
                - upgrade_required
                - quota_exceeded
                - resource_not_found
                - domain_taken
                - alias_taken
                - external_id_taken
                - folder_name_taken
                - tag_name_taken
                - pixel_name_taken
                - biolink_name_taken
                - method_not_allowed
                - url_blocked
                - dns_verification_failed
                - validation_error
                - rate_limit_exceeded
                - internal_server_error
            message:
              type: string
            details:
              type: object
              additionalProperties: true
        request_id:
          type: string
          description: Request identifier to include when contacting support.
    TargetingRule:
      type: object
      additionalProperties: false
      required:
        - key
        - value
      properties:
        key:
          type: string
          description: Match value, such as a country code, device, or platform.
          maxLength: 250
        value:
          type: string
          description: Destination URL used when the rule matches.
          maxLength: 1000
    AttachedQrCode:
      type: object
      required:
        - url
        - format
        - logo
      properties:
        url:
          type: string
          format: uri
        format:
          type: string
          const: svg
        logo:
          type: string
          enum:
            - app
            - none
  responses:
    Unauthorized:
      $ref: '#/components/responses/ApiErrorResponse'
      description: The workspace API key is missing, invalid, or revoked.
    Forbidden:
      $ref: '#/components/responses/ApiErrorResponse'
      description: >-
        The key lacks a required scope, the workspace must upgrade, or its quota
        is exhausted.
    NotFound:
      $ref: '#/components/responses/ApiErrorResponse'
      description: >-
        The requested resource or referenced public ID is unavailable in the
        key's workspace.
    Conflict:
      $ref: '#/components/responses/ApiErrorResponse'
      description: >-
        A unique alias, external ID, custom domain, or workspace resource name
        is already in use.
    UnprocessableEntity:
      $ref: '#/components/responses/ApiErrorResponse'
      description: >-
        The payload is invalid, a destination was blocked, or domain DNS
        verification is not ready.
    RateLimited:
      description: The workspace exceeded its plan's API rate limit.
      headers:
        RateLimit-Policy:
          description: Current IETF HTTPAPI quota policy as a structured field.
          schema:
            type: string
            example: '"workspace-api";q=1000;w=60'
        RateLimit:
          description: Current IETF HTTPAPI service limit as a structured field.
          schema:
            type: string
            example: '"workspace-api";r=0;t=17'
        Retry-After:
          description: Seconds to wait before retrying the request.
          schema:
            type: integer
            minimum: 0
            example: 17
        X-RateLimit-Limit:
          description: Legacy maximum request count for the current window.
          schema:
            type: integer
            minimum: 1
            example: 1000
        X-RateLimit-Remaining:
          description: Legacy remaining request count.
          schema:
            type: integer
            minimum: 0
            example: 0
        X-RateLimit-Reset:
          description: Legacy reset time as a UTC Unix timestamp.
          schema:
            type: integer
            format: int64
            example: 1788126519
        X-Biq-Request-Id:
          description: Request identifier for support and tracing.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    InternalError:
      $ref: '#/components/responses/ApiErrorResponse'
      description: The request failed unexpectedly.
    ApiErrorResponse:
      description: API error.
      headers:
        X-Biq-Request-Id:
          description: Request identifier for support and tracing.
          schema:
            type: string
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Workspace API key
      description: A workspace API key beginning with biqli_.

````