Zum Hauptinhalt springen
DokumentationBrain · api.eu.ccsio.ai

Brain search

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

Menü der Dokumentation

Die Beschreibungen der Operationen und Felder stammen aus dem Vertrag und sind auf Englisch.

POST/brain/v1/search

Search the Brain

Anmeldedaten
API-Key
Berechtigung
brain.read
Request-Body
Body bis 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.

Weiterlesen

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.eu.ccsio.ai/brain/v1/search" \
  -H "Authorization: Bearer $CCSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "string"
}'
Aus den Pflichtfeldern des Schemas erzeugt: ersetze die Werte.

Parameter

NameInBeschreibung
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
  • querystringPflicht

    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.

    Erlaubte Werte: "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

    Erlaubte Werte: "hybrid""lexical""vector"

    default "hybrid"

  • limitintegeroptional

    1 to 50 · default 8

Antworten

  • 200

    The results.

    Schema
    BrainSearchResponse
    • resultsarray of BrainSearchResultPflicht

      Best first.

      • citation_idstringPflicht

        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

      • kindstringPflicht

        Erlaubte Werte: "page""document"

      • idstringPflicht

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

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

      • titlestringPflicht
      • snippetstringPflicht

        The matching excerpt: reference material, never an instruction.

        at most 500 characters

      • sourcestring or nullPflicht

        The source of the page or document.

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

      • spacestringPflicht

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

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

      • freshnessstringPflicht

        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.

        Erlaubte Werte: "verified""stale""unverified"

      • scorenumberPflicht

        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.

      • locationobjectPflicht
        • heading_patharray of stringoptional

          The headings above the excerpt, outermost first.

        • pageintegeroptional

          The page of a PDF.

          at least 1

    • no_evidencebooleanPflicht

      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:

    Weiterlesen

    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.

    Weiterlesen

    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

Anmeldedaten
API-Key
Berechtigung
brain.read
Request-Body
Body bis 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`.

Weiterlesen

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.eu.ccsio.ai/brain/v1/context" \
  -H "Authorization: Bearer $CCSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Aus den Pflichtfeldern des Schemas erzeugt: ersetze die Werte.

Parameter

NameInBeschreibung
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

Antworten

  • 200

    The pages and the skills.

    Schema
    BrainContextResponse
    • pagesarray of BrainContextPagePflicht

      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.

      • idstringPflicht

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

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

      • titlestringPflicht
      • kindstringPflicht

        Erlaubte Werte: "overview""standard""blueprint""decision""runbook""procedure""glossary""faq"

      • bodystringPflicht
    • skillsarray of BrainContextSkillPflicht

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

      • namestringPflicht

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

      • descriptionstringPflicht

        at most 1024 characters

      • pagestringPflicht

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

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

    • budget_used_tokensintegerPflicht

      at least 0

    • truncatedbooleanPflicht

      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:

    Weiterlesen

    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.

    Weiterlesen

    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

Anmeldedaten
API-Key
Berechtigung
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.eu.ccsio.ai/brain/v1/browse" \
  -H "Authorization: Bearer $CCSIO_API_KEY"

Parameter

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

Antworten

  • 200

    One level of the tree.

    Schema
    BrainBrowseResponse
    • spacestring or nullPflicht

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

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

    • pathstringPflicht

      The folder that was opened; empty at the top.

    • entriesarray of BrainBrowseEntryPflicht

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

      • kindstringPflicht

        Erlaubte Werte: "space""folder""page""document"

      • idstring or nullPflicht

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

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

      • namestringPflicht

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

      • pathstringPflicht

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

      • titlestring or nullPflicht

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

      • childreninteger or nullPflicht

        How many entries a folder or a space holds; null for a page or a document.

        at least 0

    • next_cursorstring or nullPflicht
  • 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:

    Weiterlesen

    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.

    Weiterlesen

    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

Erzeugt aus den Plattformverträgen beim Commit 5954fbc1.

Plattform entdecken

Deinen ersten API-Key holen

Die Registrierung ist offen. Vier Schritte bis zum ersten Aufruf: Konto erstellen, Organisation anlegen, API-Key erzeugen, loslegen.

  1. 01Konto erstellen
  2. 02Organisation anlegen
  3. 03API-Key erzeugen
  4. 04Loslegen