Customer API Reference

Beta

Browser-callable API for signed-in buyers and members on your site (https://{site}/api/v1/customer). Pair with <kanorio-login> and <kanorio-unit> from @kanorio/elements or call directly with a Customer Session Bearer token. Generated from packages/shared/openapi/customer.json.

The Agent API is in Beta. Endpoints may change in breaking ways; changes are announced in the changelog first. After general availability, breaking changes go through a deprecation period of at least 6 months.

Before you start

Authenticate buyers via passwordless email code or magic link (/auth/challenge → /auth/verify) to receive a Bearer session token.
All responses are private to the signed-in contact (Cache-Control: private, no-store).
POST /units/{id}/open verifies Entitlement, release schedule, and tier scope before minting a 600-second signed playback/download URL.

Base URL

https://{site}/api/v1/customer

REST API guide Download the OpenAPI spec Changelog

Endpoint descriptions match what AI assistants read.

Authentication, Session & Profile

POST/auth/challenge

customer_auth_challenge

Beta

Request a login code / magic link by email

Permission: none
Rate limit: Per-IP & per-site rate limited

curl

curl -X POST "https://{site}/api/v1/customer/auth/challenge" \
  -H "Content-Type: application/json" \
  -d '{"email":"reader@example.com","locale":"string","returnTo":"string","altcha":"string"}'

POST/auth/verify

customer_auth_verify

Beta

Exchange a code or magic-link token for a Bearer session

Permission: none
Rate limit: Per-IP & per-site rate limited

curl

curl -X POST "https://{site}/api/v1/customer/auth/verify" \
  -H "Content-Type: application/json" \
  -d '{"method":"code","email":"string","code":"string"}'

GET/me

customer_me

BetaRead-only

Current contact and sessions

Permission: Bearer knr_cat_* (customer session)
Rate limit: Per-IP & per-site rate limited

curl

curl -X GET "https://{site}/api/v1/customer/me" \
  -H "Authorization: Bearer $KANORIO_TOKEN"

DELETE/session

customer_session_revoke

Beta

Revoke sessions

Permission: Bearer knr_cat_* (customer session)
Rate limit: Per-IP & per-site rate limited

Query parameters

modestring
sessionIdstring

curl

curl -X DELETE "https://{site}/api/v1/customer/session" \
  -H "Authorization: Bearer $KANORIO_TOKEN"

Deliverables, Protected Units, Progress & Access

GET/deliverables

customer_deliverables_list

BetaRead-only

Deliverables the customer has access to

Permission: Bearer knr_cat_* (customer session)
Rate limit: Per-IP & per-site rate limited

curl

curl -X GET "https://{site}/api/v1/customer/deliverables" \
  -H "Authorization: Bearer $KANORIO_TOKEN"

GET/deliverables/{key}

customer_deliverables_get

BetaRead-only

Deliverable tree with per-unit access and progress

Permission: Bearer knr_cat_* (customer session)
Rate limit: Per-IP & per-site rate limited

Path parameters

keystringRequired

curl

curl -X GET "https://{site}/api/v1/customer/deliverables/{key}" \
  -H "Authorization: Bearer $KANORIO_TOKEN"

GET/deliverables/{key}/progress

customer_deliverables_progress

BetaRead-only

Progress summary for a deliverable

Permission: Bearer knr_cat_* (customer session)
Rate limit: Per-IP & per-site rate limited

Path parameters

keystringRequired

curl

curl -X GET "https://{site}/api/v1/customer/deliverables/{key}/progress" \
  -H "Authorization: Bearer $KANORIO_TOKEN"

POST/units/{id}/open

customer_units_open

Beta

Get a short-lived URL to read or download a unit

Permission: Bearer knr_cat_* (customer session)
Rate limit: Per-IP & per-site rate limited

Path parameters

idstringRequired

curl

curl -X POST "https://{site}/api/v1/customer/units/{id}/open" \
  -H "Authorization: Bearer $KANORIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode":"read"}'

POST/progress

customer_progress_report

Beta

Report playback/reading progress (server decides completion)

Permission: Bearer knr_cat_* (customer session)
Rate limit: Per-IP & per-site rate limited

curl

curl -X POST "https://{site}/api/v1/customer/progress" \
  -H "Authorization: Bearer $KANORIO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"unitId":"string","reports":[{"positionSeconds":1,"durationSeconds":1,"completed":true}]}'

GET/access/{id}

customer_access_check

BetaRead-only

Check access to a deliverable (id or key) or a unit (`type=unit`)

Permission: Bearer knr_cat_* (customer session)
Rate limit: Per-IP & per-site rate limited

Path parameters

idstringRequired

Query parameters

typestring

curl

curl -X GET "https://{site}/api/v1/customer/access/{id}" \
  -H "Authorization: Bearer $KANORIO_TOKEN"

Error codes

Failures always return an error object with code, message and details. Branch on code; the message wording may change. The table lists every error code and its HTTP status.

Example: the page changed after you read it (409)

{
  "error": {
    "code": "ITEM_NOT_FOUND",
    "message": "Item not found."
  }
}

Code	HTTP
BAD_REQUEST / QUERY_INVALID	400
UNAUTHORIZED / PREVIEW_UNAUTHORIZED	401
FORBIDDEN / NO_ENTITLEMENT / NOT_YET_RELEASED	403
NOT_FOUND / COLLECTION_NOT_FOUND / ITEM_NOT_FOUND	404
RATE_LIMITED	429

BAD_REQUEST / QUERY_INVALID

400

UNAUTHORIZED / PREVIEW_UNAUTHORIZED

401

FORBIDDEN / NO_ENTITLEMENT / NOT_YET_RELEASED

403

NOT_FOUND / COLLECTION_NOT_FOUND / ITEM_NOT_FOUND

404

RATE_LIMITED

429