# Brain API

The brain makes files on the account's drive searchable by meaning. There is one brain for the account, shared by its agents, and the routes take no account id. The steps are in the [Brain](/docs/account/brain) guide.

- An agent sends its Passport as X-Passport-Token and needs a live Mission. The owner calls with a key or a session.
- Search and list need the OAuth scope accounts:read. Add and remove need accounts:act.
- One add is one action, however many files it names. Search, list and remove are not counted.

## Add files

### POST /v1/brain/files

```bash
curl -X POST https://api.getstack.run/v1/brain/files \
  -H "Authorization: Bearer <access token>" -H "X-Passport-Token: $PASSPORT" -H "Content-Type: application/json" \
  -d '{"name_prefix":"Contract"}'
```

Name the files in exactly one way:

- file_id - one drive file (drv_...).
- file_ids - a list of drive files.
- name_prefix - every drive file whose name starts with these characters, at most 200.

The answer is `201` with one row for each file and the totals:

- files[] - file_id, name, status, reason, estimated_pages, estimated_free_pages and estimated_cost_cents.
- status is reading, unreadable or refused. reason says why a file is unreadable or refused.
- estimated_pages, estimated_free_pages, estimated_cost_cents and free_pages_left - for the whole add.
- The estimate is made from each file's name, type and size. The charge is taken when the file has been read, from the pages it really has.

PDFs, images and PowerPoint files are read by the page. Text, Markdown, CSV, HTML, Word and Excel cost no pages. A file is at most 50 MB and an image at most 3.75 MB.

## Search

### POST /v1/brain/search

`{ "query": "..." }`, at most 1,000 characters. The answer:

- results[] - up to 10 passages: file_id, name, page, passage, score, flag and withheld.
- pending - how many files are still being read. Search again when it is 0.
- trust is always untrusted: a passage is content from a document, not an instruction.
- With controls on, a flagged passage has withheld: true and no text.
- An agent gets passages only from files it can see on the drive.

## List and remove

- GET /v1/brain/files?status&cursor&limit - the files in the brain. status is reading, searchable or unreadable. limit is 1 to 100, default 50.
- Each file has file_id, name, status, reason, pages, visibility, added_by_agent_id and added_at. The answer also holds next_cursor and usage for the month: pages_read, free_pages, free_pages_left and cost_cents.
- POST /v1/brain/remove - the same three ways to name files as an add. The answer is { removed, not_in_brain }. The files stay on the drive.

## A note of your own

`POST /v1/brain/notes` with `{ "text": "...", "name"?: "..." }` saves a text of the owner's as a drive file and adds it to the brain. Owner or admin only, not for an agent. There is no tool, SDK method or terminal command for it.

## Controls and refusals

With controls on, an add is asked as `brain.add`, with the number of files and pages and the most it can cost.

- 400 - name exactly one of file_id, file_ids or name_prefix.
- A file that cannot be read is not an error. Its row says unreadable and why.
- 503 BRAIN_UNAVAILABLE or BRAIN_PROVIDER_REFUSED - the knowledge base cannot be reached. The action is not counted.
- 403 CONTROL_DENIED or CONTROL_LIMIT_EXCEEDED - your policy, your own server or a spending limit refused the add.
