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

Brain sources

Add, list, sync and delete the sources documents come from.

Documentation menu

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

GET/brain/v1/sources

List the sources

Credential
API key
Permission
brain.read

Lists the sources of the spaces the caller's audience reaches, newest first, with their state and counts. A filter narrows the list and never widens it.

curl
curl "https://api.us.ccsio.ai/brain/v1/sources" \
  -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

Only this space.

kind
optional
querystring

Only sources of this kind.

state
optional
querystring

Only sources in this state.

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 page of sources.

    Schema
    BrainSourceList
    • sourcesarray of BrainSourcerequired

      Newest first.

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

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

      • kindstringrequired

        Allowed values: "upload""url""git"

      • namestringrequired

        For a file, its cleaned name; for a link, the page's title or its host and path; for a repository, `owner/name`, unless the creator chose a name.

        1 to 255 characters

      • statestringrequired

        pending: stored, not yet picked up. syncing: being fetched, extracted and indexed. ready: searchable. failed: see `error`; a git source tries again at its next poll.

        Allowed values: "pending""syncing""ready""failed"

      • last_synced_atstring (date-time) or nullrequired

        When the last sync finished successfully; null until the first one.

      • errorBrainSourceError or nullrequired

        Set only when state is failed.

      • document_countintegerrequired

        at least 0

      • bytesintegerrequired

        The bytes of the originals the source holds, which is what counts against the plan.

        at least 0

      • media_typestring or nullrequired

        The type core detected from the bytes, for kind upload; null otherwise.

      • urlstring or nullrequired

        For kind url, the normalized address; null otherwise.

        at most 2048 characters

      • gitBrainGitSource or nullrequired

        For kind git, its settings; null otherwise.

      • created_atstring (date-time)required
      • sync_interval_minutesintegeroptional

        For kind url with polling, how often the page is fetched again; omitted otherwise.

        5 to 1440

    • next_cursorstring or nullrequired
  • 400

    A filter or a limit outside its range, 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

POST/brain/v1/sources

Add a source: a file, a link or a repository

Credential
API key
Permission
brain.manage

Adds a source to the space named by the `space` query parameter, chosen by Content-Type, and answers 201 with it, pending: the worker fetches, extracts, chunks, embeds and indexes it, and the source ends ready or failed (see `error`). multipart/form-data adds a file: exactly one part named `file`, up to 50 MiB (the route's body cap is 50 MiB plus the form's framing). core detects the type from the bytes (the declared type and the extension are only hints): text/plain, text/markdown, application/json (it must parse), text/csv and application/pdf.

Read more

Images are not accepted in B1: an image is 415 source-type-not-supported. application/json adds a public web page (kind url), fetched once and again at its `sync_interval_minutes` when one is given, or a git repository folder on gitlab.com or github.com (kind git); the access token of a git source is sealed and write-only. A request that carries an access token on a plane without the platform keyring is refused with 503 credential-store-unavailable and nothing is stored. Core checks the credential with the provider before storing the source: a credential the provider refuses is 422 source-repository-auth. Webhooks are not part of this contract: a source syncs by poll (`sync_interval_minutes`) and by the sync route. A caller holding `brain.manage` writes any space; an admin of a team writes that team's spaces. An upload whose bytes (SHA-256) are already in the same space is 409 source-duplicate, as in chat; a failed source does not count. At the capacity of the plan new ingestion is refused with 409 brain-capacity-exceeded and nothing is deleted. Embeddings run as the organization's Brain principal, outside the caller's request limits and credits. Caps of B1: an uploaded file is at most 50 MiB (413 source-too-large); the body a link answers is at most 20 MiB; a file of a git repository is at most 5 MiB; a git source holds at most 5,000 files; the text extracted from one document is at most 2,000,000 characters. Chat's rules apply to the text cap: nothing is truncated, and a document above it fails with source-too-much-text. A link that answers more than 20 MiB ends its source failed with source-too-large. A git file above 5 MiB is skipped and reported, not fatal: its document is failed with source-too-large and the source and its other documents are unaffected. A repository with more than 5,000 files in the folder fails the whole sync with source-too-large. Images are not accepted in B1: an image upload is 415 source-type-not-supported, a link that answers an image ends its source failed with source-type-not-supported, and a git source never indexes an image (it reads only .md, .markdown, .txt, .csv, .json and .pdf files).

curl
curl -X POST "https://api.us.ccsio.ai/brain/v1/sources?space=<space>" \
  -H "Authorization: Bearer $CCSIO_API_KEY" \
  -F file=@audio.wav

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
required
querystring

The space the source is added to.

Request body multipart/form-data

  • filestringrequired

    The file, at most 50 MiB.

Responses

  • 201

    The source as stored, pending.

    Schema
    BrainSource
    • 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}$

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

    • kindstringrequired

      Allowed values: "upload""url""git"

    • namestringrequired

      For a file, its cleaned name; for a link, the page's title or its host and path; for a repository, `owner/name`, unless the creator chose a name.

      1 to 255 characters

    • statestringrequired

      pending: stored, not yet picked up. syncing: being fetched, extracted and indexed. ready: searchable. failed: see `error`; a git source tries again at its next poll.

      Allowed values: "pending""syncing""ready""failed"

    • last_synced_atstring (date-time) or nullrequired

      When the last sync finished successfully; null until the first one.

    • errorobject or nullrequired

      Set only when state is failed.

      • codestringrequired

        One of: source-url-refused (the address, a redirect or the host was refused), source-url-unreachable (DNS, connection, TLS or timeout), source-url-status (the page did not answer 2xx), source-repository-unreachable (the branch cannot be read), source-repository-auth (the token was refused, or none was given for a private repository), source-no-text, source-too-much-text (a document above 2,000,000 characters of text), source-extraction-failed, source-embedding-failed, source-too-large (a link answered more than 20 MiB, a git file is above 5 MiB, or a git source holds more than 5,000 files), source-type-not-supported (an image, or bytes that are not an accepted type), brain-capacity-exceeded (the Brain had no room left for what the sync read; nothing of that sync was kept). The codes that exist in chat (source-url-refused, source-url-unreachable, source-url-status, source-no-text, source-too-much-text, source-extraction-failed, source-embedding-failed, source-too-large, source-type-not-supported) keep their chat meaning. On a document, the error of an oversized git file or of a document above the text cap says why that one document is failed while its source stays ready.

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

      • messagestringrequired
    • document_countintegerrequired

      at least 0

    • bytesintegerrequired

      The bytes of the originals the source holds, which is what counts against the plan.

      at least 0

    • media_typestring or nullrequired

      The type core detected from the bytes, for kind upload; null otherwise.

    • urlstring or nullrequired

      For kind url, the normalized address; null otherwise.

      at most 2048 characters

    • gitobject or nullrequired

      For kind git, its settings; null otherwise.

      • providerstringrequired

        Allowed values: "gitlab""github"

      • repositorystring (uri)required

        An https URL of the repository on gitlab.com (provider gitlab) or github.com (provider github), with no user info, query or fragment. These two are the only providers and hosts of B1: any other host, a self-managed GitLab and GitHub Enterprise included, is 422 source-url-refused.

        at most 2048 characters

      • branchstringrequired

        1 to 255 characters · default "main"

      • pathstringrequired

        A folder of the repository, relative, with no `..`. The empty string is the repository root.

        at most 1024 characters · default ""

      • modestringrequired

        documents: the files are indexed as raw documents. pages: the files become Brain pages and the repository is their source of truth (edits happen by merge request; the pages are read-only in the API).

        Allowed values: "documents""pages"

        default "documents"

      • sync_interval_minutesintegerrequired

        How often the source is polled for changes. Webhooks are not part of this contract: a source syncs by poll and by the sync route.

        5 to 1440 · default 15

      • access_token_configuredbooleanrequired

        Whether an access token is stored for the repository. The value is never returned.

    • created_atstring (date-time)required
    • sync_interval_minutesintegeroptional

      For kind url with polling, how often the page is fetched again; omitted otherwise.

      5 to 1440

  • 400

    No file part, a second file part, a part under another name, a malformed form or body, a file with no name, an unknown kind or 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.manage` in the organization, or in the team of the space. 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.

  • 409

    The organization reached its Brain capacity, or the uploaded bytes are already in that space. Codes: brain-capacity-exceeded, source-duplicate

  • 413

    The file is above 50 MiB. Codes: source-too-large

  • 415

    The bytes are not an accepted type, or are an image (images are not accepted in B1). Codes: source-type-not-supported

  • 422

    The address of a link or a repository is refused (scheme, host, port, user info, the deny list, a git host that is not gitlab.com or github.com for its provider), core could not read the branch of the repository, or the provider refused the access token (or the repository is private and none was given). Codes: source-url-refused, source-repository-unreachable, source-repository-auth

  • 500

    Platform failure. Codes: internal-error

  • 503

    The request carries an access token and the plane has no encryption keyring, so the token cannot be sealed. Nothing is stored. Codes: credential-store-unavailable

GET/brain/v1/sources/{source}

Read a source

Credential
API key
Permission
brain.read

Answers one source with its state, its counts and, for a git source, its settings (never its token).

curl
curl "https://api.us.ccsio.ai/brain/v1/sources/{source}" \
  -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.

source
required
pathstring

The source's id. A source in a space the caller's audience does not reach is answered as one that does not exist.

Responses

  • 200

    The source.

    Schema
    BrainSource
    • 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}$

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

    • kindstringrequired

      Allowed values: "upload""url""git"

    • namestringrequired

      For a file, its cleaned name; for a link, the page's title or its host and path; for a repository, `owner/name`, unless the creator chose a name.

      1 to 255 characters

    • statestringrequired

      pending: stored, not yet picked up. syncing: being fetched, extracted and indexed. ready: searchable. failed: see `error`; a git source tries again at its next poll.

      Allowed values: "pending""syncing""ready""failed"

    • last_synced_atstring (date-time) or nullrequired

      When the last sync finished successfully; null until the first one.

    • errorobject or nullrequired

      Set only when state is failed.

      • codestringrequired

        One of: source-url-refused (the address, a redirect or the host was refused), source-url-unreachable (DNS, connection, TLS or timeout), source-url-status (the page did not answer 2xx), source-repository-unreachable (the branch cannot be read), source-repository-auth (the token was refused, or none was given for a private repository), source-no-text, source-too-much-text (a document above 2,000,000 characters of text), source-extraction-failed, source-embedding-failed, source-too-large (a link answered more than 20 MiB, a git file is above 5 MiB, or a git source holds more than 5,000 files), source-type-not-supported (an image, or bytes that are not an accepted type), brain-capacity-exceeded (the Brain had no room left for what the sync read; nothing of that sync was kept). The codes that exist in chat (source-url-refused, source-url-unreachable, source-url-status, source-no-text, source-too-much-text, source-extraction-failed, source-embedding-failed, source-too-large, source-type-not-supported) keep their chat meaning. On a document, the error of an oversized git file or of a document above the text cap says why that one document is failed while its source stays ready.

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

      • messagestringrequired
    • document_countintegerrequired

      at least 0

    • bytesintegerrequired

      The bytes of the originals the source holds, which is what counts against the plan.

      at least 0

    • media_typestring or nullrequired

      The type core detected from the bytes, for kind upload; null otherwise.

    • urlstring or nullrequired

      For kind url, the normalized address; null otherwise.

      at most 2048 characters

    • gitobject or nullrequired

      For kind git, its settings; null otherwise.

      • providerstringrequired

        Allowed values: "gitlab""github"

      • repositorystring (uri)required

        An https URL of the repository on gitlab.com (provider gitlab) or github.com (provider github), with no user info, query or fragment. These two are the only providers and hosts of B1: any other host, a self-managed GitLab and GitHub Enterprise included, is 422 source-url-refused.

        at most 2048 characters

      • branchstringrequired

        1 to 255 characters · default "main"

      • pathstringrequired

        A folder of the repository, relative, with no `..`. The empty string is the repository root.

        at most 1024 characters · default ""

      • modestringrequired

        documents: the files are indexed as raw documents. pages: the files become Brain pages and the repository is their source of truth (edits happen by merge request; the pages are read-only in the API).

        Allowed values: "documents""pages"

        default "documents"

      • sync_interval_minutesintegerrequired

        How often the source is polled for changes. Webhooks are not part of this contract: a source syncs by poll and by the sync route.

        5 to 1440 · default 15

      • access_token_configuredbooleanrequired

        Whether an access token is stored for the repository. The value is never returned.

    • created_atstring (date-time)required
    • sync_interval_minutesintegeroptional

      For kind url with polling, how often the page is fetched again; omitted otherwise.

      5 to 1440

  • 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 source 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: source-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

PATCH/brain/v1/sources/{source}

Change a source

Credential
API key
Permission
brain.manage
Request body
Body up to 1 MiB

Changes the name, the poll interval and, for a git source, the branch, the path and the access token of a source, and answers 200 with it. The access token is sealed and write-only; send `access_token: null` to clear it.

Read more

A new token is checked with the provider (422 source-repository-auth when it is refused) and, on a plane without the platform keyring, refused with 503 credential-store-unavailable. For a link, `sync_interval_minutes` (5 to 1440) sets how often it is fetched again and `null` stops the polling, leaving only the sync route; a git source always polls, so null is refused there. Changing `branch` or `path` re-syncs the source from scratch: documents and pages that no longer match are removed with their chunks, search data and stored originals, as on delete, and the source is pending again; the other members change nothing in the documents. Unknown members are refused. The body is capped at 1048576 bytes.

curl
curl -X PATCH "https://api.us.ccsio.ai/brain/v1/sources/{source}" \
  -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.

source
required
pathstring

The source's id. A source in a space the caller's audience does not reach is answered as one that does not exist.

Request body application/json

BrainSourceUpdateRequest
  • namestringoptional

    1 to 255 characters

  • sync_interval_minutesinteger or nulloptional

    How often the source is polled. For a link, null stops the polling; a git source always polls.

    5 to 1440

  • branchstringoptional

    1 to 255 characters · default "main"

  • pathstringoptional

    A folder of the repository, relative, with no `..`. The empty string is the repository root.

    at most 1024 characters · default ""

  • access_tokenstring or nulloptional

    A new token that can read the repository. Sealed and write-only: never returned and never logged. Send null to clear the stored token (the source then reads the repository without one); absent leaves it unchanged. The answer says only whether one is set, in access_token_configured.

    1 to 4096 characters

Responses

  • 200

    The source.

    Schema
    BrainSource
    • 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}$

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

    • kindstringrequired

      Allowed values: "upload""url""git"

    • namestringrequired

      For a file, its cleaned name; for a link, the page's title or its host and path; for a repository, `owner/name`, unless the creator chose a name.

      1 to 255 characters

    • statestringrequired

      pending: stored, not yet picked up. syncing: being fetched, extracted and indexed. ready: searchable. failed: see `error`; a git source tries again at its next poll.

      Allowed values: "pending""syncing""ready""failed"

    • last_synced_atstring (date-time) or nullrequired

      When the last sync finished successfully; null until the first one.

    • errorobject or nullrequired

      Set only when state is failed.

      • codestringrequired

        One of: source-url-refused (the address, a redirect or the host was refused), source-url-unreachable (DNS, connection, TLS or timeout), source-url-status (the page did not answer 2xx), source-repository-unreachable (the branch cannot be read), source-repository-auth (the token was refused, or none was given for a private repository), source-no-text, source-too-much-text (a document above 2,000,000 characters of text), source-extraction-failed, source-embedding-failed, source-too-large (a link answered more than 20 MiB, a git file is above 5 MiB, or a git source holds more than 5,000 files), source-type-not-supported (an image, or bytes that are not an accepted type), brain-capacity-exceeded (the Brain had no room left for what the sync read; nothing of that sync was kept). The codes that exist in chat (source-url-refused, source-url-unreachable, source-url-status, source-no-text, source-too-much-text, source-extraction-failed, source-embedding-failed, source-too-large, source-type-not-supported) keep their chat meaning. On a document, the error of an oversized git file or of a document above the text cap says why that one document is failed while its source stays ready.

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

      • messagestringrequired
    • document_countintegerrequired

      at least 0

    • bytesintegerrequired

      The bytes of the originals the source holds, which is what counts against the plan.

      at least 0

    • media_typestring or nullrequired

      The type core detected from the bytes, for kind upload; null otherwise.

    • urlstring or nullrequired

      For kind url, the normalized address; null otherwise.

      at most 2048 characters

    • gitobject or nullrequired

      For kind git, its settings; null otherwise.

      • providerstringrequired

        Allowed values: "gitlab""github"

      • repositorystring (uri)required

        An https URL of the repository on gitlab.com (provider gitlab) or github.com (provider github), with no user info, query or fragment. These two are the only providers and hosts of B1: any other host, a self-managed GitLab and GitHub Enterprise included, is 422 source-url-refused.

        at most 2048 characters

      • branchstringrequired

        1 to 255 characters · default "main"

      • pathstringrequired

        A folder of the repository, relative, with no `..`. The empty string is the repository root.

        at most 1024 characters · default ""

      • modestringrequired

        documents: the files are indexed as raw documents. pages: the files become Brain pages and the repository is their source of truth (edits happen by merge request; the pages are read-only in the API).

        Allowed values: "documents""pages"

        default "documents"

      • sync_interval_minutesintegerrequired

        How often the source is polled for changes. Webhooks are not part of this contract: a source syncs by poll and by the sync route.

        5 to 1440 · default 15

      • access_token_configuredbooleanrequired

        Whether an access token is stored for the repository. The value is never returned.

    • created_atstring (date-time)required
    • sync_interval_minutesintegeroptional

      For kind url with polling, how often the page is fetched again; omitted otherwise.

      5 to 1440

  • 400

    A body that is not strict JSON, has no member, names a member that does not exist, a value outside its range, or a git member on an upload or a link. 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.manage` in the organization, or in the team of the source's space. Codes: policy-denied, brain-disabled (the organization has no Brain capacity)

  • 404

    The source 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: source-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.

  • 409

    The organization reached its Brain capacity and the change would sync again. Codes: brain-capacity-exceeded

  • 422

    The new branch cannot be read, or the provider refused the new access token. Codes: source-repository-unreachable, source-repository-auth

  • 500

    Platform failure. Codes: internal-error

  • 503

    The change carries an access token and the plane has no encryption keyring. Nothing is changed. Codes: credential-store-unavailable

DELETE/brain/v1/sources/{source}

Delete a source

Credential
API key
Permission
brain.manage

Deletes a source and everything it produced: its documents and pages, their chunks and search data in the same transaction, and the stored originals. Answers 204. Nothing can be recovered; backups keep the data for their retention.

curl
curl -X DELETE "https://api.us.ccsio.ai/brain/v1/sources/{source}" \
  -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.

source
required
pathstring

The source's id. A source in a space the caller's audience does not reach is answered as one that does not exist.

Responses

  • 204

    The source and what it produced are deleted.

  • 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.manage` in the organization, or in the team of the space. Codes: policy-denied, brain-disabled (the organization has no Brain capacity)

  • 404

    The source 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: source-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

POST/brain/v1/sources/{source}/sync

Sync a source now

Credential
API key
Permission
brain.manage

Queues a sync of a url or git source without waiting for the next poll and answers 202 with the source, pending. A git source reads the changes since its last sync; a link is fetched again. A link without a `sync_interval_minutes` is fetched when it is added and again only by this route. A file source has nothing to sync, and a source that is already pending or syncing is not queued twice: both are 409 source-not-refreshable. No body.

curl
curl -X POST "https://api.us.ccsio.ai/brain/v1/sources/{source}/sync" \
  -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.

source
required
pathstring

The source's id. A source in a space the caller's audience does not reach is answered as one that does not exist.

Responses

  • 202

    The source, pending again.

    Schema
    BrainSource
    • 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}$

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

    • kindstringrequired

      Allowed values: "upload""url""git"

    • namestringrequired

      For a file, its cleaned name; for a link, the page's title or its host and path; for a repository, `owner/name`, unless the creator chose a name.

      1 to 255 characters

    • statestringrequired

      pending: stored, not yet picked up. syncing: being fetched, extracted and indexed. ready: searchable. failed: see `error`; a git source tries again at its next poll.

      Allowed values: "pending""syncing""ready""failed"

    • last_synced_atstring (date-time) or nullrequired

      When the last sync finished successfully; null until the first one.

    • errorobject or nullrequired

      Set only when state is failed.

      • codestringrequired

        One of: source-url-refused (the address, a redirect or the host was refused), source-url-unreachable (DNS, connection, TLS or timeout), source-url-status (the page did not answer 2xx), source-repository-unreachable (the branch cannot be read), source-repository-auth (the token was refused, or none was given for a private repository), source-no-text, source-too-much-text (a document above 2,000,000 characters of text), source-extraction-failed, source-embedding-failed, source-too-large (a link answered more than 20 MiB, a git file is above 5 MiB, or a git source holds more than 5,000 files), source-type-not-supported (an image, or bytes that are not an accepted type), brain-capacity-exceeded (the Brain had no room left for what the sync read; nothing of that sync was kept). The codes that exist in chat (source-url-refused, source-url-unreachable, source-url-status, source-no-text, source-too-much-text, source-extraction-failed, source-embedding-failed, source-too-large, source-type-not-supported) keep their chat meaning. On a document, the error of an oversized git file or of a document above the text cap says why that one document is failed while its source stays ready.

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

      • messagestringrequired
    • document_countintegerrequired

      at least 0

    • bytesintegerrequired

      The bytes of the originals the source holds, which is what counts against the plan.

      at least 0

    • media_typestring or nullrequired

      The type core detected from the bytes, for kind upload; null otherwise.

    • urlstring or nullrequired

      For kind url, the normalized address; null otherwise.

      at most 2048 characters

    • gitobject or nullrequired

      For kind git, its settings; null otherwise.

      • providerstringrequired

        Allowed values: "gitlab""github"

      • repositorystring (uri)required

        An https URL of the repository on gitlab.com (provider gitlab) or github.com (provider github), with no user info, query or fragment. These two are the only providers and hosts of B1: any other host, a self-managed GitLab and GitHub Enterprise included, is 422 source-url-refused.

        at most 2048 characters

      • branchstringrequired

        1 to 255 characters · default "main"

      • pathstringrequired

        A folder of the repository, relative, with no `..`. The empty string is the repository root.

        at most 1024 characters · default ""

      • modestringrequired

        documents: the files are indexed as raw documents. pages: the files become Brain pages and the repository is their source of truth (edits happen by merge request; the pages are read-only in the API).

        Allowed values: "documents""pages"

        default "documents"

      • sync_interval_minutesintegerrequired

        How often the source is polled for changes. Webhooks are not part of this contract: a source syncs by poll and by the sync route.

        5 to 1440 · default 15

      • access_token_configuredbooleanrequired

        Whether an access token is stored for the repository. The value is never returned.

    • created_atstring (date-time)required
    • sync_interval_minutesintegeroptional

      For kind url with polling, how often the page is fetched again; omitted otherwise.

      5 to 1440

  • 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.manage` in the organization, or in the team of the space. Codes: policy-denied, brain-disabled (the organization has no Brain capacity)

  • 404

    The source 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: source-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.

  • 409

    The source is a file, or is already pending or syncing, or the organization reached its Brain capacity. Codes: source-not-refreshable, brain-capacity-exceeded

  • 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