kv

GET /kv/{ns}

List keys in a namespace, with sizes and modified times. No values.

07 §3. Ordered by key, ascending. The namespace `shared` is the shared namespace and needs `kv.shared` (Q21).

Needs the kv capability.

Go	`List(ctx context.Context, ns string, params KVListParams) (KVKeyPage, error)`
Python	`def list(self, ns: str, *, prefix: Optional[Any] = None, limit: Optional[Any] = None, cursor: Optional[Any] = None) -> Any`
JavaScript	`list(ns, params = {})`

Parameter	In	Type	About
ns	path · required	string
prefix	query	string
limit	query	integer
cursor	query	string	The `next_cursor` of the previous page, unchanged.

Status	Body	Means
200	KVKeyPage	A page of keys.
400	Error	The request is malformed. Codes: `bad_request`, `bad_filter`, `bad_cursor`, `invalid_document`.
401	Error	No studio token, or a revoked or unknown one. Code `unauthenticated`.
403	Error	The token lacks a capability (`capability_required`, with `details.capability`), the job is not a task the studio may change (`not_a_task`), or the request came from another origin (`bad_origin`).

GET /kv/{ns}/{key}

Read one document.

Needs the kv capability.

Go	`Get(ctx context.Context, ns string, key string) (*KVDoc, error)`
Python	`def get(self, ns: str, key: str) -> Any`
JavaScript	`get(ns, key)`

Parameter	In	Type	About
ns	path · required	string
key	path · required	string

Status	Body	Means
200	KVDoc	The document. The ETag header equals `etag`.
401	Error	No studio token, or a revoked or unknown one. Code `unauthenticated`.
403	Error	The token lacks a capability (`capability_required`, with `details.capability`), the job is not a task the studio may change (`not_a_task`), or the request came from another origin (`bad_origin`).
404	Error	Absent, deleted, or not the caller's to see. Code `not_found`.

PUT /kv/{ns}/{key}

Create or replace a document.

07 §3. The body is the document, a JSON object. With `If-Match`, the write happens only when the stored etag matches (409 `etag_mismatch` otherwise, and on a key that does not exist). Without it, the write is unconditional. Every successful write produces a new etag. The document's bytes count toward `kv_bytes` (Q20).

Needs the kv capability.

Go	`Put(ctx context.Context, ns string, key string, body map[string]any, params KVPutParams) (KVDoc, error)`
Python	`def put(self, ns: str, key: str, body: Dict[str, Any], *, if_match: Optional[Any] = None) -> Any`
JavaScript	`put(ns, key, body, params = {})`

Parameter	In	Type	About
ns	path · required	string
key	path · required	string
If-Match	header	string	The etag last read. When given and stale, the write is refused with 409 `etag_mismatch`.

Request body: JSONObject (application/json)

Status	Body	Means
200	KVDoc	The stored document.
400	Error	The request is malformed. Codes: `bad_request`, `bad_filter`, `bad_cursor`, `invalid_document`.
401	Error	No studio token, or a revoked or unknown one. Code `unauthenticated`.
403	Error	The token lacks a capability (`capability_required`, with `details.capability`), the job is not a task the studio may change (`not_a_task`), or the request came from another origin (`bad_origin`).
409	Error	Codes: `etag_mismatch`, `name_taken`, `job_finished`, `already_running`, `not_running`, `port_conflict`, `heavy_conflict` (with `details.heavy`), `not_installed`, `conflict`, `in_use`, `missing`, `confirm_required` and `preview_changed` (with `details.preview`), `not_reclaimable`, and from M7: `approval_required` (with `details.approval`), `id_taken`, `not_fetched`, `already_exists`.
413	Error	The body is over its limit. Code `too_large`, with `details.limit` in bytes.
429	Error	A per-studio quota is full. Code `quota_exceeded`, with `details` as QuotaDetails.

PATCH /kv/{ns}/{key}

Apply a JSON merge patch (RFC 7396) to an existing document.

07 §3. A `null` member removes that member. `If-Match` as for PUT.

Needs the kv capability.

Go	`Patch(ctx context.Context, ns string, key string, body map[string]any, params KVPatchParams) (KVDoc, error)`
Python	`def patch(self, ns: str, key: str, body: Dict[str, Any], *, if_match: Optional[Any] = None) -> Any`
JavaScript	`patch(ns, key, body, params = {})`

Parameter	In	Type	About
ns	path · required	string
key	path · required	string
If-Match	header	string	The etag last read. When given and stale, the write is refused with 409 `etag_mismatch`.

Request body: JSONObject (application/merge-patch+json)

Status	Body	Means
200	KVDoc	The patched document.
400	Error	The request is malformed. Codes: `bad_request`, `bad_filter`, `bad_cursor`, `invalid_document`.
401	Error	No studio token, or a revoked or unknown one. Code `unauthenticated`.
403	Error	The token lacks a capability (`capability_required`, with `details.capability`), the job is not a task the studio may change (`not_a_task`), or the request came from another origin (`bad_origin`).
404	Error	Absent, deleted, or not the caller's to see. Code `not_found`.
409	Error	Codes: `etag_mismatch`, `name_taken`, `job_finished`, `already_running`, `not_running`, `port_conflict`, `heavy_conflict` (with `details.heavy`), `not_installed`, `conflict`, `in_use`, `missing`, `confirm_required` and `preview_changed` (with `details.preview`), `not_reclaimable`, and from M7: `approval_required` (with `details.approval`), `id_taken`, `not_fetched`, `already_exists`.
413	Error	The body is over its limit. Code `too_large`, with `details.limit` in bytes.
429	Error	A per-studio quota is full. Code `quota_exceeded`, with `details` as QuotaDetails.

DELETE /kv/{ns}/{key}

Remove a document.

07 §3. With `If-Match`, only when the etag matches. Deleting a key that does not exist is 404.

Needs the kv capability.

Go	`Delete(ctx context.Context, ns string, key string, params *KVDeleteParams) error`
Python	`def delete(self, ns: str, key: str, *, if_match: Optional[Any] = None) -> Any`
JavaScript	`delete(ns, key, params = {})`

Parameter	In	Type	About
ns	path · required	string
key	path · required	string
If-Match	header	string	The etag last read. When given and stale, the write is refused with 409 `etag_mismatch`.

Status	Body	Means
204		Removed.
401	Error	No studio token, or a revoked or unknown one. Code `unauthenticated`.
403	Error	The token lacks a capability (`capability_required`, with `details.capability`), the job is not a task the studio may change (`not_a_task`), or the request came from another origin (`bad_origin`).
404	Error	Absent, deleted, or not the caller's to see. Code `not_found`.
409	Error	Codes: `etag_mismatch`, `name_taken`, `job_finished`, `already_running`, `not_running`, `port_conflict`, `heavy_conflict` (with `details.heavy`), `not_installed`, `conflict`, `in_use`, `missing`, `confirm_required` and `preview_changed` (with `details.preview`), `not_reclaimable`, and from M7: `approval_required` (with `details.approval`), `id_taken`, `not_fetched`, `already_exists`.