Core API reference
The project API: data, compute, encryption, streams, storage and the other platform primitives.
Data, Queries & Vectors
Your project's data, wherever you read it from: rows in your collections, the metadata index over them, vector and full-text search, raw queries, and the data streams and bridges that move records in and out.
The SDK entry point for rows is k9o.from('<collection>'), with select (filter, aggregate, single-row, vector and full-text variants), insert, update and delete.
Every read and write goes through the project's access policies at the gateway: a read returns only the rows the caller may see, and a write passes through the Maker-Checker policy graph, so a write awaiting approval stays invisible to standard reads until it commits.
Reserved columns (names beginning with _) cannot be written directly and return K9O_RESERVED_COLUMN_WRITE_PROHIBITED.
Inserts a new record into the named user-collection.
Retrieves records from a named user-collection using cursor-based pagination and the full query-builder vocabulary:
Executes a parameterised raw SQL statement against the project's user-data schema (
k9o_<proj_id>).Applies a partial update (delta) to the record identified by
idin the named collection.Permanently deletes the record identified by
idfrom the named collection, returning{id}on success.The record list read with its query in the body, for a vector too long for a URL.
Upsert vectors.
Search vectors.
Create nearest.
Replace index by collection.
Get index by collection.
Create query.
Update collection by id.
Create search.
List subscribe.
Deletes the rows of a
_-prefixed vector collection that match every equality infilters, and answers{ deleted, collection }with the count removed.
Realtime Feeds & Streams
Events as they happen.
A stream is a named, append-only channel your project publishes to: create one, publish events, replay what it holds and subscribe for new ones.
The Pulse feed is the project's realtime subscription to its own changes, with replay of recent history.
A subscriber receives only what its role and your policies allow, and the realtime feed re-checks row access for every row change it delivers.
Upgrades the connection to a WebSocket or SSE stream to receive live events for a named topic.
Returns one page of past events for a topic.
Creates a user stream in the project: a named, append-only message log that the project's own producers publish to and consumers read from.
Lists the project's active user streams, oldest first.
Returns one active user stream by its slug.
Deletes a user stream by its slug.
Appends one message to a user stream.
Opens a Server-Sent Events stream of a user stream's messages, starting after a sequence number and following new messages as they arrive.
Reads a page of a user stream's retained messages, oldest first, between two sequence numbers.
Storage & Schema
Where your project keeps files and how its data is shaped.
Storage is object storage in buckets (k9o.storage.*), platform-managed or backed by your own S3, GCS, Azure, MinIO, R2 or B2 bucket, with the same API either way.
Schema is introspection of your collections and columns, and migrations (k9o.migrations.*, CLI k9o migrations) are versioned DDL you propose, review and apply transactionally; a migration that embeds policy declarations may pass through approval before it takes effect.
Creates a bucket in the project.
Returns all logical buckets defined within the project.
Returns one bucket, including its
mode(private,publicorcustom).Updates a bucket's settings; only the fields sent change.
Permanently deletes a storage bucket and its configuration.
Uploads one object into the bucket as
multipart/form-data.Lists the objects in the bucket, optionally under a
prefix.Deletes the object at the
pathquery parameter (a query parameter because paths contain slashes).Mints a pre-authenticated GET URL for one object in the bucket.
Lists the project's active storage locations: the customer's own object stores (bring your own store) that buckets and datasets can be linked to.
Registers one of the customer's own object stores as a storage location for the project.
Gets one active storage location of the project by id.
Updates a storage location.
Retires a storage location: it stops being listed and can't be linked again.
Returns a paginated list of all user-defined collections in the project, sourced from the project's
k9o_<proj_id>schema.Returns full schema detail for a single named collection, including:
Applies all pending migration files to the project's schema, executing each atomically in a Postgres transaction.
Returns the migration history for the project — the ordered list of migrations that have been applied to the project's schema, corresponding to the
k9o migration statusCLI command.Returns the record for a single applied migration identified by its version number.
Proposes one or more migration files for admin approval by inserting them into the pending-migration queue with status
queued.Returns the list of pending-migration records for the project, filterable by status (
queued,applied,rejected, orcancelled) via the?status=query parameter.Approves and executes a queued pending migration, transitioning it from
queuedtoappliedand running its DDL atomically against the project's schema.Declines a queued pending migration, transitioning it from
queuedtorejectedwithout executing any DDL.Cancels a queued pending migration that the calling user authored, transitioning it from
queuedtocancelledwithout executing any DDL.
Compute & Automation
Code and automation that runs inside your project: Functions, their triggers and invocations, multi-step workflows, realtime channels, hosted model calls and the MCP servers an agent reaches.
The SDK surface is k9o.functions.* (notably k9o.functions.invoke(name, ...)), and the CLI deploys with k9o functions deploy.
A function runs on a gateway tier for light work or a sandbox tier of isolated MicroVMs for heavier work; callers never choose the tier.
Workflows compose data writes, function calls and approval gates, and are started by events or by signed inbound webhooks.
Registers a new function or redeploys an existing one within the specified project.
Returns the cursor-paginated function registry for the specified project.
Retrieves the full registry entry for a single named function in the specified project, including
status,tier,runtime,version,source,deployed_at, anderror_detail.Invokes the named function with a caller-supplied
payload.Transitions a developer-deployed function's
statustoretired, making it no longer invocable.Attaches an EVENT trigger to the named function: it fires on writes to a collection.
Returns the named function's EVENT triggers, newest first.
Partially updates an EVENT trigger.
Permanently removes the EVENT trigger
triggerIdfrom the named function, so writes to its collection no longer invoke the function.Creates a new workflow in the project with a name, trigger type (one of
view_row_event,form_submission,scheduled,manual, orwebhook), trigger configuration, and an ordered actions chai…Returns the paginated list of workflows in the specified project, ordered by authored date descending.
Retrieves the full definition of a single workflow by its
wfl_<base62>identifier, including its trigger configuration, actions chain, and current status.Partially updates a workflow's definition — including its name, description, status (
active,archived, ordraft), trigger configuration, or actions chain.Permanently deletes a workflow by its
wfl_<base62>identifier.Manually triggers a new execution run for a workflow whose
trigger_typeismanual, returning a run record withstatus: 'pending'.Returns the cursor-paginated history of execution runs for a workflow, ordered by start time descending.
Retrieves the full detail of a single workflow run by its
wfr_<base62>identifier, including per-step status, per-action cost subtotals, and any error context.Cancels a workflow run that is in
pendingorrunningstatus, halting execution at the current step.Fires a workflow whose
trigger_typeiswebhookby posting to its dedicated webhook endpoint.Returns the curated library of LLM models available to the project; every model is available on every plan.
Retrieves metadata for a single LLM model by its identifier, including name, provider class, modality, token cost (per million input and output tokens), and supported parameters.
Dispatches a synchronous inference request to the specified LLM model and returns
{ completion: string, tokensUsed: int, latencyMs: int }.Dispatches an inference request to the specified LLM model and streams the response as Server-Sent Events (SSE), delivering tokens incrementally for low-latency UX.
Analytics & Intelligence
Questions you ask of your project's activity: analytics datasets and their queries, rollups that fold a stream into windowed aggregates, and the project's own logs, metrics and traces.
A rollup's source is a stream slug: one of your streams, or logs, metrics or traces for the project's telemetry.
Results are scoped to the project and read through the same access policies as the data they summarize.
Creates a dataset at the slug in the path.
Returns the project's active datasets, newest first: slug, display name, schema, partition keys (
regionis always the first), residency class, storage target and creation time.Returns one active dataset's metadata.
Retires the dataset: it reads as absent from then on and its slug is never reissued.
Appends rows: the body is newline-delimited JSON or a JSON array.
Uploads a CSV or JSON file (raw body, or multipart with
fileand an optionalmanifest), up to 25 MiB.Returns the original file of the dataset's stored upload as a download (
text/csv,application/jsonorapplication/octet-stream), not a JSON envelope.Copies rows into the dataset from exactly one source:
fromCollection(a collection name) orfromQuery(a saved Studio query id that reads a single collection).Pages through a dataset's rows.
Runs a read-only SQL
SELECTover the project's datasets and returns the rows.Creates a continuous rollup that folds a stream into this dataset over fixed windows.
Returns every rollup in the project whose dataset the caller can read, with its read and subscribe endpoints.
Returns the dataset's rollups with their attestation state:
attestedAt,expiresAtandattestationStatus(active,expiring_soonorexpired; an expired rollup is paused, not deleted).Returns the rollup's cells for a time range.
Opens a server-sent events stream with one
cellevent per closed cell.Confirms the rollup's configuration is still wanted: resets its attestation to now and, optionally, sets a new
reattestIntervalDays(7, 30, 90 or 365).Deletes the rollup.
Creates a recurring materialization from a collection into this dataset.
Returns the dataset's schedules with
lastRunAt,lastRunStatus,nextRunAtand their attestation state (attestedAt,expiresAt,attestationStatus).Confirms the schedule is still wanted: resets its attestation to now and, optionally, sets a new
reattestIntervalDays(7, 30, 90 or 365).Deletes the schedule.
AI Safety
Checks on content an AI agent reads or writes, and rules on what agents may do.
Rampart classifies submitted content as clear, suspicious or malicious with a risk score and a signed classification receipt, as a signal for your own decision; its JWKS verifies those receipts.
The classification policy and tool rules set which agent tool calls a project allows.
Classifies the submitted content and returns its classification, a risk score and a confidence (both in basis points, 0 to 10000), any categories, and the classifier's calibration version.
Returns the JSON Web Key Set (RFC 7517) that verifies Rampart
classificationReceiptsignatures.
Policy & Approvals
Who may do what, and what needs a second person.
Two families sit here.
Pending approvals (/pending-approvals) are the queue of held data and schema changes waiting on a reviewer; an approved change is applied for you, and a rejected one is discarded.
The change's author and its reviewers can discuss it in comments.
Approval policies (/approval-policies) are the rules that decide which changes are held.
Access policies, IAM policies and their bindings to principals live here too.
Returns the caller's approver inbox: a cursor-paginated list of pending-change envelopes (
pch_<base62>) where the caller is a member of the denormalizedapprover_setor holds an active approval…Returns the full pending-change detail for a single pending-change envelope identified by
pendingId(pch_<base62>), including the proposed diff, maker identity, denormalized approver set, statu…Records a checker approval decision on a pending change.
Records a checker rejection decision on a pending change, capturing an optional reason in
status_reason.Adds a comment to a pending change.
Lists the comments on a pending change, oldest first, filtered by what the caller may see at the time of the request.
Approves or rejects a batch of pending changes in a single atomic attestation using a batch criterion predicate (by maker session, by criteria predicate, by time window, or by table scope).
Creates a new draft policy bundle for the project, assigned a stable
bundleId(bnd_<base62>).Lists the project's approval policies (
apo_...), oldest first.Permanently deletes a draft policy bundle identified by
policyId.Creates a new draft policy bundle for the project.
Returns all policy bundles for the project, cursor-paginated and filterable by status (
draft,published,superseded).Returns a single policy bundle by its
bundleId.Returns the currently published policy bundle for the project — the live bundle evaluated at runtime against all data operations.
Updates the policy document of a draft bundle.
Validates a candidate policy bundle body against all schema and operator rules without persisting any state.
Atomically publishes a draft bundle, activating it as the project's live policy.
Deletes a draft policy bundle.
Encryption
Encrypt and decrypt data under your project's keys, rewrap ciphertext, and check who holds the keys.
The SDK surface is k9o.kibo.*.
A custody move runs as a job you can follow to completion.
Encrypts up to 100 items with the project's key; the key never leaves the platform and you never choose one.
Decrypts up to 100 ciphertexts made by this API, with the same
cryptandcontextused to encrypt them.Re-seals up to 100 ciphertexts under the project's current key in one call; the plaintext never leaves the platform.
Returns the project's key custody mode (
PLATFORM_MANAGED,SKR,BYOKorHYOK), itsroute, and an opaqueepochthat changes with every custody transition.Issues a short-lived signed identity for the client-side crypto path on a project that uses your own key (BYOK or HYOK): present it to your cloud's token exchange (AWS AssumeRoleWithWebIdentity, GC…
Revokes every federation signing key of the project: tokens already issued stop verifying once your cloud's cached copy of the key set expires, and the next token is signed with a new key under the…
Read-only summary of the project's key custody:
{ mode, attached, provider, lastJob, hsm, kmsFederation }.
Members & End Users
The people in your project.
Members and invitations are the operators who work on it; end users are your application's own customers (eu_<base62>), with their groups (eug_<base62>) and role grants (eur_<base62>), managed through k9o.gate.admin.*.
The two are separate trust zones: an operator's access never comes from an end-user record, and an end user never holds an operator role.
Signing end users in is under the Gate tags.
Invites a new user or grants an existing org member a role on the project.
Returns a list of members for the specified project.
Changes the project role of an existing project member.
Removes a user from the project.
Grants a project-level role to an end-user, creating a
eur_-prefixed role grant record.Returns all active role grants for project end-users, cursor-paginated.
Revokes a specific end-user role grant by its
eur_-prefixed grant ID, settingrevoked_aton the grant record.
Audit & Security
The record of what happened in your project and the controls around it: the audit log and its anchors, security settings such as SIEM delivery, notifications and alert rules, erasure triggers, legal attestations and project settings.
Audit entries are identity-attributed and append-only, and anchors let you check that the log you read is the log that was written.
Notification and alert events are the same events the audit trail records.
Returns a paginated list of audit events for the specified project, covering auth, data-access, security, and lifecycle activity.
Returns the cursor-paginated list of external transparency anchors for the project, ordered by
capturedAtdescending.Retrieves a single transparency anchor by its identifier (
anc_<base62>).
Extensions
Installing, configuring, enabling, disabling, and operating extensions within a project.
Extensions (ext_<base62>) add capabilities on top of the platform core — connectors, AI agents, identity surfaces, and automations — running in a sandboxed WASM/Bun runtime with per-extension isolation, gateway-mediated egress, and a declared manifest of capabilities and dependencies.
These endpoints manage the extension lifecycle (install, supply per-project configuration and secrets, enable, disable, uninstall) and the per-project state each extension maintains in its own _ext_<name> namespace.
Extensions are how a project is extended without forking the platform: they read feature flags rather than tier names, deploy functions into the shared _sys.functions registry under an extension:<slug> provenance, and are governed by the same policy and audit machinery as first-party code.
A manifest that violates the schema is hard-rejected with K9O_EXTENSION_MANIFEST_INVALID.
Integrators building, publishing, or installing marketplace capabilities manage their lifecycle and configuration here.
Returns the list of extensions currently enabled (or previously installed) on the specified project, including each extension's status, manifest version, enabled-at timestamp, and permission grants.
Returns the per-project enable record for the specified extension on this project — including the enable status, current manifest version, permission grants, schema name, and the
hookSecret(HMAC…Enables a registered extension on the specified project.
Disables an enabled extension on the specified project.
Updates per-extension configuration for the specified project and fires the
configurelifecycle hook (best-effort, single attempt).Lists the rows of one of an installed extension's own tables, a page at a time.
Creates one row in an installed extension's own table from
values, and answers 201 with the row as stored.Reads one row of an installed extension's own table by its id.
Changes the columns named in
seton one row, and answers with the row as stored.Deletes one row of an installed extension's own table.
MCP
The project's inbound MCP (Model Context Protocol) endpoint, for AI agents and MCP clients.
A client reads the discovery document without a token, presents a token minted for a named set of tools, and calls those tools over JSON-RPC.
Each call runs under the minting operator's live role, so a token never grants more than that operator holds.
The project's OAuth 2.0 Protected Resource Metadata (RFC 9728) for its MCP endpoint.
The project's inbound MCP endpoint: Streamable HTTP, one JSON-RPC 2.0 request per POST.
Mints the bearer token an MCP client presents to the project's MCP endpoint.
Revokes an MCP token by its
jti.
Operator Sign-in
The entry points by which an operator establishes identity with the platform:
- sign-up
- sign-in (password and federated)
- token refresh
- sign-out
- the OAuth2 / OIDC / SAML callback and assertion-consumer flows that complete a federated handshake
Most are reachable before any session token exists — they mint the first credential — so they require no caller credential and are emitted with security: [].
A successful flow yields an operator session (a JWT plus refresh token) that every other operator-plane call presents.
This tag covers operators only — the people and machines that administer organizations, projects, and configuration.
Authentication for your own application's end-users is a separate trust zone entirely and is under the Gate tags; the two must not be conflated.
Integrators automating against the platform typically pass through here once to obtain a token, then prefer a Personal Access Token for long-lived programmatic access.
RFC 6749 token endpoint for the operator authorization code with PKCE.
RFC 7009 revocation for a token from Redeem Authorization Code.