The descriptions of the operations and fields are the contract’s own, in English.
/brain/v1/sourcesList 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 "https://api.latam.ccsio.ai/brain/v1/sources" \
-H "Authorization: Bearer $CCSIO_API_KEY"Parameters
| Name | In | Description |
|---|---|---|
X-Request-IDoptional | header | string Optional request ULID. A valid ULID (upper or lowercase) is honored; when the header is absent or invalid, the runtime mints the id. The response X-Request-ID header carries the canonical uppercase form. |
spaceoptional | query | string Only this space. |
kindoptional | query | string Only sources of this kind. |
stateoptional | query | string Only sources in this state. |
cursoroptional | query | string The `next_cursor` of the previous page; absent starts at the first item. A cursor that this plane did not write is refused with 400 invalid-request. |
limitoptional | query | integer The largest page, 1 to 100. Default 50. |
Responses
- 200
One page of sources.
Schema
BrainSourceListsourcesarray of BrainSourcerequiredNewest first.
idstringrequiredAn id generated by core: URL-safe, matching the C6 identifier pattern, and opaque to clients.
pattern ^[a-z][a-z0-9._-]{0,127}$
spacestringrequiredAn id generated by core: URL-safe, matching the C6 identifier pattern, and opaque to clients.
pattern ^[a-z][a-z0-9._-]{0,127}$
kindstringrequiredAllowed values:
"upload""url""git"namestringrequiredFor 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
statestringrequiredpending: 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 nullrequiredWhen the last sync finished successfully; null until the first one.
errorBrainSourceError or nullrequiredSet only when state is failed.
document_countintegerrequiredat least 0
bytesintegerrequiredThe bytes of the originals the source holds, which is what counts against the plan.
at least 0
media_typestring or nullrequiredThe type core detected from the bytes, for kind upload; null otherwise.
urlstring or nullrequiredFor kind url, the normalized address; null otherwise.
at most 2048 characters
gitBrainGitSource or nullrequiredFor kind git, its settings; null otherwise.
created_atstring (date-time)requiredsync_interval_minutesintegeroptionalFor 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
/brain/v1/sourcesAdd 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 -X POST "https://api.latam.ccsio.ai/brain/v1/sources?space=<space>" \
-H "Authorization: Bearer $CCSIO_API_KEY" \
-F file=@audio.wavParameters
| Name | In | Description |
|---|---|---|
X-Request-IDoptional | header | string Optional request ULID. A valid ULID (upper or lowercase) is honored; when the header is absent or invalid, the runtime mints the id. The response X-Request-ID header carries the canonical uppercase form. |
spacerequired | query | string The space the source is added to. |
Request body multipart/form-data
filestringrequiredThe file, at most 50 MiB.
Responses
- 201
The source as stored, pending.
Schema
BrainSourceidstringrequiredAn id generated by core: URL-safe, matching the C6 identifier pattern, and opaque to clients.
pattern ^[a-z][a-z0-9._-]{0,127}$
spacestringrequiredAn id generated by core: URL-safe, matching the C6 identifier pattern, and opaque to clients.
pattern ^[a-z][a-z0-9._-]{0,127}$
kindstringrequiredAllowed values:
"upload""url""git"namestringrequiredFor 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
statestringrequiredpending: 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 nullrequiredWhen the last sync finished successfully; null until the first one.
errorobject or nullrequiredSet only when state is failed.
codestringrequiredOne 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_countintegerrequiredat least 0
bytesintegerrequiredThe bytes of the originals the source holds, which is what counts against the plan.
at least 0
media_typestring or nullrequiredThe type core detected from the bytes, for kind upload; null otherwise.
urlstring or nullrequiredFor kind url, the normalized address; null otherwise.
at most 2048 characters
gitobject or nullrequiredFor kind git, its settings; null otherwise.
providerstringrequiredAllowed values:
"gitlab""github"repositorystring (uri)requiredAn 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
branchstringrequired1 to 255 characters · default "main"
pathstringrequiredA folder of the repository, relative, with no `..`. The empty string is the repository root.
at most 1024 characters · default ""
modestringrequireddocuments: 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_minutesintegerrequiredHow 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_configuredbooleanrequiredWhether an access token is stored for the repository. The value is never returned.
created_atstring (date-time)requiredsync_interval_minutesintegeroptionalFor 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
/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 "https://api.latam.ccsio.ai/brain/v1/sources/{source}" \
-H "Authorization: Bearer $CCSIO_API_KEY"Parameters
| Name | In | Description |
|---|---|---|
X-Request-IDoptional | header | string Optional request ULID. A valid ULID (upper or lowercase) is honored; when the header is absent or invalid, the runtime mints the id. The response X-Request-ID header carries the canonical uppercase form. |
sourcerequired | path | string 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
BrainSourceidstringrequiredAn id generated by core: URL-safe, matching the C6 identifier pattern, and opaque to clients.
pattern ^[a-z][a-z0-9._-]{0,127}$
spacestringrequiredAn id generated by core: URL-safe, matching the C6 identifier pattern, and opaque to clients.
pattern ^[a-z][a-z0-9._-]{0,127}$
kindstringrequiredAllowed values:
"upload""url""git"namestringrequiredFor 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
statestringrequiredpending: 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 nullrequiredWhen the last sync finished successfully; null until the first one.
errorobject or nullrequiredSet only when state is failed.
codestringrequiredOne 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_countintegerrequiredat least 0
bytesintegerrequiredThe bytes of the originals the source holds, which is what counts against the plan.
at least 0
media_typestring or nullrequiredThe type core detected from the bytes, for kind upload; null otherwise.
urlstring or nullrequiredFor kind url, the normalized address; null otherwise.
at most 2048 characters
gitobject or nullrequiredFor kind git, its settings; null otherwise.
providerstringrequiredAllowed values:
"gitlab""github"repositorystring (uri)requiredAn 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
branchstringrequired1 to 255 characters · default "main"
pathstringrequiredA folder of the repository, relative, with no `..`. The empty string is the repository root.
at most 1024 characters · default ""
modestringrequireddocuments: 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_minutesintegerrequiredHow 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_configuredbooleanrequiredWhether an access token is stored for the repository. The value is never returned.
created_atstring (date-time)requiredsync_interval_minutesintegeroptionalFor 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
/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 -X PATCH "https://api.latam.ccsio.ai/brain/v1/sources/{source}" \
-H "Authorization: Bearer $CCSIO_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'Parameters
| Name | In | Description |
|---|---|---|
X-Request-IDoptional | header | string Optional request ULID. A valid ULID (upper or lowercase) is honored; when the header is absent or invalid, the runtime mints the id. The response X-Request-ID header carries the canonical uppercase form. |
sourcerequired | path | string 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
namestringoptional1 to 255 characters
sync_interval_minutesinteger or nulloptionalHow often the source is polled. For a link, null stops the polling; a git source always polls.
5 to 1440
branchstringoptional1 to 255 characters · default "main"
pathstringoptionalA folder of the repository, relative, with no `..`. The empty string is the repository root.
at most 1024 characters · default ""
access_tokenstring or nulloptionalA 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
BrainSourceidstringrequiredAn id generated by core: URL-safe, matching the C6 identifier pattern, and opaque to clients.
pattern ^[a-z][a-z0-9._-]{0,127}$
spacestringrequiredAn id generated by core: URL-safe, matching the C6 identifier pattern, and opaque to clients.
pattern ^[a-z][a-z0-9._-]{0,127}$
kindstringrequiredAllowed values:
"upload""url""git"namestringrequiredFor 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
statestringrequiredpending: 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 nullrequiredWhen the last sync finished successfully; null until the first one.
errorobject or nullrequiredSet only when state is failed.
codestringrequiredOne 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_countintegerrequiredat least 0
bytesintegerrequiredThe bytes of the originals the source holds, which is what counts against the plan.
at least 0
media_typestring or nullrequiredThe type core detected from the bytes, for kind upload; null otherwise.
urlstring or nullrequiredFor kind url, the normalized address; null otherwise.
at most 2048 characters
gitobject or nullrequiredFor kind git, its settings; null otherwise.
providerstringrequiredAllowed values:
"gitlab""github"repositorystring (uri)requiredAn 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
branchstringrequired1 to 255 characters · default "main"
pathstringrequiredA folder of the repository, relative, with no `..`. The empty string is the repository root.
at most 1024 characters · default ""
modestringrequireddocuments: 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_minutesintegerrequiredHow 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_configuredbooleanrequiredWhether an access token is stored for the repository. The value is never returned.
created_atstring (date-time)requiredsync_interval_minutesintegeroptionalFor 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
/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 -X DELETE "https://api.latam.ccsio.ai/brain/v1/sources/{source}" \
-H "Authorization: Bearer $CCSIO_API_KEY"Parameters
| Name | In | Description |
|---|---|---|
X-Request-IDoptional | header | string Optional request ULID. A valid ULID (upper or lowercase) is honored; when the header is absent or invalid, the runtime mints the id. The response X-Request-ID header carries the canonical uppercase form. |
sourcerequired | path | string 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
/brain/v1/sources/{source}/syncSync 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 -X POST "https://api.latam.ccsio.ai/brain/v1/sources/{source}/sync" \
-H "Authorization: Bearer $CCSIO_API_KEY"Parameters
| Name | In | Description |
|---|---|---|
X-Request-IDoptional | header | string Optional request ULID. A valid ULID (upper or lowercase) is honored; when the header is absent or invalid, the runtime mints the id. The response X-Request-ID header carries the canonical uppercase form. |
sourcerequired | path | string 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
BrainSourceidstringrequiredAn id generated by core: URL-safe, matching the C6 identifier pattern, and opaque to clients.
pattern ^[a-z][a-z0-9._-]{0,127}$
spacestringrequiredAn id generated by core: URL-safe, matching the C6 identifier pattern, and opaque to clients.
pattern ^[a-z][a-z0-9._-]{0,127}$
kindstringrequiredAllowed values:
"upload""url""git"namestringrequiredFor 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
statestringrequiredpending: 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 nullrequiredWhen the last sync finished successfully; null until the first one.
errorobject or nullrequiredSet only when state is failed.
codestringrequiredOne 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_countintegerrequiredat least 0
bytesintegerrequiredThe bytes of the originals the source holds, which is what counts against the plan.
at least 0
media_typestring or nullrequiredThe type core detected from the bytes, for kind upload; null otherwise.
urlstring or nullrequiredFor kind url, the normalized address; null otherwise.
at most 2048 characters
gitobject or nullrequiredFor kind git, its settings; null otherwise.
providerstringrequiredAllowed values:
"gitlab""github"repositorystring (uri)requiredAn 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
branchstringrequired1 to 255 characters · default "main"
pathstringrequiredA folder of the repository, relative, with no `..`. The empty string is the repository root.
at most 1024 characters · default ""
modestringrequireddocuments: 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_minutesintegerrequiredHow 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_configuredbooleanrequiredWhether an access token is stored for the repository. The value is never returned.
created_atstring (date-time)requiredsync_interval_minutesintegeroptionalFor 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.