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

# API reference

> Base URL, authentication, scopes, conventions, and errors for the ZeroClick REST API.

The ZeroClick REST API manages your catalog (sellers, services, meters, plans, and prices) and handles usage checks, usage reports, and analytics. The endpoint pages that follow are generated from the live OpenAPI document the API serves, so they always match production. The interactive playground on each page sends real requests; authenticate it with your API key.

## Base URL

```text theme={null}
https://api.zeroclick.io
```

All endpoints live under `/v1/` and speak JSON over HTTPS.

## Authentication

Authenticate with an API key as a bearer token. Keys start with `zc_` and are shown once. Create them in the [dashboard](https://dashboard.zeroclick.io) under Settings → API keys. See [keys and secrets](/integrate/keys-and-secrets).

```sh theme={null}
curl https://api.zeroclick.io/v1/sellers \
  -H "Authorization: Bearer $ZEROCLICK_API_KEY"
```

Every key is scoped to your organization and carries one or more scopes:

| Scope         | Grants                                                                                       |
| ------------- | -------------------------------------------------------------------------------------------- |
| `admin:read`  | Read catalog, analytics, and sandbox endpoints.                                              |
| `admin:write` | Create, update, and delete catalog and sandbox resources; create the Stripe onboarding link. |
| `usage:read`  | `POST /v1/usage/check` (allowance checks).                                                   |
| `usage:write` | `POST /v1/usage` (usage reports).                                                            |

Auth requirements differ by route group:

* **Usage** endpoints accept API keys only, with the split read and write scopes above. A dashboard session cannot call them.
* **Sellers** (including signing secrets), **Services**, **Meters**, **Plans**, **Plan meter prices**, **Analytics**, and **Sandbox** accept an API key (`admin:read` for reads, `admin:write` for writes) or a dashboard session.
* **API keys**, **Organizations**, **Users**, and **Stripe Connect** (except `POST /v1/stripe-connect/account-link`, which accepts `admin:write`) are dashboard-session-only. An API key gets `403 {"error":"auth_type_not_allowed"}`. This is why API keys cannot mint more API keys.

A key missing a required scope gets `403 {"error":"insufficient_scope"}`.

## Conventions

**Ids are prefixed strings**, returned in the `id` field and used in path and query parameters:

| Prefix   | Resource                                     |
| -------- | -------------------------------------------- |
| `sel_`   | Seller                                       |
| `svc_`   | Service                                      |
| `mtr_`   | Meter                                        |
| `pln_`   | Plan                                         |
| `pmp_`   | Plan meter price                             |
| `ak_`    | API key                                      |
| `hsec_`  | Signing secret (the `kid` in `zc-signature`) |
| `agt_`   | Buyer agent                                  |
| `zcreq_` | Forwarded request (`zc-request-id`)          |
| `use_`   | Usage event                                  |

**Lists are parent-scoped and unpaginated.** List endpoints filter by a required parent id (`GET /v1/services?sellerId=sel_…`, `GET /v1/meters?serviceId=svc_…`, `GET /v1/plan-meter-prices?planId=pln_…`) and return the full set in one response. There are no cursors or page parameters.

**Timestamps** are ISO 8601 strings in UTC. **There are no webhooks**; poll the analytics endpoints instead.

## Errors

Errors return a machine-readable envelope, with an optional human-readable `reason`:

```json theme={null}
{ "error": "insufficient_scope" }
```

| Status | Meaning                                                                                                     |
| ------ | ----------------------------------------------------------------------------------------------------------- |
| `400`  | Request validation failed.                                                                                  |
| `401`  | Missing, invalid, or revoked credentials.                                                                   |
| `402`  | Usage denial: `access_inactive`, `plan_expired`, `usage_exhausted`.                                         |
| `403`  | `organization_required`, `insufficient_scope`, `auth_type_not_allowed`, `organization_permission_required`. |
| `404`  | Resource missing, or owned by another organization; the two are deliberately indistinguishable.             |
| `409`  | Conflict, such as `duplicate_slug` on create or `meter_not_priced` on a usage report.                       |
| `422`  | Semantic rejection, such as `payg_price_not_whole_cents`.                                                   |

The [errors reference](/resources/errors) catalogs every code.