Introduction

How the Clakta REST API is organized, and the conventions every endpoint follows.

Clakta exposes a REST API over HTTPS. Every endpoint takes and returns JSON, uses standard HTTP verbs for intent and standard status codes for outcome, and is authenticated with an API key sent as a bearer token.

Base URL

All requests go to a single host:

Paths in this reference are relative to that host, so POST /v1/orders means POST https://api.clakta.com/v1/orders.

Conventions

Verbs carry intent. GET reads, POST creates, PATCH partially updates, DELETE removes. A PATCH only changes the fields you send.
JSON in, JSON out. Send Content-Type: application/json on any request with a body. Responses are always JSON, including errors.
Successful responses are wrapped. Write endpoints return a human-readable message alongside the affected resource in data.
Money is an integer on the way out. Prices are accepted as decimals (10.4 meaning $10.40) and returned in the smallest currency unit (1040). Currencies are ISO 4217 codes.
Timestamps are ISO 8601 in UTC, for example 2026-07-29T14:03:00.000Z.

Identifying a project

Most endpoints act on a single project, and you can identify it by either its ID (proj_…) or its slug. Where the project is passed depends on the verb:

Verb	Where the project goes
`POST`, `PATCH`	`projectId` in the JSON body
`GET`, `DELETE`	`projectId` query parameter

A request that resolves to a project your API key cannot reach returns 404 not_found rather than 403, so the API never confirms the existence of resources you have no access to.

Rate limits

Requests are rate limited per API key, per minute, based on your team's plan:

Plan	Requests / minute
Free	60
Pro	600
Business	1,200
Enterprise	3,000

Every response carries the current state of your budget:

X-RateLimit-Limit — your ceiling for the window
X-RateLimit-Remaining — requests left in the window
X-RateLimit-Reset — when the window resets
Retry-After — sent on 429, how long to wait

Treat 429 rate_limit_exceeded as retryable: back off exponentially rather than retrying immediately.

Errors

Failures return a non-2xx status and a JSON body describing what went wrong, including a link to the relevant section of the errors reference.

Next steps

Authentication — create an API key and scope it
Errors — what each error code means and how to react