> ## 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.

# Introduction

> Build server-side integrations with Biqli's workspace-scoped REST API.

The Biqli API lets you programmatically create and manage resources in a
Biqli workspace. It uses predictable REST endpoints, JSON payloads, and
workspace-scoped API keys.

<Note>
  The current API is designed for server-to-server integrations that manage
  one workspace. It is not a browser API or an OAuth partner authorization
  flow.
</Note>

## What you can build

<Columns cols={2}>
  <Card title="Links" icon="link" href="/docs/api-reference/links/list">
    Create, retrieve, update, list, count, and bulk-manage short links.
  </Card>

  <Card title="Custom domains" icon="globe" href="/docs/api-reference/domains/list">
    Connect domains, retrieve DNS instructions, and verify configuration.
  </Card>

  <Card title="Folders and tags" icon="folder" href="/docs/api-reference/folders/list">
    Organize links and manage their folder and tag associations.
  </Card>

  <Card title="Tracking pixels" icon="chart-line" href="/docs/api-reference/tracking-pixels/list">
    Manage supported retargeting-pixel configurations and link attachments.
  </Card>

  <Card title="QR codes" icon="qrcode" href="/docs/api-reference/qr-codes/list">
    Create and style standalone static or dynamic QR codes.
  </Card>

  <Card title="Biolinks" icon="address-card" href="/docs/api-reference/biolinks/list">
    Manage Biolink page-level settings without exposing frontend-owned widgets.
  </Card>
</Columns>

## Quick start

<Steps>
  <Step title="Create a workspace API key">
    Open **Workspace settings → API Keys**, select **Create API key**, and grant
    only the permissions your integration needs. The secret is displayed once.

    See [Authentication](/docs/api-reference/authentication) for the complete
    key and permission model.
  </Step>

  <Step title="Store the key on your server">
    Save the key in an environment variable or secret manager. Never include it
    in browser code, mobile applications, public repositories, or logs.

    ```bash .env theme={null}
    BIQLI_API_KEY=biqli_xxxxxxxxxxxxxxxxxxxxxxxx
    ```
  </Step>

  <Step title="Make your first request">
    List the first ten links in the key's workspace:

    <CodeGroup>
      ```bash cURL theme={null}
      curl --request GET \
        --url 'https://biq.li/api/v1/link?page_size=10' \
        --header "Authorization: Bearer $BIQLI_API_KEY" \
        --header 'Accept: application/json'
      ```

      ```javascript Node.js theme={null}
      const response = await fetch(
        'https://biq.li/api/v1/link?page_size=10',
        {
          headers: {
            Authorization: `Bearer ${process.env.BIQLI_API_KEY}`,
            Accept: 'application/json',
          },
        },
      );

      const data = await response.json();
      if (!response.ok) throw new Error(data.error?.message || 'Request failed');
      console.log(data);
      ```

      ```php PHP theme={null}
      <?php

      $request = curl_init('https://biq.li/api/v1/link?page_size=10');
      curl_setopt_array($request, [
          CURLOPT_RETURNTRANSFER => true,
          CURLOPT_HTTPHEADER => [
              'Authorization: Bearer ' . getenv('BIQLI_API_KEY'),
              'Accept: application/json',
          ],
      ]);

      $response = curl_exec($request);
      if ($response === false) {
          throw new RuntimeException(curl_error($request));
      }

      $data = json_decode($response, true, flags: JSON_THROW_ON_ERROR);
      curl_close($request);
      print_r($data);
      ```

      ```python Python theme={null}
      import json
      import os
      from urllib.request import Request, urlopen

      request = Request(
          "https://biq.li/api/v1/link?page_size=10",
          headers={
              "Authorization": f"Bearer {os.environ['BIQLI_API_KEY']}",
              "Accept": "application/json",
          },
      )

      with urlopen(request) as response:
          print(json.load(response))
      ```
    </CodeGroup>
  </Step>
</Steps>

## Base URL

All endpoints use HTTPS and are versioned under this base URL:

```text theme={null}
https://biq.li/api/v1
```

Unencrypted HTTP is not supported. Endpoint pages show paths relative to this
base URL, such as `GET /link`.

## Authentication and workspace scope

Send your `biqli_...` secret in the `Authorization` header:

```http theme={null}
Authorization: Bearer biqli_xxxxxxxxxxxxxxxxxxxxxxxx
```

The key selects exactly one workspace. Do not send `workspaceId`,
`workspace_id`, internal numeric IDs, or frontend model fields. Requests are
also checked against the key's resource permissions and the key creator's
current workspace role.

Read [Authentication](/docs/api-reference/authentication) for creation,
permissions, rotation, and revocation guidance.

## API conventions

* Send `Accept: application/json` on every request.
* Send `Content-Type: application/json` when a request has a JSON body.
* `PATCH` changes only fields included in the request; omitted fields are preserved.
* Successful creates return `201 Created` unless an endpoint documents another result.
* Successful deletes return `204 No Content` with an empty body.
* Collection endpoints use cursor pagination with `starting_after` and
  `ending_before`; see [Pagination](/docs/api-reference/pagination).
* `external_id` lets your system address supported resources with its own stable identifier.

### Public resource IDs

Biqli returns typed public identifiers instead of internal database IDs:

| Resource       | Prefix     |
| :------------- | :--------- |
| Link           | `biq_lnk_` |
| Domain         | `biq_dom_` |
| Folder         | `biq_fld_` |
| Tag            | `biq_tag_` |
| Tracking pixel | `biq_pxl_` |
| QR code        | `biq_qr_`  |
| Biolink        | `biq_bio_` |

A valid identifier belonging to another workspace returns the same
`404 resource_not_found` response as an identifier that does not exist.

## Responses and errors

Successful JSON responses contain the named resource and a success status:

```json theme={null}
{
  "link": {
    "id": "biq_lnk_01M14D2M8VFKYQCE7Z3A6HRXWP"
  },
  "status": "success"
}
```

Errors use one machine-readable envelope:

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "The request data is invalid.",
    "details": {
      "errors": {
        "long_url": ["The long url field is required."]
      }
    }
  },
  "request_id": "ae437f49-30a3-4d55-bca6-dc523f2efcb3"
}
```

Every API error returns the request identifier in both the JSON body and the
`X-Biq-Request-Id` response header. You may send your own
`X-Biq-Request-Id` value of up to 100 characters to correlate a request across
services. Include it when contacting support.

| Status | Meaning                                                           |
| :----- | :---------------------------------------------------------------- |
| `401`  | The API key is missing, invalid, or revoked.                      |
| `403`  | The key lacks permission or the workspace cannot use the feature. |
| `404`  | The resource is unavailable in the key's workspace.               |
| `409`  | A unique identifier or association conflicts.                     |
| `422`  | One or more request values failed validation.                     |
| `429`  | The workspace's request rate limit was exceeded.                  |
| `500`  | An unexpected server error occurred.                              |

Read [Errors](/docs/api-reference/errors) for stable error codes, structured
details, retry decisions, and partial bulk failures.

## Rate limits

Biqli applies the workspace plan's fixed one-minute request allowance.
Successful responses expose the current quota through the IETF HTTPAPI
`RateLimit-Policy` and `RateLimit` fields. A throttled request returns
`429 Too Many Requests`, the same quota fields, and `Retry-After`.

Read [Rate limits](/docs/api-reference/rate-limits) for field syntax, quota
scope, and retry guidance.

## Next steps

<Columns cols={2}>
  <Card title="Authentication" icon="key" href="/docs/api-reference/authentication">
    Create a key and choose the least-privilege permission set.
  </Card>

  <Card title="Rate limits" icon="gauge-high" href="/docs/api-reference/rate-limits">
    Read quota fields and implement safe throttling behavior.
  </Card>

  <Card title="Errors" icon="circle-exclamation" href="/docs/api-reference/errors">
    Handle stable error codes, request IDs, and partial bulk failures.
  </Card>

  <Card title="Pagination" icon="arrows-left-right" href="/docs/api-reference/pagination">
    Traverse every list endpoint with forward and backward cursors.
  </Card>
</Columns>