# Link in bio API documentation

> BioFlow REST API docs: API-key auth, 22 operations across pages, contacts, files, analytics and webhooks — RFC 9457 errors, rate limits, and idempotency.

Page: https://getbioflow.com/docs/api

{/* Generated by apps/docs/scripts/generate-api-surface.mjs from openapi/v1.json — do not edit by hand. */}

A REST API for the page your users keep in their bio: read and edit pages, add
blocks, publish, capture contacts, pull analytics, and manage webhooks — all at
`https://app.getbioflow.com/v1`, described by an OpenAPI 3.1 spec, available on Creator and Pro.

## Quickstart [#quickstart]

### 1. Get your API key [#1-get-your-api-key]

Create a key in the [developer console](https://app.getbioflow.com/dashboard/settings/developers) — pick its scopes
when you create it. `bf_live_` keys are production keys; `bf_test_` keys are
read-only.

### 2. List your pages [#2-list-your-pages]

Paste-runnable — swap in your key:

```bash
curl "https://app.getbioflow.com/v1/pages" \
  -H "Authorization: Bearer bf_live_YOUR_KEY"
```

```ts
const res = await fetch("https://app.getbioflow.com/v1/pages", {
  headers: {
    Authorization: "Bearer bf_live_YOUR_KEY",
  },
});

if (!res.ok) {
  // RFC 9457 problem+json — switch on the stable `code` field.
  const problem = await res.json();
  throw new Error(`BioFlow API ${problem.code}: ${problem.title}`);
}
const data = await res.json();
```

### 3. Read the response [#3-read-the-response]

A cursor page of your bio pages — every list endpoint uses the same
`{ data, has_more, next_cursor }` envelope:

```json
{
  "data": [
    {
      "id": "pg_abc123",
      "title": "My links",
      "slug": "maya",
      "status": "PUBLISHED",
      "block_count": 6,
      "public_url": "https://app.getbioflow.com/maya",
      "updated_at": "2026-07-20T12:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

## Authentication [#authentication]

Two equivalent header forms — send exactly one per request:

```
Authorization: Bearer bf_live_YOUR_KEY
x-api-key: bf_live_YOUR_KEY
```

`bf_live_` keys can do everything their scopes allow. `bf_test_` keys are
restricted to read operations — a write with a test key returns
[403 `test_key_read_only`](https://getbioflow.com/docs/api/errors/test-key-read-only), so test
integrations can never touch live data.

## Rate limits and quotas [#rate-limits-and-quotas]

| Plan    | Monthly quota       | Per-key burst    |
| ------- | ------------------- | ---------------- |
| Free    | — (no API access)   | —                |
| Creator | 10,000 requests/mo  | 60 requests/min  |
| Pro     | 100,000 requests/mo | 120 requests/min |

The quota counts successful /v1 requests per calendar month (UTC);
`GET /v1/usage` is free and shows where you stand. Every response carries IETF
draft-11 `RateLimit` / `RateLimit-Policy` headers. Bursting past the per-minute
limit returns [429 `rate_limited`](https://getbioflow.com/docs/api/errors/rate-limited); an exhausted
month returns [429 `quota_exhausted`](https://getbioflow.com/docs/api/errors/quota-exhausted);
Free-plan keys get
[403 `feature_not_enabled`](https://getbioflow.com/docs/api/errors/feature-not-enabled). Full plan
pricing on [getbioflow.com/pricing](https://getbioflow.com/pricing).

## Conventions [#conventions]

**Cursor pagination.** List endpoints return
`{ data, has_more, next_cursor }`. Pass `limit` for page size and feed
`next_cursor` back as `after` until `has_more` is false. Cursors are opaque —
never parse them.

**Idempotency keys.** Consequential POSTs (create page, add block, publish,
webhook management) accept an `Idempotency-Key` header — any unique string per
logical attempt. Retrying with the same key returns the original result instead
of repeating the action; reusing a key with a different body returns
[422 `idempotency_key_reused`](https://getbioflow.com/docs/api/errors/idempotency-key-reused).

## Errors [#errors]

Every error is `application/problem+json` with a stable `code` your
integration can branch on (never parse `title` or `detail`), a `type` URI that
resolves to the pages below, and a `request_id` to quote at support.

| Code                                                                       | Status | Meaning                                                        |
| -------------------------------------------------------------------------- | ------ | -------------------------------------------------------------- |
| [`invalid_request`](https://getbioflow.com/docs/api/errors/invalid-request)                           | 400    | The request body or parameters failed validation               |
| [`invalid_api_key`](https://getbioflow.com/docs/api/errors/invalid-api-key)                           | 401    | Missing, malformed, unknown, disabled, or expired API key      |
| [`insufficient_scope`](https://getbioflow.com/docs/api/errors/insufficient-scope)                     | 403    | The API key was not granted the required scope                 |
| [`feature_not_enabled`](https://getbioflow.com/docs/api/errors/feature-not-enabled)                   | 403    | The workspace plan does not include public API access          |
| [`test_key_read_only`](https://getbioflow.com/docs/api/errors/test-key-read-only)                     | 403    | Test-mode keys are restricted to read operations               |
| [`resource_not_found`](https://getbioflow.com/docs/api/errors/resource-not-found)                     | 404    | No resource with that ID exists in this workspace              |
| [`stale_snapshot`](https://getbioflow.com/docs/api/errors/stale-snapshot)                             | 409    | The draft changed since it was last read                       |
| [`idempotency_in_progress`](https://getbioflow.com/docs/api/errors/idempotency-in-progress)           | 409    | A request with this Idempotency-Key is still executing         |
| [`idempotency_key_reused`](https://getbioflow.com/docs/api/errors/idempotency-key-reused)             | 422    | This Idempotency-Key was already used with a different request |
| [`endpoint_verification_failed`](https://getbioflow.com/docs/api/errors/endpoint-verification-failed) | 422    | The webhook endpoint did not accept the signed test event      |
| [`endpoint_limit_reached`](https://getbioflow.com/docs/api/errors/endpoint-limit-reached)             | 422    | The workspace webhook endpoint limit was reached               |
| [`rate_limited`](https://getbioflow.com/docs/api/errors/rate-limited)                                 | 429    | Per-key rate limit exceeded                                    |
| [`quota_exhausted`](https://getbioflow.com/docs/api/errors/quota-exhausted)                           | 429    | Monthly API quota exhausted                                    |
| [`internal_error`](https://getbioflow.com/docs/api/errors/internal-error)                             | 500    | Something went wrong on our side                               |
| [`query_timeout`](https://getbioflow.com/docs/api/errors/query-timeout)                               | 503    | The request took too long to compute                           |

## Reference [#reference]

All 22 operations. Each links to its full reference page —
parameters, schemas, and a live request builder.

| Operation                                                          | Endpoint                                                                   | Scope                                                                       |
| ------------------------------------------------------------------ | -------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| [Get analytics summary](https://getbioflow.com/docs/api-reference/getAnalyticsSummary)        | `GET /v1/analytics/summary`                                                | analytics:read                                                              |
| [List contacts](https://getbioflow.com/docs/api-reference/listContacts)                       | `GET /v1/contacts`                                                         | contacts:read                                                               |
| [List files](https://getbioflow.com/docs/api-reference/listFiles)                             | `GET /v1/files`                                                            | files:read                                                                  |
| [List pages](https://getbioflow.com/docs/api-reference/listPages)                             | `GET /v1/pages`                                                            | pages:read                                                                  |
| [Create a page](https://getbioflow.com/docs/api-reference/createPage)                         | `POST /v1/pages`                                                           | pages:write                                                                 |
| [Delete a page](https://getbioflow.com/docs/api-reference/deletePage)                         | `DELETE /v1/pages/{page_id}`                                               | pages:write                                                                 |
| [Get a page](https://getbioflow.com/docs/api-reference/getPage)                               | `GET /v1/pages/{page_id}`                                                  | pages:read                                                                  |
| [Update a page](https://getbioflow.com/docs/api-reference/updatePage)                         | `PATCH /v1/pages/{page_id}`                                                | pages:write                                                                 |
| [Add a block](https://getbioflow.com/docs/api-reference/addBlock)                             | `POST /v1/pages/{page_id}/blocks`                                          | pages:write                                                                 |
| [Remove a block](https://getbioflow.com/docs/api-reference/removeBlock)                       | `DELETE /v1/pages/{page_id}/blocks/{block_id}`                             | pages:write                                                                 |
| [Publish a page](https://getbioflow.com/docs/api-reference/publishPage)                       | `POST /v1/pages/{page_id}/publish`                                         | publish                                                                     |
| [Get API usage](https://getbioflow.com/docs/api-reference/getUsage)                           | `GET /v1/usage`                                                            | pages:read, pages:write, analytics:read, contacts:read, files:read, publish |
| [List webhook endpoints](https://getbioflow.com/docs/api-reference/listWebhookEndpoints)      | `GET /v1/webhook-endpoints`                                                | webhooks:read                                                               |
| [Create a webhook endpoint](https://getbioflow.com/docs/api-reference/createWebhookEndpoint)  | `POST /v1/webhook-endpoints`                                               | webhooks:write                                                              |
| [Delete a webhook endpoint](https://getbioflow.com/docs/api-reference/deleteWebhookEndpoint)  | `DELETE /v1/webhook-endpoints/{endpoint_id}`                               | webhooks:write                                                              |
| [Get a webhook endpoint](https://getbioflow.com/docs/api-reference/getWebhookEndpoint)        | `GET /v1/webhook-endpoints/{endpoint_id}`                                  | webhooks:read                                                               |
| [Update a webhook endpoint](https://getbioflow.com/docs/api-reference/updateWebhookEndpoint)  | `PATCH /v1/webhook-endpoints/{endpoint_id}`                                | webhooks:write                                                              |
| [List deliveries](https://getbioflow.com/docs/api-reference/listWebhookDeliveries)            | `GET /v1/webhook-endpoints/{endpoint_id}/deliveries`                       | webhooks:read                                                               |
| [Resend a delivery](https://getbioflow.com/docs/api-reference/resendWebhookDelivery)          | `POST /v1/webhook-endpoints/{endpoint_id}/deliveries/{delivery_id}/resend` | webhooks:write                                                              |
| [Replay failed deliveries](https://getbioflow.com/docs/api-reference/replayWebhookDeliveries) | `POST /v1/webhook-endpoints/{endpoint_id}/replay`                          | webhooks:write                                                              |
| [Rotate the signing secret](https://getbioflow.com/docs/api-reference/rotateWebhookSecret)    | `POST /v1/webhook-endpoints/{endpoint_id}/rotate-secret`                   | webhooks:write                                                              |
| [Send a test event](https://getbioflow.com/docs/api-reference/testWebhookEndpoint)            | `POST /v1/webhook-endpoints/{endpoint_id}/test`                            | webhooks:write                                                              |

## Go deeper [#go-deeper]

* [Interactive reference](https://getbioflow.com/docs/api-reference) — every operation, schema, and example, rendered straight from the OpenAPI 3.1 spec.
* [Webhooks](https://getbioflow.com/docs/api/webhooks) — Standard Webhooks v1 signing, four event types, retries with replay, and verification snippets.
* [Changelog](https://getbioflow.com/changelog) — dated, factual platform updates, one URL per entry, RSS included.
* [TypeScript SDK](https://github.com/DevinoSolutions/bioflow-node) — open source, on npm as `@bioflow/sdk`: spec-generated types, typed errors, safe retries, pagination, webhook verification.
* [MCP server](https://getbioflow.com/mcp) — let Claude, ChatGPT, or any MCP client operate your workspace: 108 operations behind OAuth 2.1 with safety rails.
* [AI tooling](https://getbioflow.com/docs/ai) — llms.txt, llms-full.txt, markdown twins of every docs page, and the spec download.

Machine-readable spec: [/docs/api/openapi.json](https://getbioflow.com/docs/api/openapi.json) · this
page as markdown: [/docs/api.md](https://getbioflow.com/docs/api.md)
