This is a technical reference for developers. If you just want to connect an AI tool, you do not need this: use a connection instead.
Base URL and authentication
All endpoints live underhttps://api.oncortex.ai/api/v1. Authenticate with a service credential as a bearer token:
Push to your default brain
The quickest way to capture something: post to the default inbox, which lands in the credential’s brain (or, for a signed-in user, their single writable brain when they have exactly one).externalId to a stable value so that re-sending the same thing does not create a duplicate.
Say where the document lives
Four optional fields record where a document lives, so the source record shows the link and later versions are linked as revisions:
When you give a reference and no
externalId, Cortex derives one as {provider}:{itemId}@{version}, so re-sending the same version is a no-op and a new version becomes a new item linked to the earlier one. The response of a GET on the new item carries revisionOf (the earlier item, its status and the pages it was filed to) and revisionDiff, a line diff of the two extractions.
Send the file itself
A JSON body can carry the document as base64 instead of text:contentBase64 and content are mutually exclusive. The decoded size is capped at 10 MB on this route; larger files go as multipart form data, up to 50 MB, where the same four fields are accepted as form fields. The same rules apply to your agent’s upload_to_inbox tool.
Two optional query parameters:
?brain={slugOrId}names a destination brain explicitly (it must be one the credential can write to; a brain-scoped credential can only name its own brain).?path={folder}suggests where the content should file. It is recorded as a hint for the filing pass, not an order; the content itself can never choose its own destination.?partition={key}names the client (or site, or matter) in a partitioned brain. An unknown or archived key is refused with a 422 that lists the existing keys. Without it, the attendee emails decide, or the item waits as “needs a client”.?skill={name}(orskillin the JSON body or as a form field) pins the filing skill:ingest,ingest-meeting,ingest-docoringest-conversation. A deliberate upload that names its skill skips the automatic filer’s “is this worth filing” check and goes straight to that skill; leave it out for ambient captures (a session hook, say) so the check still runs. A name that is not a skill is refused with a 400 that lists the skills. The sameskillargument is on your agent’supload_to_inboxtool.
Work with a specific brain’s inbox
Uploads accept either a JSON body (
filename, content or contentBase64, optional externalId, targetFolder, skill and the four reference fields above) or multipart form data for binary files, up to 50 MB, with canonicalUrl, provider, providerItemId, version and skill as form fields. The ?path={folder} and ?skill={name} hints work here too. Items carry skillHint (the pinned skill, or null), sourceReference, supersedesItemId and supersededByItemId; a GET on one item adds revisionOf and revisionDiff.
Pages, timelines and the graph
The page endpoints take a brain-scoped credential and the page path as?path=. Writes need a read-and-write credential.
An edit sent with a stale
expectedVersion, or one that lands while someone else is saving, is refused with a 409 and the message “This page was changed by someone else. Reload and try again.”; read the page again and resend.
Partitions
In a partitioned brain the clients (or sites, or matters) are managed here as well as on the Clients page. Roles are the caller’s role on the brain: a service credential carries the role it was issued with, so a Write credential can push and assign, an Admin credential can manage partitions, and only an Owner credential or an owner’s connection can purge.
Inbox listing takes
?partition={key} and ?unassigned=true. Search takes ?partition=, ?folder= and ?includeArchived=true (archived partitions are left out of results unless asked for).
Members
A brain’s access list can be managed here as well as on its Members page, so onboarding a person or an agent can be scripted. The caller needs Admin or Owner on the brain: a service credential counts with the role it was issued, so a read-and-write credential is refused with a 403 and can never widen anyone’s access. Only workspace members can be granted (invite them to the workspace first); one grant per person; the last Owner cannot be demoted or removed. Name the person by their user id or their email.
A grant for someone who already has access is refused with a 409; a grant for someone who is not in the workspace, a demotion of the last Owner, or an unknown role is a 400 with the reason. There is no agent tool for any of this, on purpose: an agent in a conversation cannot add or remove members.