Skip to main content
PATCH/metadata/collection/{collection}/{id}

Set Metadata

Update collection by id. (Data, Queries & Vectors) PATCH /@:projectSlug/metadata/collection/{collection}/{id}.

Parameters
collection *path

The collection's name.

id *path

The id of the record whose metadata columns to write.

projectSlug *path

The project's slug: the path segment after @.

It is unique within the org.

Request body
metadata *object

The metadata columns to write, keyed by declared column name, at least one.

Each value must suit the column's type, as on PATCH /data/{collection}/{id}.

An undeclared key is refused with 400 K9O_METADATA_FIELD_NOT_INDEXED.

Responses
HTTPK9O CodeDescription
200Success
202Accepted
400K9O_INVALID_FIELD_VALUEThe body is malformed: an unknown field, a wrong type, or an unsupported where operator.
400K9O_METADATA_FIELD_NOT_INDEXEDA field is not a declared metadata field of the surface (ch04 §1.3.1); declare it with PUT /metadata/index/{collection}.
401K9O_INVALID_CREDENTIALSThe caller is not authenticated.
403K9O_ACCESS_DENIEDThe caller has no read access to the collection (the record read's own gate).
403K9O_EXTENSION_PERMISSION_DENIEDAn extension token: the Metadata API is not extension-callable yet.
403K9O_RBAC_DENYThe caller may not write this record (the record PATCH's own gate).
404K9O_NOT_FOUNDNo such record in the collection (the record PATCH's own not-found).
Response body (200)
data *object

The updated record, every column the caller may see, keyed by column name (the same row PATCH /data/{collection}/{id} returns).

Protected columns the caller may not reveal are withheld as on that route.

meta *any

Request metadata: request id, trace id, timing and cost.

Response body (202)
data *object

The change, held for approval.

Returned with status 202 when the collection needs an approver for updates; nothing is written until it is approved.

id *string

The pending change's id (apr_...).

Decide it through the pending approvals API.

status *"pending_approval"

Always pending_approval: the change waits for an approver.

collection *string

The collection the change targets.

operation *"update"

Always update on this route.

makerId *string

Who asked for the change: the accountable originator's subject id (a user, end user or token id).

proposedPayload *object

The metadata columns and values the change will write, exactly as sent in metadata.

targetRecordId *string

The id of the record the change updates.

meta *any

Request metadata, plus approval.status = pending_approval.

TypeScript
// const k9o = new K9o({ orgSlug: 'playground', projectSlug: 'storefront', apiKey: 'k9o_…' })
const { data } = await k9o.metadata.set('<collection>', '<id>', {})

Showing example in TypeScript

Request example
{}
Response example (200)
{}
Response example (202)
{
  "data": {
    "id": "string",
    "status": "pending_approval",
    "collection": "string",
    "operation": "update",
    "makerId": "string",
    "targetRecordId": "string"
  }
}

More in Data, Queries & Vectors