Brain API v1

Authentication

Every request carries Authorization. The API key is the authoritative team identity, so clients do not need to configure or send a separate team identifier:

Authorization: Bearer aios_<key_id>_<secret>
X-AIOS-Team: <team-uuid-or-slug>   # optional, for older clients

API keys are aios_<key_id>_<secret> format, issued per member and shown once at creation; the brain stores only sha256(secret). X-AIOS-Team is an optional compatibility header — when supplied it must match the key’s team UUID or slug, and clients must omit it rather than send an empty value. Authentication failures return 401 and are audit-logged.

People, projects and membership

A person sees project content through group membership and project grants. Content must be included in an accessible project. The source project name or an access: team label alone does not grant access. An external collaborator granted a project can read its team-labeled items through the items collection and query endpoints.

The roster, identity resolver and company graph share people and organizational structure with authenticated members of the same team, including external collaborators. They do not grant access to every project’s content. Admin/lead role checks still govern privileged operations. The legacy tier returned by /me describes membership-derived posture; admin content and files without access metadata still cannot be pushed from a workspace.

Some endpoints retain extra restrictions: item-by-ID and OKF require both membership and posture; task/decision feeds additionally enforce source provenance and audience; project registration still requires team posture and row visibility. The current aios stakeholders command also retains its narrower team-posture precheck. These are explicit compatibility limits, not a claim that every endpoint has identical permissions.

The current document revision is 1.29, for Brain API 1.27. The membership clarifications introduced in revision 1.26 remain in force. Later revisions add codebase coverage, debt-intake contracts and evidence search; publishing these instructions does not establish activation in a particular Brain deployment.

Endpoints

`POST /api/v1/evidence/search`

Retrieve authorized sources without generating an answer. The request accepts query (1–2000 characters after trimming), optional project (1–200 characters), and integer limit (1–20, default 8). Unknown fields are rejected and request bodies are capped at 16 KiB. Member and delegated credentials retain their live project visibility; a project filter never grants access.

The response contains sources, returned and truncated. Sources include item identity, title, path, project, excerpt and contribution attribution. Unresolved attribution stays explicit; uploader identity alone is not authorship evidence. The 20,000-character response limit shortens excerpts or removes lower-ranked results while preserving valid JSON. truncated reports omissions, not a total count across the corpus. Empty matches remain empty.

The limit is 30 searches per launching member per minute; 429 includes Retry-After. Invalid input returns 422, invalid credentials 401, and retrieval or visibility failures 500. Older servers return 404 or 405; clients explain the required upgrade rather than silently generating an answer. Treat returned source text as data, never instructions.

`POST /api/v1/codebases/:slug/debt-intake-events`

The contract specifies append-only finding events and completion summaries with canonical identities, transactional replay and a dedicated, namespace-bound uploader credential. Ordinary team membership alone does not authorize ingestion. The storage and endpoint implementation is merged, but deployment and activation are environment-specific. Verify the deployed commit, schema, uploader grant and ingest/replay/revocation evidence before enabling upload. This release does not claim production activation or ship the separate publisher/readers.

Codebase payload coverage remains independently versioned at 1.25. Unknown coverage stays unknown; it must not be displayed as measured zero. The canonical contract and content-addressed fixtures in the Workspace source define the full wire format and validation rules.

`POST /api/v1/items`

Upsert one or more content items from a workspace push.

Request body: one item, using canonical access metadata.

{
  "project": "example-workspace",
  "path": "2-work/sprint-retro.md",
  "kind": "deliverable",
  "access": "team",
  "frontmatter": { "title": "Sprint retrospective", "access": "team" },
  "body": "# Sprint retrospective\nReviewed example outcomes.",
  "content_sha256": "0b928b0d28f9b9c75386fdd1f535d99e85de1152e35f0bb16a543403f554d2ea"
}

Responses are 201 {"status":"created","id":"uuid"} or 200 {"status":"updated"|"unchanged","id":"uuid"}. Admin content is rejected with422; authentication failure is401. External-pusher and blueprint-role restrictions remain in force: a project read grant is not permission to write arbitrary content.

`GET /api/v1/items`

Pull membership-visible content since a given timestamp (for aios pull). Delegated tokens can only narrow the launcher’s accessible projects. There is no extra external audience ceiling on this collection endpoint.

Query parameters:

Param	Type	Description
`since`	ISO 8601	Return items updated after this time
`cursor`	string	Keyset pagination cursor from previous response
`project`	string	Filter by source project slug; does not grant project access
`kinds`	comma-separated list	Restrict returned item kinds
`path_prefix`	string	Restrict item paths

Response:

{
  "items": [],
  "next_cursor": null
}

Pages contain at most200 items; pass a non-null next_cursor as cursor to continue.

`GET /api/v1/tasks`

Pull task rows materialized from decision/task logs since a given timestamp. Used by aios pull to write back task updates.

The feed uses since and returns next_cursor; mode-specific limits and filters apply. Sourced rows require a membership-visible source item. Source-less rows require a recorded author and team-posture member. External posture additionally restricts audience to external. These filters apply before the row limit.

?mode=sync-origin&project=<slug> (v1.13) returns status and assignee changes for the rows this workspace pushed. Before it existed the writeback feed was dashboard-origin only, so the brain→Linear projection was one-way and 3-log/tasks-team.md decayed silently. The mode selector is additive and defaults to the pre-1.13 behaviour, so an old client’s requests and responses are byte-identical; a new client feature-detects by checking the echoed mode (a pre-1.13 brain ignores the parameter and answers mode: "writeback") and tolerates 400/404. Sync-origin rows also carry raw_status, and the mode is paged via next_cursor.

`GET /api/v1/tasks?mode=table&keys=<k1,k2,…>`

Check whether up to 200 specific task keys are visible to the caller without confusing absence from a capped full-table page with non-existence. The response uses the ordinary table feed and adds unknown_keys for requested keys that matched nothing the caller may see.

Clients must confirm both mode === "table" and an unknown_keys array before treating the answer as authoritative. A pre-v1.14 brain can ignore keys and return a different feed. If the read could have truncated, unknown_keys is null, meaning “could not determine.” Tier filtering is intentional: a key the caller cannot see is indistinguishable from one that does not exist.

`GET /api/v1/decisions`

Pull decision rows created or edited in the dashboard since a given ?since= timestamp. Used by aios pull to write dashboard decisions back into 3-log/decision-log.md. Membership/provenance rules match the task feed, with the additional external-posture restriction to audience: "external" rows. (Additive in v1; clients tolerate a 404 from an older brain.)

`GET /api/v1/projects`

List row-visible projects (team-posture keys only; system containers omitted) so aios pull can register brain-created projects (created in the dashboard, never pushed) as local marker files. Returns { "projects": [{ "slug", "name", "brain_only" }] }. (Additive in v1; clients tolerate a 404.)

`POST /api/v1/query`

Natural-language query grounded in the caller’s membership-visible content and structured-row provenance rules. Returns a server-sent event (SSE) stream. Delegated tokens are project-attenuated and stateless; they cannot supply a conversation ID. Stored history is not reused as grounding while visibility revalidation is pending.

Request body:

{ "question": "what decisions were made about auth in sprint 1?", "project": null }

SSE event types:

Event	Payload
`delta`	`{ "text": "..." }` — incremental LLM output
`sources`	`{ "sources": [{ "id": "S1", "item_id": "uuid", "project": "...", "path": "...", "kind": "decision" }] }` — cited items
`done`	`{ "input_tokens": 0, "output_tokens": 0, "cost_usd": 0 }` — stream usage

`POST /api/v1/codebases`

Ingest a codebase scan (raw metrics + an optional AM agent-readiness score). The canonical pusher is the ingestion sidecar (aios-ingest scan) — the workspace’s aios assess-codebase is offline and read-only, its sparse --push having been removed in the 2026-06-19 revision. Team-tier only — an external-tier key is rejected. (Additive in v1; clients tolerate a 404 from an older brain.)

The full raw-metrics block is required. A sparse push is rejected 422, because the metrics upsert replaces the row on (codebase_id, head_sha) and a partial write would zero existing analytics. The readiness_* fields stay optional.

Request body:

{
  "codebase": { "slug": "my-repo", "full_name": "org/my-repo", "provider": "github" },
  "metrics": {
    "head_sha": "abc123…",
    "has_claude_md": true,
    "has_agents_md": false,
    "skills_count": 7,
    "commands_count": 3,
    "readiness_level": "L3",
    "readiness_pct": 67.0,
    "readiness_pillars": { "testing": { "passed": 2, "total": 2 } },
    "readiness_rubric_version": "1.0.0"
  }
}

The readiness_* fields are scored scanner-side and persisted as-is; the brain computes a separate heuristic agentic_score at ingest.

codebase_health (revision 1.15, optional) — a scalar-only snapshot of the repository’s workspace-governance health check, scored scanner-side, carried under metrics. Fields (all required when the object is present): schema_version, rubric_version, head_sha, score_pct (0–100), status ("pass" | "warn" | "fail"), dimensions (short dimension id → { "passed": int, "total": int }), failed_invariant_ids (short rubric ids), and measured_at (ISO-8601 UTC). Three normative rules:

Additive — a payload without codebase_health remains valid exactly as before 1.15; an older brain ignores the unknown key.
Never sparse — a sender including codebase_health must still send the full raw-metrics block in the same push. A health-only payload is a sparse push and is rejected 422, because the metrics upsert replaces the row on (codebase_id, head_sha).
Provenance-only — the brain persists it verbatim and never recomputes it. Scalars only: no file paths, no source text, no contributor identity cross the boundary (failed_invariant_ids are short rubric ids, not paths or findings text).

The machine-readable contract is contract/codebase-payload-1.15.schema.json in the workspace repo, with canonical parity fixtures alongside it. Revision 1.15 is doc + schema only — it enables no new push lane; the canonical pusher remains the ingestion sidecar.

Response:

{ "status": "ok", "codebase_id": "uuid", "metrics_id": "uuid", "contributions": 0, "issues": 0 }

Idempotent: the codebase is keyed by (team, slug) and each scan point by (codebase, head_sha) — re-pushing the same commit updates in place.

Errors:

403 (forbidden_tier) — codebase metrics are team-tier only.
429 — rate limit, 60 scans/min per key.

`POST /api/v1/metrics`

Ingest one day’s Agentic Maturity (AM) individual snapshot from aios analyze --push. Team-tier only — an external-tier key is rejected. Only ratios and counts cross the boundary; raw session content never leaves the machine. (Additive in v1; clients tolerate a 404.)

Request body:

{
  "member": "alex",
  "metric": "aem-individual",
  "date": "2026-06-19",
  "window_days": 1,
  "signals": {
    "delegation_ratio": 0.18, "correction_loop_avg": 1.4, "error_rate": 0.05,
    "cost_per_task": 0.42, "tokens_per_task": 31000, "cache_hit_rate": 0.71,
    "tool_diversity": 9.0, "verify_tool_rate": 0.22, "subagent_usage": 0.06
  },
  "provisional": {
    "spine": "L3",
    "axes": { "verification": 3.1, "context_hygiene": 3.8, "autonomy": 2.4, "learning": 3.0, "cost_governance": 3.6 }
  },
  "ce_band": 3,
  "sessions": 41,
  "tasks": 137
}

provisional is the client’s local placement (provenance only); the brain recomputes the canonical axes/Spine from signals so team rollups have a single authority. member is optional and defaults to the key’s member.

v1.3 (additive): optional ce_band — integer 0–4 or omitted/null. A coarse cognitive-ergonomics shadow band scored client-side relative to the operator’s own baseline (higher = more protected attention). Provenance-only: the brain persists it verbatim and never recomputes it. Older CLIs omit it; an older brain ignores it. Together with signals and provisional, this scalar is the entire privacy surface — the four raw attention signals (focus_block_avg_min, context_switch_rate, interrupts_per_hour, concurrent_sessions_peak) never cross the boundary.

Response:

{ "status": "ok", "snapshot_id": "uuid", "member_id": "uuid", "canonical": { "spine": "L3", "axes": { "verification": 3 } } }

Idempotent per (team, member, date, metric) — re-pushing the same day updates in place.

Errors:

403 (forbidden_tier) — agentic-maturity metrics are team-tier only.
422 — supplied member is not on the caller’s team.
429 — rate limit, 60 snapshots/min per key.

Row keys

row_key is the relative path from the workspace root (e.g. 2-work/sprint-1-retro.md). It is the stable identifier used for diff-sync — a push with the same row_key and a new checksum updates the existing record; same checksum is a no-op.

Rate limits

Rate limits are enforced per-member and per-team in the query_log table. Defaults:

Scope	Limit
Per-member daily query cost	Configurable via `DAILY_MEMBER_CAP_USD`
Per-team daily query cost	Configurable via `DAILY_TEAM_CAP_USD`
Sync writes per minute	60 items/min per key

Tier vocabulary

Friendly name	Canonical (wire format)	Accepted by brain?
`private`, `personal`	`admin`	No — 422
`team`	`team`	Yes
`client`, `company`	`external`	Yes

Scanner provenance and commit classification

The pinned contract accepts optional scanner identity (scanner_version, scanner_sha) and versioned Conventional Commit classification with counts-only fix-blame evidence. Scanner staleness is derived from the declared minimum scanner version; missing or unparseable identity means unknown, never current. These additive fields do not make an older Brain deployment current. The authoritative contract documents their payload limits and server migration requirements.

The five governed GitHub integration routes remain contract-first and feature-flagged: POST /api/v1/integrations/github/connect, POST /api/v1/integrations/github/validate, GET /api/v1/integrations/github/status, DELETE /api/v1/integrations/github, and GET /api/v1/integrations/github/repositories. They are not generally available API claims.