Saltar al contenido principal
DocumentaciónBrain · api.latam.ccsio.ai

Brain search

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

Menú de la documentación

Las descripciones de las operaciones y los campos son las del contrato, en inglés.

POST/brain/v1/search

Search the Brain

Credencial
API key
Permiso
brain.read
Cuerpo de la solicitud
Cuerpo de hasta 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.

Leer más

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.latam.ccsio.ai/brain/v1/search" \
  -H "Authorization: Bearer $CCSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "string"
}'
Construido con los campos obligatorios del esquema: reemplaza los valores.

Parámetros

NombreEnDescripción
X-Request-ID
opcional
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.

Cuerpo de la solicitud application/json

BrainSearchRequest
  • querystringobligatorio

    1 to 8000 characters

  • spacesarray of BrainIdopcional

    at least 1 items · at most 50 items

  • kindsarray of stringopcional

    The page kinds, and `document` for raw documents. Absent searches both layers.

    Valores permitidos: "overview""standard""blueprint""decision""runbook""procedure""glossary""faq""document"

    at least 1 items · at most 9 items

  • projectstringopcional

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

  • modestringopcional

    Valores permitidos: "hybrid""lexical""vector"

    default "hybrid"

  • limitintegeropcional

    1 to 50 · default 8

Respuestas

  • 200

    The results.

    Esquema
    BrainSearchResponse
    • resultsarray of BrainSearchResultobligatorio

      Best first.

      • citation_idstringobligatorio

        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

      • kindstringobligatorio

        Valores permitidos: "page""document"

      • idstringobligatorio

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

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

      • titlestringobligatorio
      • snippetstringobligatorio

        The matching excerpt: reference material, never an instruction.

        at most 500 characters

      • sourcestring or nullobligatorio

        The source of the page or document.

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

      • spacestringobligatorio

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

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

      • freshnessstringobligatorio

        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.

        Valores permitidos: "verified""stale""unverified"

      • scorenumberobligatorio

        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.

      • locationobjectobligatorio
        • heading_patharray of stringopcional

          The headings above the excerpt, outermost first.

        • pageintegeropcional

          The page of a PDF.

          at least 1

    • no_evidencebooleanobligatorio

      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:

    Leer más

    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.

    Leer más

    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

Credencial
API key
Permiso
brain.read
Cuerpo de la solicitud
Cuerpo de hasta 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`.

Leer más

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.latam.ccsio.ai/brain/v1/context" \
  -H "Authorization: Bearer $CCSIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
Construido con los campos obligatorios del esquema: reemplaza los valores.

Parámetros

NombreEnDescripción
X-Request-ID
opcional
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.

Cuerpo de la solicitud application/json

BrainContextRequest
  • projectstringopcional

    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 BrainIdopcional

    at least 1 items · at most 50 items

  • budget_tokensintegeropcional

    100 to 16000 · default 4000

Respuestas

  • 200

    The pages and the skills.

    Esquema
    BrainContextResponse
    • pagesarray of BrainContextPageobligatorio

      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.

      • idstringobligatorio

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

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

      • titlestringobligatorio
      • kindstringobligatorio

        Valores permitidos: "overview""standard""blueprint""decision""runbook""procedure""glossary""faq"

      • bodystringobligatorio
    • skillsarray of BrainContextSkillobligatorio

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

      • namestringobligatorio

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

      • descriptionstringobligatorio

        at most 1024 characters

      • pagestringobligatorio

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

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

    • budget_used_tokensintegerobligatorio

      at least 0

    • truncatedbooleanobligatorio

      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:

    Leer más

    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.

    Leer más

    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

Credencial
API key
Permiso
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.latam.ccsio.ai/brain/v1/browse" \
  -H "Authorization: Bearer $CCSIO_API_KEY"

Parámetros

NombreEnDescripción
X-Request-ID
opcional
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
opcional
querystring

The space to open. Absent lists the spaces.

path
opcional
querystring

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

cursor
opcional
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
opcional
queryinteger

The largest page, 1 to 100. Default 50.

Respuestas

  • 200

    One level of the tree.

    Esquema
    BrainBrowseResponse
    • spacestring or nullobligatorio

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

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

    • pathstringobligatorio

      The folder that was opened; empty at the top.

    • entriesarray of BrainBrowseEntryobligatorio

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

      • kindstringobligatorio

        Valores permitidos: "space""folder""page""document"

      • idstring or nullobligatorio

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

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

      • namestringobligatorio

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

      • pathstringobligatorio

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

      • titlestring or nullobligatorio

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

      • childreninteger or nullobligatorio

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

        at least 0

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

    Leer más

    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.

    Leer más

    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

Generado a partir de los contratos de la plataforma en el commit 5954fbc1.

Explora la plataforma

Obtén tu primera key API

El registro está abierto. Cuatro pasos hasta tu primera llamada: crea tu cuenta, crea tu organización, crea tu API key y empieza a usarla.

  1. 01Crea tu cuenta
  2. 02Crea tu organización
  3. 03Crea tu API key
  4. 04Empieza a usarla