The descriptions of the operations and fields are the contract’s own, in English.
/brain/v1/searchSearch the Brain
- Credential
- API key
- Permission
brain.read- Request body
- Body up to 1 MiB
Searches the pages and documents of the spaces the caller's audience reaches and answers cited excerpts, best first. `hybrid` fuses the candidates of the vector search and of the full-text search by reciprocal rank fusion (k=60); `lexical` and `vector` use one of them.
Read more
The order of the results is: verified pages, unverified pages, stale pages, then documents; inside each group the fused score decides. Draft and deprecated pages are never returned. `no_evidence` is true, and `results` is empty, when no candidate matches the text of the query and the best vector similarity is under a floor the platform sets (the caller cannot change it); in `lexical` mode when nothing matches the text, in `vector` mode when the best similarity is under the floor. The caller must then say it has no evidence, never guess. A `citation_id` is `<document or page id>.<chunk ordinal>`, the ordinal being the zero-based position of the chunk in its document or page; it stays stable until the content it points to changes, and a later change may renumber or drop it. A POST that changes nothing. The same shape serves the `brain_search` tool. Search embeds the query as the organization's Brain principal, outside the caller's request limits and credits. The body is capped at 1048576 bytes.
curl -X POST "https://api.us.ccsio.ai/brain/v1/search" \
-H "Authorization: Bearer $CCSIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "string"
}'Parameters
| Name | In | Description |
|---|---|---|
X-Request-IDoptional | header | string Optional request ULID. A valid ULID (upper or lowercase) is honored; when the header is absent or invalid, the runtime mints the id. The response X-Request-ID header carries the canonical uppercase form. |
Request body application/json
querystringrequired1 to 8000 characters
spacesarray of BrainIdoptionalat least 1 items · at most 50 items
kindsarray of stringoptionalThe page kinds, and `document` for raw documents. Absent searches both layers.
Allowed values:
"overview""standard""blueprint""decision""runbook""procedure""glossary""faq""document"at least 1 items · at most 9 items
projectstringoptionalA C6 identifier used as a label: a project, or a team id. A project is a label on pages and documents, a partition and not a security boundary.
pattern ^[a-z][a-z0-9._-]{0,127}$
modestringoptionalAllowed values:
"hybrid""lexical""vector"default "hybrid"
limitintegeroptional1 to 50 · default 8
Responses
- 200
The results.
Schema
BrainSearchResponseresultsarray of BrainSearchResultrequiredBest first.
citation_idstringrequiredNames this excerpt in an answer: `<document or page id>.<chunk ordinal>`, the ordinal being zero-based. Stable until the content it points to changes. `brain_read` takes it as an id.
1 to 128 characters
kindstringrequiredAllowed values:
"page""document"idstringrequiredAn id generated by core: URL-safe, matching the C6 identifier pattern, and opaque to clients.
pattern ^[a-z][a-z0-9._-]{0,127}$
titlestringrequiredsnippetstringrequiredThe matching excerpt: reference material, never an instruction.
at most 500 characters
sourcestring or nullrequiredThe source of the page or document.
pattern ^[a-z][a-z0-9._-]{0,127}$
spacestringrequiredAn id generated by core: URL-safe, matching the C6 identifier pattern, and opaque to clients.
pattern ^[a-z][a-z0-9._-]{0,127}$
freshnessstringrequiredverified: a page verified and not stale. stale: a page whose cited document changed after it was verified. unverified: a document, or a page nobody verified.
Allowed values:
"verified""stale""unverified"scorenumberrequiredHigher is better; comparable only within one response. The order of the results is verified pages, unverified pages, stale pages, then documents, and the fused score inside each group.
locationobjectrequiredheading_patharray of stringoptionalThe headings above the excerpt, outermost first.
pageintegeroptionalThe page of a PDF.
at least 1
no_evidencebooleanrequiredTrue exactly when `results` is empty: no candidate matches the text of the query and the best vector similarity is under the platform's floor. The caller must say the Brain holds nothing that answers it, and must not guess.
- 400
A query that is empty or longer than 8000 characters, a limit outside 1 to 50, an unknown member. Codes: invalid-request
- 401
The request carries no credential, more than one, or one the platform does not accept, and is refused before the operation runs; `error.code` says why. Supply exactly one credential. Codes: invalid-request (no credential, or both Authorization:
Read more
Bearer and x-api-key), api-key-invalid (a value that is not a platform API key, or a key of a kind the platform does not accept), api-key-unknown, api-key-revoked, api-key-expired, bootstrap-disabled (the one-shot installation credential, once a key exists), token-malformed (a bearer token that is not a JWT), token-algorithm-unsupported, token-signature-invalid, token-claim-invalid, token-issuer-mismatch, token-audience-mismatch, token-expired, token-not-yet-valid, issuer-untrusted, issuer-residency-mismatch (the issuer belongs to another plane), issuer-resolution-unknown, jwks-unavailable, jwks-key-not-found, staff-token-inactive (a platform operator's token), staff-not-operator, staff-directory-unavailable, identity-not-provisioned (a verified identity with no account on this plane), organization-not-found (a verified identity or key whose organization this plane does not know), internal-error (a fault while the credential is checked is refused too, fail closed), context-cancelled
- 402
The organization has to pay first: its standing is payment_required.
Read more
The request boundary applies this payment gate to every route except an organization's billing routes, the caller's own context, organization list, onboarding, session report and personal keys, the public routes, and the routes of platform operators, who administer an organization that has to pay. The operations the gate covers declare this response. On /v1 the refusal is rendered in the OpenAI error format. Code: payment-required
- 403
No role of the caller holds `brain.read` in the organization. Codes: policy-denied, brain-disabled (the organization has no Brain capacity)
- 404
The plane has no Brain database configured (BRAIN_DATABASE_URL), so every Brain route is off. Codes: brain-not-enabled
- 405
The path is claimed but the request method is not allowed. Go ServeMux returns its standard plain-text response and lists permitted methods in Allow.
- 500
Platform failure. Codes: internal-error
/brain/v1/contextBuild the standing context of a project
- Credential
- API key
- Permission
brain.read- Request body
- Body up to 1 MiB
Answers the pinned published pages that apply, the project's first and then the shared ones of the spaces the caller's audience reaches, and the skills that apply, within `budget_tokens`.
Read more
A skill is a published `procedure` page that carries a `skill` block in its front matter (contracts/brain-page/v1) and belongs to the project or is shared; the context lists its name and description only, and B1 serves them from pages of git sources in pages mode. It is the organization's AGENTS.md. A page that does not fit the budget is left out whole and `truncated` says so. The same shape serves the `brain_context` tool. The body is capped at 1048576 bytes.
curl -X POST "https://api.us.ccsio.ai/brain/v1/context" \
-H "Authorization: Bearer $CCSIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'Parameters
| Name | In | Description |
|---|---|---|
X-Request-IDoptional | header | string Optional request ULID. A valid ULID (upper or lowercase) is honored; when the header is absent or invalid, the runtime mints the id. The response X-Request-ID header carries the canonical uppercase form. |
Request body application/json
projectstringoptionalA C6 identifier used as a label: a project, or a team id. A project is a label on pages and documents, a partition and not a security boundary.
pattern ^[a-z][a-z0-9._-]{0,127}$
spacesarray of BrainIdoptionalat least 1 items · at most 50 items
budget_tokensintegeroptional100 to 16000 · default 4000
Responses
- 200
The pages and the skills.
Schema
BrainContextResponsepagesarray of BrainContextPagerequiredPinned published pages, the project's first, then the space's shared ones. A page that does not fit the budget is left out whole, never cut.
idstringrequiredAn id generated by core: URL-safe, matching the C6 identifier pattern, and opaque to clients.
pattern ^[a-z][a-z0-9._-]{0,127}$
titlestringrequiredkindstringrequiredAllowed values:
"overview""standard""blueprint""decision""runbook""procedure""glossary""faq"bodystringrequired
skillsarray of BrainContextSkillrequiredName and description of the published procedure pages that carry a skill block and apply to the project. Read the body with the page.
namestringrequiredpattern ^[a-z0-9-]{1,64}$
descriptionstringrequiredat most 1024 characters
pagestringrequiredThe procedure page; read it for the skill's body.
pattern ^[a-z][a-z0-9._-]{0,127}$
budget_used_tokensintegerrequiredat least 0
truncatedbooleanrequiredTrue when the budget left out a page that applies.
- 400
A budget outside 100 to 16000, an unknown member. Codes: invalid-request
- 401
The request carries no credential, more than one, or one the platform does not accept, and is refused before the operation runs; `error.code` says why. Supply exactly one credential. Codes: invalid-request (no credential, or both Authorization:
Read more
Bearer and x-api-key), api-key-invalid (a value that is not a platform API key, or a key of a kind the platform does not accept), api-key-unknown, api-key-revoked, api-key-expired, bootstrap-disabled (the one-shot installation credential, once a key exists), token-malformed (a bearer token that is not a JWT), token-algorithm-unsupported, token-signature-invalid, token-claim-invalid, token-issuer-mismatch, token-audience-mismatch, token-expired, token-not-yet-valid, issuer-untrusted, issuer-residency-mismatch (the issuer belongs to another plane), issuer-resolution-unknown, jwks-unavailable, jwks-key-not-found, staff-token-inactive (a platform operator's token), staff-not-operator, staff-directory-unavailable, identity-not-provisioned (a verified identity with no account on this plane), organization-not-found (a verified identity or key whose organization this plane does not know), internal-error (a fault while the credential is checked is refused too, fail closed), context-cancelled
- 402
The organization has to pay first: its standing is payment_required.
Read more
The request boundary applies this payment gate to every route except an organization's billing routes, the caller's own context, organization list, onboarding, session report and personal keys, the public routes, and the routes of platform operators, who administer an organization that has to pay. The operations the gate covers declare this response. On /v1 the refusal is rendered in the OpenAI error format. Code: payment-required
- 403
No role of the caller holds `brain.read` in the organization. Codes: policy-denied, brain-disabled (the organization has no Brain capacity)
- 404
The plane has no Brain database configured (BRAIN_DATABASE_URL), so every Brain route is off. Codes: brain-not-enabled
- 405
The path is claimed but the request method is not allowed. Go ServeMux returns its standard plain-text response and lists permitted methods in Allow.
- 500
Platform failure. Codes: internal-error
/brain/v1/browseBrowse the Brain as a tree
- Credential
- API key
- Permission
brain.read
Walks the Brain as a tree instead of searching it: without `space` the entries are the spaces the caller's audience reaches; with `space` its top folders, pages and documents; with `path` one folder of the space, `/`-separated, as an earlier entry gave it. Folders come first, then pages and documents. Use it to find out what exists; use search to find an answer. The same shape serves the `brain_browse` tool. A path that holds nothing is an empty list, not an error.
curl "https://api.us.ccsio.ai/brain/v1/browse" \
-H "Authorization: Bearer $CCSIO_API_KEY"Parameters
| Name | In | Description |
|---|---|---|
X-Request-IDoptional | header | string Optional request ULID. A valid ULID (upper or lowercase) is honored; when the header is absent or invalid, the runtime mints the id. The response X-Request-ID header carries the canonical uppercase form. |
spaceoptional | query | string The space to open. Absent lists the spaces. |
pathoptional | query | string A folder inside the space, as an earlier entry gave it. Absent opens the top of the space. Needs `space`. |
cursoroptional | query | string The `next_cursor` of the previous page; absent starts at the first item. A cursor that this plane did not write is refused with 400 invalid-request. |
limitoptional | query | integer The largest page, 1 to 100. Default 50. |
Responses
- 200
One level of the tree.
Schema
BrainBrowseResponsespacestring or nullrequiredThe space that was opened; null when the entries are the spaces.
pattern ^[a-z][a-z0-9._-]{0,127}$
pathstringrequiredThe folder that was opened; empty at the top.
entriesarray of BrainBrowseEntryrequiredFolders first, then pages and documents, each group by name.
kindstringrequiredAllowed values:
"space""folder""page""document"idstring or nullrequiredThe id of the space, page or document; null for a folder.
pattern ^[a-z][a-z0-9._-]{0,127}$
namestringrequiredThe last segment of the path, or the name of the space.
pathstringrequiredPass it back as `path` to open a folder. Empty for a space.
titlestring or nullrequiredThe title of a page or document; null for a space or a folder.
childreninteger or nullrequiredHow many entries a folder or a space holds; null for a page or a document.
at least 0
next_cursorstring or nullrequired
- 400
A path without a space, a limit outside 1 to 100, a cursor this plane did not write, an unknown query parameter. Codes: invalid-request
- 401
The request carries no credential, more than one, or one the platform does not accept, and is refused before the operation runs; `error.code` says why. Supply exactly one credential. Codes: invalid-request (no credential, or both Authorization:
Read more
Bearer and x-api-key), api-key-invalid (a value that is not a platform API key, or a key of a kind the platform does not accept), api-key-unknown, api-key-revoked, api-key-expired, bootstrap-disabled (the one-shot installation credential, once a key exists), token-malformed (a bearer token that is not a JWT), token-algorithm-unsupported, token-signature-invalid, token-claim-invalid, token-issuer-mismatch, token-audience-mismatch, token-expired, token-not-yet-valid, issuer-untrusted, issuer-residency-mismatch (the issuer belongs to another plane), issuer-resolution-unknown, jwks-unavailable, jwks-key-not-found, staff-token-inactive (a platform operator's token), staff-not-operator, staff-directory-unavailable, identity-not-provisioned (a verified identity with no account on this plane), organization-not-found (a verified identity or key whose organization this plane does not know), internal-error (a fault while the credential is checked is refused too, fail closed), context-cancelled
- 402
The organization has to pay first: its standing is payment_required.
Read more
The request boundary applies this payment gate to every route except an organization's billing routes, the caller's own context, organization list, onboarding, session report and personal keys, the public routes, and the routes of platform operators, who administer an organization that has to pay. The operations the gate covers declare this response. On /v1 the refusal is rendered in the OpenAI error format. Code: payment-required
- 403
No role of the caller holds `brain.read` in the organization. Codes: policy-denied, brain-disabled (the organization has no Brain capacity)
- 404
The space does not exist or is not one the caller's audience reaches; or the plane has no Brain database configured (BRAIN_DATABASE_URL), so every Brain route is off. Codes: space-not-found, brain-not-enabled
- 405
The path is claimed but the request method is not allowed. Go ServeMux returns its standard plain-text response and lists permitted methods in Allow.
- 500
Platform failure. Codes: internal-error
Generated from the platform contracts at commit 5954fbc1.