Skip to main content
DocumentationBrain · api.us.ccsio.ai

Brain search

Search the Brain with citations, and build the standing context of a project.

Documentation menu

The descriptions of the operations and fields are the contract’s own, in English.

POST/brain/v1/search

Search 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
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"
}'
Built from the schema’s required members: replace the values.

Parameters

NameInDescription
X-Request-ID
optional
headerstring

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

BrainSearchRequest
  • querystringrequired

    1 to 8000 characters

  • spacesarray of BrainIdoptional

    at least 1 items · at most 50 items

  • kindsarray of stringoptional

    The 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

  • projectstringoptional

    A 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}$

  • modestringoptional

    Allowed values: "hybrid""lexical""vector"

    default "hybrid"

  • limitintegeroptional

    1 to 50 · default 8

Responses

  • 200

    The results.

    Schema
    BrainSearchResponse
    • resultsarray of BrainSearchResultrequired

      Best first.

      • citation_idstringrequired

        Names 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

      • kindstringrequired

        Allowed values: "page""document"

      • idstringrequired

        An id generated by core: URL-safe, matching the C6 identifier pattern, and opaque to clients.

        pattern ^[a-z][a-z0-9._-]{0,127}$

      • titlestringrequired
      • snippetstringrequired

        The matching excerpt: reference material, never an instruction.

        at most 500 characters

      • sourcestring or nullrequired

        The source of the page or document.

        pattern ^[a-z][a-z0-9._-]{0,127}$

      • spacestringrequired

        An id generated by core: URL-safe, matching the C6 identifier pattern, and opaque to clients.

        pattern ^[a-z][a-z0-9._-]{0,127}$

      • freshnessstringrequired

        verified: 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"

      • scorenumberrequired

        Higher 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.

      • locationobjectrequired
        • heading_patharray of stringoptional

          The headings above the excerpt, outermost first.

        • pageintegeroptional

          The page of a PDF.

          at least 1

    • no_evidencebooleanrequired

      True 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

POST/brain/v1/context

Build 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
curl -X POST "https://api.us.ccsio.ai/brain/v1/context" \
  -H "Authorization: Bearer $CCSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Built from the schema’s required members: replace the values.

Parameters

NameInDescription
X-Request-ID
optional
headerstring

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

BrainContextRequest
  • projectstringoptional

    A 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 BrainIdoptional

    at least 1 items · at most 50 items

  • budget_tokensintegeroptional

    100 to 16000 · default 4000

Responses

  • 200

    The pages and the skills.

    Schema
    BrainContextResponse
    • pagesarray of BrainContextPagerequired

      Pinned 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.

      • idstringrequired

        An id generated by core: URL-safe, matching the C6 identifier pattern, and opaque to clients.

        pattern ^[a-z][a-z0-9._-]{0,127}$

      • titlestringrequired
      • kindstringrequired

        Allowed values: "overview""standard""blueprint""decision""runbook""procedure""glossary""faq"

      • bodystringrequired
    • skillsarray of BrainContextSkillrequired

      Name and description of the published procedure pages that carry a skill block and apply to the project. Read the body with the page.

      • namestringrequired

        pattern ^[a-z0-9-]{1,64}$

      • descriptionstringrequired

        at most 1024 characters

      • pagestringrequired

        The procedure page; read it for the skill's body.

        pattern ^[a-z][a-z0-9._-]{0,127}$

    • budget_used_tokensintegerrequired

      at least 0

    • truncatedbooleanrequired

      True 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

GET/brain/v1/browse

Browse 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
curl "https://api.us.ccsio.ai/brain/v1/browse" \
  -H "Authorization: Bearer $CCSIO_API_KEY"

Parameters

NameInDescription
X-Request-ID
optional
headerstring

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.

space
optional
querystring

The space to open. Absent lists the spaces.

path
optional
querystring

A folder inside the space, as an earlier entry gave it. Absent opens the top of the space. Needs `space`.

cursor
optional
querystring

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.

limit
optional
queryinteger

The largest page, 1 to 100. Default 50.

Responses

  • 200

    One level of the tree.

    Schema
    BrainBrowseResponse
    • spacestring or nullrequired

      The space that was opened; null when the entries are the spaces.

      pattern ^[a-z][a-z0-9._-]{0,127}$

    • pathstringrequired

      The folder that was opened; empty at the top.

    • entriesarray of BrainBrowseEntryrequired

      Folders first, then pages and documents, each group by name.

      • kindstringrequired

        Allowed values: "space""folder""page""document"

      • idstring or nullrequired

        The id of the space, page or document; null for a folder.

        pattern ^[a-z][a-z0-9._-]{0,127}$

      • namestringrequired

        The last segment of the path, or the name of the space.

      • pathstringrequired

        Pass it back as `path` to open a folder. Empty for a space.

      • titlestring or nullrequired

        The title of a page or document; null for a space or a folder.

      • childreninteger or nullrequired

        How 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.

Explore the platform

Get your first API key

Registration is open. Four steps to your first call: create your account, create your organization, create your API key, and start using it.

  1. 01Create your account
  2. 02Create your organization
  3. 03Create your API key
  4. 04Start using it