{ "openapi": "3.1.0", "info": { "title": "Contextely API", "version": "1.0.0", "description": "Contextely is the context layer between a company's systems of record and the AI tools that read from them. Every endpoint below is the REST mirror of the MCP tool of the same operationId and runs the same code, so the two surfaces cannot diverge. An API key resolves to a MEMBER, and retrieval is scored against that member's entitlement scopes, so a machine caller can never see more than the person whose key it holds.", "contact": { "email": "hello@contextely.com", "url": "https://www.contextely.com" } }, "servers": [ { "url": "https://www.contextely.com" } ], "security": [ { "bearerAuth": [] } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "A Contextely API key, `ctx_sk_...`, created under API keys in the dashboard." }, "orgBearerAuth": { "type": "http", "scheme": "bearer", "description": "A Contextely organization key, `ctx_org_...`, created in the partner console. It provisions client workspaces, people and their keys. It never reads a client's memory: that is always done with the `ctx_sk_` key minted for one person." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } }, "paths": { "/api/v1/search": { "post": { "operationId": "context_search", "summary": "Search company context", "description": "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. Metered: one call counts against the monthly query allowance.", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "No API key, or the key has been revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "402": { "description": "The workspace has spent this month's metered allowance for this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "What you want to know, in natural language." }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 8, "description": "Maximum results." }, "skip_refresh": { "type": "boolean", "default": false, "description": "Return stored memory without checking freshness. Faster, but results may be stale." } }, "required": [ "query" ] } } } } } }, "/api/v1/memory/{id}/related": { "get": { "operationId": "context_related", "summary": "Walk to neighbouring memory", "description": "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.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "The memory object to find neighbours of." }, "description": "The memory object to find neighbours of." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 25, "default": 5, "description": "Maximum neighbours." }, "description": "Maximum neighbours." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "No API key, or the key has been revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "No such object is available to this asker. Returned both when the object does not exist and when the asker is not entitled to it, deliberately, so probing for ids cannot reveal what exists.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/memory/{id}/expand": { "post": { "operationId": "context_expand", "summary": "Fetch the full record behind a memory", "description": "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. Metered: one call counts against the monthly refresh allowance.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "The memory object to expand." }, "description": "The memory object to expand." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "No API key, or the key has been revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "402": { "description": "The workspace has spent this month's metered allowance for this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "No such object is available to this asker. Returned both when the object does not exist and when the asker is not entitled to it, deliberately, so probing for ids cannot reveal what exists.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "502": { "description": "The system of record could not be reached. The condensed memory object still stands.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/memory/{id}": { "get": { "operationId": "memory_get", "summary": "Get one memory object", "description": "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.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "description": "Memory object id." }, "description": "Memory object id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "No API key, or the key has been revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "No such object is available to this asker. Returned both when the object does not exist and when the asker is not entitled to it, deliberately, so probing for ids cannot reveal what exists.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/sources": { "get": { "operationId": "sources_list", "summary": "List connected systems of record", "description": "List the connected systems of record with their freshness policies, sync status, and whether this asker is entitled to anything from each.", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "No API key, or the key has been revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/usage": { "get": { "operationId": "workspace_usage", "summary": "Check plan and remaining quota", "description": "Plan, metered usage and remaining allowance for the month. Call it before a batch run to decide whether to proceed or back off.", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "No API key, or the key has been revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/actions": { "get": { "operationId": "actions_list", "summary": "List the actions this workspace has enabled", "description": "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.", "parameters": [], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "No API key, or the key has been revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/actions/{name}/preview": { "post": { "operationId": "action_preview", "summary": "Preview an action before invoking it", "description": "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.", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "description": "The action's name, from actions_list." }, "description": "The action's name, from actions_list." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "No API key, or the key has been revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "No such object is available to this asker. Returned both when the object does not exist and when the asker is not entitled to it, deliberately, so probing for ids cannot reveal what exists.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "args": { "type": "object", "description": "The arguments you intend to invoke with." } }, "additionalProperties": false } } } } } }, "/api/v1/actions/{name}/invoke": { "post": { "operationId": "action_invoke", "summary": "Invoke an action", "description": "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. Metered: one call counts against the monthly action allowance.", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string", "description": "The action's name, from actions_list." }, "description": "The action's name, from actions_list." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "No API key, or the key has been revoked.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "402": { "description": "The workspace has spent this month's metered allowance for this operation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "No such object is available to this asker. Returned both when the object does not exist and when the asker is not entitled to it, deliberately, so probing for ids cannot reveal what exists.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "args": { "type": "object", "description": "The arguments." }, "idempotency_key": { "type": "string", "description": "A key unique to this request. Required." } }, "required": [ "idempotency_key" ], "additionalProperties": false } } } } } }, "/api/v1/ingest": { "post": { "operationId": "post_ingest", "summary": "Run a sync for one source", "description": "Read records from a connected source and condense them into memory objects. Owner or admin only, because ingesting spends the workspace's condensation budget.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source_id": { "type": "string", "description": "The source to sync." }, "limit": { "type": "integer", "description": "Maximum records to read this run." } }, "required": [ "source_id" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing, invalid or revoked credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/actions/discover": { "post": { "operationId": "post_actions_discover", "summary": "Ask a source what it can be asked to do", "description": "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.", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source_id": { "type": "string", "description": "The source to ask." } }, "required": [ "source_id" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing, invalid or revoked credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/action-runs": { "get": { "operationId": "get_action_runs", "summary": "The action audit trail", "description": "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.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing, invalid or revoked credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/action-runs/{id}/approve": { "post": { "operationId": "post_action_runs_id_approve", "summary": "Release an action that was held for a person", "description": "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.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The action run id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing, invalid or revoked credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/action-runs/{id}/reject": { "post": { "operationId": "post_action_runs_id_reject", "summary": "Reject an action that was held for a person", "description": "Mark a held action rejected. Nothing upstream is contacted, then or ever.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The action run id." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing, invalid or revoked credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/org": { "get": { "operationId": "get_org", "summary": "The organization this key belongs to", "description": "Plan, subscription status, tenant count and the caps applied to a new tenant. The place to confirm a key is wired up correctly.", "security": [ { "orgBearerAuth": [] } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing, invalid or revoked credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/org/tenants": { "post": { "operationId": "post_org_tenants", "summary": "Create a client workspace, or return the existing one", "description": "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.", "security": [ { "orgBearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "external_ref": { "type": "string", "description": "Your own id for this client." }, "name": { "type": "string", "description": "The client's name, shown in your partner console." }, "query_cap": { "type": "integer", "description": "Retrievals this client may make per month. Defaults to the organization's setting." }, "refresh_cap": { "type": "integer", "description": "Staleness refreshes per month. Defaults to the organization's setting." } }, "required": [ "external_ref", "name" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing, invalid or revoked credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "403": { "description": "The organization is at its client limit, or its subscription is not active.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "get": { "operationId": "get_org_tenants", "summary": "List client workspaces", "description": "Every tenant this organization manages, newest first, with this period's usage.", "security": [ { "orgBearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Maximum tenants to return. Default 100." }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Rows to skip, for paging." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing, invalid or revoked credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/org/tenants/{tenant_id}": { "get": { "operationId": "get_org_tenants_tenant_id", "summary": "One client workspace", "description": "The tenant, what it holds, and what it has spent this period.", "security": [ { "orgBearerAuth": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The client workspace, as returned by POST /org/tenants." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing, invalid or revoked credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "No such tenant in this organization. Also the answer when it belongs to a different one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "post": { "operationId": "post_org_tenants_tenant_id", "summary": "Update a client workspace", "description": "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.", "security": [ { "orgBearerAuth": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The client workspace, as returned by POST /org/tenants." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "A new name." }, "query_cap": { "type": "integer", "description": "Retrievals per month. Null clears it back to the organization default." }, "refresh_cap": { "type": "integer", "description": "Staleness refreshes per month." } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing, invalid or revoked credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "No such tenant in this organization. Also the answer when it belongs to a different one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "delete_org_tenants_tenant_id", "summary": "Remove a client workspace and everything in it", "description": "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.", "security": [ { "orgBearerAuth": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The client workspace, as returned by POST /org/tenants." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing, invalid or revoked credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "No such tenant in this organization. Also the answer when it belongs to a different one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/org/tenants/{tenant_id}/members": { "post": { "operationId": "post_org_tenants_tenant_id_members", "summary": "Create a person inside a client", "description": "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.", "security": [ { "orgBearerAuth": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The client workspace, as returned by POST /org/tenants." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "description": "Identifies the person within the client. Unique per tenant." }, "name": { "type": "string", "description": "Display name." }, "role": { "type": "string", "description": "`owner`, `admin` or `member`. Owners and admins hold the wildcard grant." }, "scopes": { "type": "array", "description": "Entitlement grants, e.g. `finance:payroll`, `eng:*`." }, "external_ref": { "type": "string", "description": "Your own id for this person." } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing, invalid or revoked credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "No such tenant in this organization. Also the answer when it belongs to a different one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "get": { "operationId": "get_org_tenants_tenant_id_members", "summary": "List the people inside a client", "description": "Their roles and entitlement scopes. Never their memory.", "security": [ { "orgBearerAuth": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The client workspace, as returned by POST /org/tenants." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing, invalid or revoked credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "No such tenant in this organization. Also the answer when it belongs to a different one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/org/tenants/{tenant_id}/members/{member_id}": { "post": { "operationId": "post_org_tenants_tenant_id_members_member_id", "summary": "Change a person's role or scopes", "description": "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.", "security": [ { "orgBearerAuth": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The client workspace, as returned by POST /org/tenants." }, { "name": "member_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The person to change." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name." }, "role": { "type": "string", "description": "`owner`, `admin` or `member`." }, "scopes": { "type": "array", "description": "Entitlement grants, replacing the current set." } } } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing, invalid or revoked credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "No such tenant in this organization. Also the answer when it belongs to a different one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "delete": { "operationId": "delete_org_tenants_tenant_id_members_member_id", "summary": "Remove a person from a client", "description": "Their API keys go with them, so an agent holding one stops working immediately.", "security": [ { "orgBearerAuth": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The client workspace, as returned by POST /org/tenants." }, { "name": "member_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The person to remove." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing, invalid or revoked credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "No such tenant in this organization. Also the answer when it belongs to a different one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/org/tenants/{tenant_id}/keys": { "post": { "operationId": "post_org_tenants_tenant_id_keys", "summary": "Mint a retrieval key for one person", "description": "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.", "security": [ { "orgBearerAuth": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The client workspace, as returned by POST /org/tenants." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "member_id": { "type": "string", "description": "The person this key speaks as." }, "name": { "type": "string", "description": "A label, so you can tell your own keys apart." } }, "required": [ "member_id" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing, invalid or revoked credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "No such tenant in this organization. Also the answer when it belongs to a different one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "get": { "operationId": "get_org_tenants_tenant_id_keys", "summary": "List a client's keys", "description": "Prefixes and last use. The secret is not recoverable; mint a new one and revoke the old.", "security": [ { "orgBearerAuth": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The client workspace, as returned by POST /org/tenants." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing, invalid or revoked credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "No such tenant in this organization. Also the answer when it belongs to a different one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/org/tenants/{tenant_id}/keys/{key_id}": { "delete": { "operationId": "delete_org_tenants_tenant_id_keys_key_id", "summary": "Revoke a key", "description": "Immediate. The next request carrying it is refused.", "security": [ { "orgBearerAuth": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The client workspace, as returned by POST /org/tenants." }, { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The key to revoke." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing, invalid or revoked credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "No such tenant in this organization. Also the answer when it belongs to a different one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/org/tenants/{tenant_id}/sources": { "post": { "operationId": "post_org_tenants_tenant_id_sources", "summary": "Connect a client's system of record", "description": "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.", "security": [ { "orgBearerAuth": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The client workspace, as returned by POST /org/tenants." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "What to call it." }, "kind": { "type": "string", "description": "`mcp_http` or `postgres`." }, "config": { "type": "object", "description": "That connector's own settings." }, "default_ttl_seconds": { "type": "integer", "description": "Freshness contract for objects from this source." }, "required_scopes": { "type": "array", "description": "Scopes every object from this source inherits." } }, "required": [ "name", "kind", "config" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing, invalid or revoked credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "No such tenant in this organization. Also the answer when it belongs to a different one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } }, "get": { "operationId": "get_org_tenants_tenant_id_sources", "summary": "List a client's connected sources", "description": "Kind, status, last sync and last error.", "security": [ { "orgBearerAuth": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The client workspace, as returned by POST /org/tenants." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing, invalid or revoked credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "No such tenant in this organization. Also the answer when it belongs to a different one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/org/tenants/{tenant_id}/ingest": { "post": { "operationId": "post_org_tenants_tenant_id_ingest", "summary": "Sync one of a client's sources", "description": "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.", "security": [ { "orgBearerAuth": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The client workspace, as returned by POST /org/tenants." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "source_id": { "type": "string", "description": "The source to sync." }, "limit": { "type": "integer", "description": "Maximum records to read this run." } }, "required": [ "source_id" ] } } } }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing, invalid or revoked credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "No such tenant in this organization. Also the answer when it belongs to a different one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/org/tenants/{tenant_id}/audit": { "get": { "operationId": "get_org_tenants_tenant_id_audit", "summary": "A client's retrieval log", "description": "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.", "security": [ { "orgBearerAuth": [] } ], "parameters": [ { "name": "tenant_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "The client workspace, as returned by POST /org/tenants." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Rows to return. Default 50." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing, invalid or revoked credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } }, "404": { "description": "No such tenant in this organization. Also the answer when it belongs to a different one.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } }, "/api/v1/org/usage": { "get": { "operationId": "get_org_usage", "summary": "Pooled usage, and the per-tenant breakdown", "description": "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.", "security": [ { "orgBearerAuth": [] } ], "parameters": [ { "name": "period", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`YYYY-MM`, UTC. Defaults to this month." } ], "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "401": { "description": "Missing, invalid or revoked credential.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "bad_request", "unauthorized", "forbidden", "not_found", "quota_exceeded", "unconfigured", "upstream_failure", "internal" ] }, "message": { "type": "string" }, "details": { "type": "object", "additionalProperties": true } }, "required": [ "code", "message" ] } }, "required": [ "error" ] } } } } } } } } }