API
Headers
Request and response headers for tokens, tracing, caching, safe updates and rate limits.
Most calls need only Authorization, plus Content-Type when you send a body. The other headers help you trace, cache and avoid lost updates.
Request headers
| Header | When to send it | Example |
|---|---|---|
Authorization | Every call that needs sign-in. | Bearer YOUR_ACCESS_TOKEN |
Content-Type | Every call with a JSON body. | application/json |
If-Match | On update, to reject it if the record changed since you read it. Returns 412 record_changed then. | "2026-10-23T07:04:27.858424Z" |
If-None-Match | On a repeat read, to skip the body when nothing changed. Returns 304. | "2026-10-23T07:04:27.858424Z" |
X-Request-ID | Your own trace ID. Kanesh echoes it back and logs it. | checkout-7f3a |
X-Workspace-ID | With paths that have no :workspace, such as /api/v1/collections. | 1d6035d32788a9046a1e3209059e00a3 |
| Custom token header | Only when the server sets AUTH_TOKEN_HEADER, such as X-Api-Key. Send the raw token. | YOUR_ACCESS_TOKEN |
Send one credential only. A token in two headers, or a token plus a cookie, returns 401.
Response headers
| Header | What it tells you |
|---|---|
ETag | Version of a single record. Use it with If-Match or If-None-Match. |
X-Request-ID | ID of this request, also in meta.request_id. Yours if you sent one. |
X-Response-Time | Server time for the request, such as 1.906ms. |
Retry-After | With 429, seconds to wait before retrying. |
Content-Disposition | On file downloads, the file name. |
Cache-Control | no-store on API data, so proxies never cache private records. |
Kanesh also sends security headers such as X-Content-Type-Options: nosniff, X-Frame-Options: DENY and Referrer-Policy. See Security.
Example: read, then update safely
# 1. Read and keep the ETag
curl -i 'http://127.0.0.1:8080/api/v1/workspaces/YOUR_WORKSPACE_ID/collections/YOUR_COLLECTION_ID/records/YOUR_RECORD_ID' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'X-Request-ID: checkout-7f3a'
# 2. Update only if it is still that version
curl -X PATCH 'http://127.0.0.1:8080/api/v1/workspaces/YOUR_WORKSPACE_ID/collections/YOUR_COLLECTION_ID/records/YOUR_RECORD_ID' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-H 'If-Match: "2026-10-23T07:04:27.858424Z"' \
--data '{"stage":"Won"}'Browser apps
A browser on another origin can only send and read these headers when CORS allows them. The defaults already allow every header on this page.