API reference
Versioned source and work endpoints, request shapes, and error behavior.
Brainlyy is the account that makes private infrastructure reachable through one authenticated connection, with source provenance and machine-owned knowledge.
Local source-linked briefs
The authenticated local Work service supports an explicit local-model brief
in addition to its existing excerpt report. GET /api/v1/work/models reads the
supported local catalog without a prompt or download. POST /api/v1/work accepts
query, kind: source_brief, model: {name, digest} and one UUID request_key.
The server owns the endpoint and the worker stores the selected model identity.
The request body cannot add a workspace, endpoint, tool or verification status.
Brief records expose a structured document, a public model execution record
and separately computed citation checks. Source freshness is distinct from
conclusion review. JSON export uses kind: brainlyy.source-brief; append
?format=markdown to the existing artifact export path for a readable brief.
Repair and restore retain the original model and check records. See
source-linked briefs for the request, limits and recovery
behavior. Existing remote grants do not authorize this model operation.
The local MCP model tools also refuse incomplete, length-truncated, wrong-model, empty or tool-bearing responses. These local paths are distinct from the hosted native-name mappings below. Real provider qualification remains separate from the protocol tests.
Versioned work and source routes
The local /api/v1/work interface provides durable source reports, revision
history and exact approval for repair or restore. Its read-only
GET /api/v1/work/graph route links saved sources, versions, checks, runs,
reports and proposals. It checks current source access before returning these
records. See maintained work for inputs, outputs, access
rules and error codes, and managed graphs for the two graph
views and their limits. Work routes are refused over the relay.
The authenticated read API also provides GET /api/v1/sources,
GET /api/v1/sources/{id}/files, GET /api/v1/sources/{id}/preview and
GET /api/v1/sources/{id}/download. File paths use the path query parameter.
Listings accept offset and limit; downloads accept offset and version.
Each read resolves the source handle against current configuration. Four source
operations may run concurrently. Responses are not cached. See
source access for format and transfer limits.
The read-only MCP tool graph_data(query) returns a saved graph with provenance,
sampling and size limits applied to its MCP representation. code_search uses
the shared bounded Graphify executor. Neither tool treats graph edges as proof.
GET /api/v1/sources/{id}/graph/nodes?q=&limit=25 searches the full saved
index for endpoint candidates. GET /api/v1/sources/{id}/graph/path takes
start, end and optional directed=true|false. Use the returned opaque node
IDs. The read-only MCP equivalents are graph_nodes(root, query, limit) and
graph_path(root, start, end, directed). They preserve the chosen endpoints,
index revision, direction and relationship provenance. They share the two-read
graph limit. See source access for path limits and meaning.
This is the implemented revision contract, not a claim of full canonical protocol support. Target gaps are assigned to G1-06, G1-07 and G4. The mistaken navigation tables in the original API/MCP sections are replaced here by actual routes and tools.
Principals
Local onboarding additions
The authenticated local reader provides POST /api/setup/discover with an empty
JSON object and GET /api/setup/readiness. Both require an actual loopback
connection, reject relayed requests, enforce same-origin browser requests and
return Cache-Control: no-store. They are never exposed through account relay
access, even when remote writes are enabled.
Discovery reports versioned observations (schema_version: 1), capability
candidates, limitations and local readiness. permissions_changed is false and
sources_attached is zero. Finding a registration does not activate its tools.
Readiness checks local configuration, selected directories and credential files;
it does not certify inference, MCP integrations, remote access or autostart.
Existing GET /api/setup keeps its summary contract. POST /api/setup additionally
returns applied and readiness; invalid names, paths and passphrases are refused
before setup writes. These local reader additions do not change the distinct
hosted account routes described below.
Browser routes require an HttpOnly session cookie. Mutating browser API calls also require the X-Brainlyy-CSRF value issued to that session and valid Origin/Host policy. Gateway calls require a gateway credential. Relay calls require a distinct paired machine credential. Pair completion accepts an unexpired single-use code, not a browser token. Local reader traffic has its own private loopback credential.
The gateway accepts Authorization: Bearer and an explicit X-Auth-Token. When both are supplied, X-Auth-Token is the Brainlyy credential. This collision policy does not make unrelated bearer tokens valid. Raw credentials are not returned from list endpoints.
Read surfaces
| Method | Path | Purpose |
|---|---|---|
| GET | /healthz | Process status and version, not whole-system readiness. |
| GET | /login, /signup | Real provider handoff or explicit unconfigured state. |
| GET | /auth/callback | Bound one-use identity callback. |
| GET | /, /account, /machines | Account/local UI and machine navigation. |
| GET | /m/{id} | Authorized machine UI over the relay. |
| GET | /api/state | Account/local snapshot with safe session/token metadata. |
| GET | /m/{id}/api/state | The corresponding machine-scoped snapshot. |
| GET | /api/export | Service-held account metadata export. |
| GET | /api/evidence/verify | Local evidence integrity result where authorized. |
| GET | /docs/{page} | Canonical allowlisted documentation. |
| GET | /static/{asset} | Allowlisted shared assets; demo.js is not served. |
Mutating or request-body routes
| Method | Path | Input / boundary |
|---|---|---|
| POST | /api/search | query, scope; optional machine prefix. |
| POST | /api/ask | query, scope; current extractive retrieval, not model synthesis. |
| POST | /api/note | id, scope; opaque source id, never a filesystem path. |
| POST | /api/pair | Browser-authorized creation of a short-lived code. |
| POST | /api/pair/complete | code and machine metadata; creates scoped machine identity once. |
| POST | /api/tokens | name and granted scopes; returns a new secret once. |
| POST | /api/tokens/revoke | id; account-bound credential revocation. |
| POST | /api/sessions/revoke | id; session kind only, account-bound. |
| POST | /api/machines/remove | id; plane only, revokes machine credential. |
| POST | /api/account/delete | confirm exactly DELETE; active account deletion, backup caveat explicit. |
| POST | /api/integrations | name, url, reviewed tools; custom allowlisted HTTPS upstream only. |
| POST | /api/integrations/disconnect | id; account-bound disconnection. |
| POST | /api/health/probe | id; source round trip rather than timestamp. |
| POST | /api/checks/run | optional id; local authorized write only. |
| POST | /api/checks/update | id, name, target; local write, invalidates previous verification. |
| POST | /api/settings | workspace; current local preference editing only. |
| POST | /logout | Application session logout after confirmation/CSRF checks. |
| POST | /relay/poll | Paired machine credential; outbound poll. |
| POST | /relay/reply | Request correlation plus bounded reply; paired machine authority. |
| POST | /mcp | Authenticated JSON-RPC subset. |
Request and reply limits, error handling and authority checks are implemented in server.py, app.py, agent.py and relay.py. Current errors are JSON error objects or JSON-RPC error/isError replies. Uniform typed API error codes and full public API compatibility remain release work. Do not build production clients by inferring error semantics from text.
Native read tools
| Tool | Required input | Current result |
|---|---|---|
| search_notes | query | Attributed matches; optional personal/company scope and bounded limit. |
| read_note | id | Exact permitted source and provenance; optional scope. |
| ask_fast | query | Attributed excerpts or abstention; not a model-generated answer in this revision. |
| code_search | query | Limited Python AST symbols/import/call references; not resolved Graphify relationships. |
| list_claims | none | Evaluator-owned claim state. |
| list_evidence | none | Local chain records and integrity result. |
| machine_health | none | Live local reader response. |
The plane adds optional machine_id routing and namespaces opaque source ids. tools/list is authoritative for the actually available schema; do not expose a tool solely because the table lists its target name. The current remote native-name mapping is account-native; third-party tools use a server namespace.
A native result includes data, provenance and an untrusted_content marker. A plane fan-out result identifies each machine independently. Source-origin labeling does not verify the semantic truth of a note. Client and UI rendering must keep untrusted content out of executable HTML/instructions.
MCP transport limits
Current methods: initialize, ping, tools/list, tools/call and notifications/initialized. Protocol negotiation supports the implemented versions through 2025-11-25. GET /mcp returns 405. There is no server-to-client SSE stream, full current-protocol OAuth discovery or production client-conformance claim. The stdio bridge transports this declared JSON-HTTP subset only and does not add missing server features.
Target native write tools are post_message, run_agent, agent_status and rate_answer. They are not gateway tools in this revision. ask_licensed, real model generation, Hermes company search, provider catalogue OAuth and complete Graphify results remain gated work rather than placeholder successes.
Primary references for the implementation queue
The official MCP authorization specification, Auth0 session/logout documentation and W3C target-size guidance were checked when preparing this revision. They are reference requirements, not certifications of this build: