REST API

The main call. Searches the workspace's condensed working memory and returns what this asker is entitled to see, refreshing anything past its freshness TTL from its system of record first.

body: {"query":"string","limit":"integer","skip_refresh":"boolean"}

Walk from one memory object to its neighbours, ranked by shared entities, then topics, then keywords. Use it when one search result is the right thread and you want the rest of it. A neighbour outside the asker's scopes is never named or counted.

Read the full current record from the system of record a memory object was condensed from, for when the summary is not enough. No model is involved, so it returns exactly what the source says. Costs one source round-trip, metered against the monthly refresh allowance.

Fetch one memory object by id. Returns not_found rather than forbidden when the asker is not entitled to it, so probing for ids cannot reveal what exists.

List the connected systems of record with their freshness policies, sync status, and whether this asker is entitled to anything from each.

Plan, metered usage and remaining allowance for the month. Call it before a batch run to decide whether to proceed or back off.

The enabled actions the caller may invoke. Proposed and disabled actions never appear, and neither do actions whose required write scopes the caller does not hold.

Validates arguments and returns a rendered description plus the request hash, without contacting the source. It reports upstream_dry_run:false rather than simulating an effect, because a fabricated preview is indistinguishable from a real one.

body: {"name":"string","args":"object"}

Performs one enabled action. Entitlement is checked at entry and again immediately before the effect; the allowance is charged only when it reaches upstream; and every attempt, refusals included, is recorded in the action log.

body: {"name":"string","args":"object","idempotency_key":"string"}

Read records from a connected source and condense them into memory objects. Owner or admin only, because ingesting spends the workspace's condensation budget.

body: {"source_id":"string","limit":"integer"}

Enumerate the actions a connected source offers and record them as PROPOSED. Owner or admin only, and it enables nothing: each proposed action has to be enabled by hand, with the write scopes it requires. Deliberately not a tool, for the same reason /ingest is not.

body: {"source_id":"string","limit":"integer"}

Every invocation that ran and every invocation that was refused, newest first, with the refusal reason. Not gated behind the paid plan: what an agent changed in your systems is a safety artefact, not a compliance nicety.

body: {"source_id":"string","limit":"integer"}

Perform an action whose policy holds it for approval. The APPROVER's entitlement is checked, because releasing it is authorising it. Owner or admin only, and deliberately not a tool: an agent holding a key must never see its own approval bypass in its tool list.

body: {"source_id":"string","limit":"integer"}

Mark a held action rejected. Nothing upstream is contacted, then or ever.

body: {"source_id":"string","limit":"integer"}

Plan, subscription status, tenant count and the caps applied to a new tenant. The place to confirm a key is wired up correctly.

body: {"source_id":"string","limit":"integer"}

Idempotent on `external_ref`, which is your own identifier for the client. Call it on every one of your customer's logins rather than tracking which ones you have already created; `created` tells you which happened.

body: {"source_id":"string","limit":"integer"}

Every tenant this organization manages, newest first, with this period's usage.

body: {"source_id":"string","limit":"integer"}

The tenant, what it holds, and what it has spent this period.

body: {"source_id":"string","limit":"integer"}

Rename it, or change its caps. Raising a cap takes effect on the client's very next request, which is what makes a cap safe to set tightly.

body: {"source_id":"string","limit":"integer"}

Deletes the tenant's people, keys, sources and condensed memory objects. Usage already spent stays on this period's invoice, because it has already cost a source round trip and a model call.

body: {"source_id":"string","limit":"integer"}

The asker a retrieval is scored against. `scopes` is what your own permission model says this person may see, and it is enforced inside the ranking function rather than as a filter over the answer. No email is ever sent: these people do not have Contextely accounts and are never invited to make one.

body: {"source_id":"string","limit":"integer"}

Their roles and entitlement scopes. Never their memory.

body: {"source_id":"string","limit":"integer"}

Takes effect on their next retrieval. Narrowing a scope narrows every key that speaks as them, because a key is never more privileged than the person it belongs to.

body: {"source_id":"string","limit":"integer"}

Their API keys go with them, so an agent holding one stops working immediately.

body: {"source_id":"string","limit":"integer"}

The returned `key` is shown once and never stored, so keep it. Every retrieval made with it is scored against that person's scopes, which is what makes it safe to hand to an agent.

body: {"source_id":"string","limit":"integer"}

Prefixes and last use. The secret is not recoverable; mint a new one and revoke the old.

body: {"source_id":"string","limit":"integer"}

Immediate. The next request carrying it is refused.

body: {"source_id":"string","limit":"integer"}

Either an MCP server or a read-only SQL query. `required_scopes` is inherited by every memory object condensed from it, which is how a whole source is made visible to only part of a client's staff.

body: {"source_id":"string","limit":"integer"}

Kind, status, last sync and last error.

body: {"source_id":"string","limit":"integer"}

Exists so you never have to mint a wildcard-scoped owner key per client purely to trigger a sync, which would be exactly the privilege manufacture the entitlement model is built to prevent.

body: {"source_id":"string","limit":"integer"}

Every query, and how many candidates were refused on entitlement grounds. This is the artefact your own customer's security reviewer asks for, and it is the reason to resell a permission-aware layer rather than a search index.

body: {"source_id":"string","limit":"integer"}

What every client has spent this period against the pool, and what is over the included volume. Usage past the included amount bills as overage and keeps serving; only a client's own cap stops a request.

body: {"source_id":"string","limit":"integer"}