---
name: bigbrain
description: Use the Big Brain HTTP API and MCP.
---

# Big Brain

Big Brain is an agentic knowledge platform. Authenticated agents use the
HTTP API and MCP. Unauthenticated callers are guests. They may read this 
skill, generated discovery documents, and any live public shares at
`GET /api/v1/shares/{id}`.

If you do **not** have access to something, do **not** attempt to find or 
manipulate resources to access it. Stop and ask for help.

## Discovery

- `/llms.txt` — curated index of public agent resources
- `/.well-known/agent-skills/index.json` — this skill
- `/.well-known/api-catalog` — HTTP APIs (RFC 9727)
- `/server-card` and `/.well-known/mcp.json` — MCP Streamable HTTP
- `/openapi.json` — OpenAPI 3 contract (public operations when unauthenticated)
- `/api/v1/discovery/skill` — canonical copy of this file

## HTTP API

Base path: `/api/v1`. The contract is `/openapi.json`. Unauthenticated
`GET /openapi.json` lists only public operations; send
`Authorization: Bearer <token>` on that request for the authenticated
caller contract.

Workspace files are protected by authorization. 
Do not call `GET /api/v1/{kind}/{id}` without authorization.

## MCP

Streamable HTTP at `/mcp`. Send `Authorization: Bearer <token>` (session
access token or a PAT prefixed `bbp_`).

Tools include `whoami`, instance verbs (`list`, `create`, `read`,
`update`, `delete`, `explain` with `kind=`), `browse_workspace`,
`resolve_workspace_path`, workspace CRUD, and admin kind tools.

## Authenticate

Call `/api/v1` and `/mcp` with `Authorization: Bearer <token>`.

## Content

File kinds (`document`, `audio`, `video`) live in a workspace
(`workspace`, `file_path`, `file_name`). Visibility defaults to
workspace members. File kinds reject `visibility=world` and
`visibility=authenticated` on the entity. Guests cannot list files or
read `GET /api/v1/{kind}/{id}` or `/api/v1/workspace/{slug}`.

## Sharing

An editor publishes one public link with `PUT /api/v1/{kind}/{id}/share`.
The response `id` is the token. Guests who know it read a projection at
`GET /api/v1/shares/{id}`: kind, file name, format, and text body. That
route does not grant the entity, the workspace, or attachments. The share
grant allows guests; the entity's `network` rules still apply, so
`network=private` means the link works only from the private network
(`AccessEnvironment.network=private`), not from the public internet.

Editors change visibility and network independently (`PUT
/api/v1/{kind}/{id}/access-rules`). A public link does not clear
`network=private`.

`GET /api/v1/{kind}/{id}/share` returns the active share for an editor, or
404. Publishing again returns the same id. `DELETE /api/v1/{kind}/{id}/share`
revokes it, and deleting the file deletes the share. The entity stays
`visibility=workspace`, or `private` when the editor chooses private.