API reference

API keys

Long-lived scoped credentials for scripts (P6-02): Authorization: Bearer co_…. A key does at most what its account does, within its scopes; each has its own per-minute limit, reported in X-RateLimit-*. Keys cannot manage keys.

Paths are relative to /api/v1 on your server.

GET/api-keys#

List API keys

Your own, or ?userId= for someone who manages accounts. Usage rides along: total, this minute, last used.

Authorisation: Bearer token or API key · Session cookie

Parameter	In	Type	Description
`userId`	query	`string (uuid)`
`includeRevoked`	query

200Success. application/json · object
400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope

POST/api-keys#

Create an API key

The secret is in this answer and nowhere else; only its hash is kept. Scopes may not exceed what the account can do.

Authorisation: Bearer token or API key · Session cookie
Body: application/json · object

201Success. application/json · object
400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. FORBIDDEN: a scope is asked for that the account does not have, the account is a child or guest, or the caller is itself an API key application/json · ErrorEnvelope

PATCH/api-keys/{id}#

Change an API key

Authorisation: Bearer token or API key · Session cookie
Body: application/json · object

Parameter	In	Type	Description
`id` required	path	`string (uuid)`

200Success. application/json · ApiKey
400VALIDATION_FAILED: the request did not match the schema; details.issues lists what. application/json · ErrorEnvelope
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope
409CONFLICT: the key was revoked application/json · ErrorEnvelope

DELETE/api-keys/{id}#

Revoke an API key

Effective on the next request; the row stays for the record.

Authorisation: Bearer token or API key · Session cookie

Parameter	In	Type	Description
`id` required	path	`string (uuid)`

204Done; no body.
401UNAUTHENTICATED: no session, or the access token expired. application/json · ErrorEnvelope
403FORBIDDEN: the account lacks library:view, or the library, label, age or schedule scope refuses it. application/json · ErrorEnvelope
404NOT_FOUND: no such thing, or not one the caller may see. application/json · ErrorEnvelope