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

# API reference

> Base URL, conventions and the shape of every response.

Everything below is generated from Unif's OpenAPI document, so it matches what the API actually
does. Each endpoint page has a playground — paste a key and send a real request.

```
https://api.unif.dev/v1
```

## Authentication

Every request carries a bearer token.

```bash theme={null}
curl https://api.unif.dev/v1/me \
  -H "Authorization: Bearer unif_sk_live_8f3c1a9e4b2d8065f1a3c7e9b5d2408f"
```

Keys are scoped to one workspace. A `unif_sk_test_` key hits the same endpoints against
[sandbox fixtures](/docs/platform/sandbox) and costs nothing. See
[Authentication](/docs/authentication).

## Conventions

<CardGroup cols={2}>
  <Card title="No envelope" icon="box-open">
    A `200` body is the object itself. Success and failure are carried by the HTTP status code.
  </Card>

  <Card title="Cursor pagination" icon="list-ol">
    Lists return `has_more` and `next_cursor`. Loop on `has_more`, never on page length.
  </Card>

  <Card title="Self-describing records" icon="tag">
    Every object repeats the `period` and `currency` it was measured under, plus a `meta` block.
  </Card>

  <Card title="Ratios, not percentages" icon="percent">
    Every `*_rate` and `*_share` field is a ratio. `0.25` is 25%.
  </Card>
</CardGroup>

## Search takes POST

The five `search` endpoints use `POST` with a JSON body. Filter sets are nested and open-ended, and
a body keeps them readable and replayable — but the calls are read-only, safe to retry, and need no
`Idempotency-Key`. See [Search](/docs/workflows/search#why-post).

## Response headers

| Header                                        | On                                               |
| --------------------------------------------- | ------------------------------------------------ |
| `X-Request-Id`                                | Every response — log it, and quote it to support |
| `X-Unif-Credits-Charged`                      | Billable responses                               |
| `X-Unif-Credits-Remaining`                    | Billable responses                               |
| `X-RateLimit-Limit` / `-Remaining` / `-Reset` | Every response                                   |
| `Retry-After`                                 | `429` responses                                  |
| `Unif-Version`                                | Every response                                   |

## Errors

```json theme={null}
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "filters.revenue.gte must be a non-negative number.",
    "param": "filters.revenue.gte",
    "doc_url": "https://unif.dev/docs/platform/errors#parameter_invalid",
    "request_id": "req_01k3m9x7v2q8r4t6y0b1n5d7fa"
  }
}
```

Branch on `type` and `code`; never parse `message`. Retry `429` and `5xx`, nothing else. The full
taxonomy is in [Errors](/docs/platform/errors).

## Endpoint groups

<CardGroup cols={2}>
  <Card title="Meta" icon="circle-info" href="/api-reference/meta/get-current-workspace">
    Workspace, channel entitlements and field coverage. All free to call.
  </Card>

  <Card title="Entities" icon="cubes" href="/api-reference/shops/search-shops">
    Search, detail and timeseries for shops, products, creators, videos, livestreams and
    categories.
  </Card>

  <Card title="Resolution" icon="fingerprint" href="/api-reference/resolution/resolve-identifiers-to-entities">
    Turn URLs, handles and native IDs into stable Unif IDs, with or without data attached.
  </Card>

  <Card title="Jobs" icon="layer-group" href="/api-reference/jobs/create-a-job">
    Bulk enrichment, deep search and exports, collected by webhook.
  </Card>

  <Card title="Lists and trackers" icon="bell" href="/api-reference/lists/create-a-list">
    Saved sets and the scheduled re-checks that watch them.
  </Card>

  <Card title="Usage" icon="coins" href="/api-reference/usage/get-credit-balance">
    Credit balance and the per-request ledger.
  </Card>
</CardGroup>