REST/JSON is the source of truth
/agent/v1 exposes capabilities, project, graph, context, proposal, batch, event, and readback. CLI and MCP stdio are thin adapters and do not read SQLite directly.
Developer docs
Connect compatible tools to local GrowthMap through one governed contract.
This is advanced integration reference. The interface is local on 127.0.0.1, not a public cloud API or a claim of named one-click integrations.
01 / Interfaces and shared semantics
Context Packet
It includes target, ancestors, children/current work, decisions, constraints, risks, relations, revisions, and a snapshot digest.
02 / Authority and consistency
Grant scope
Read, propose, and write may be limited to a project, exact node, or branch descendants, and may expire or be revoked.
Revision and 409
Writes carry expected project and entity revisions. A mismatch returns 409; refresh the Context Packet and reconcile before retrying.
Atomic batch
A batch applies completely or not at all, preventing partial updates.
Idempotency and receipt
The same idempotency key and request can safely retry and return the same receipt. Reusing a key with a changed payload is rejected.
03 / Repository-contract-verified read-only example
CLI / HTTP
CLI default context: python3 scripts/growthmap_agent.py context --token-file <OWNER_ONLY_TOKEN_FILE> --base-url http://127.0.0.1:8100/agent/v1 --target <PROJECT_NODE_UUID>. On POSIX, the token file must be owner-only. Separately, HTTP may request an objective: GET /agent/v1/context/<PROJECT_NODE_UUID>?objective=read-only-context with Authorization: Bearer <GRANT_TOKEN>; never put the token in the URL.
04 / Integration status and limits
Available now
Local REST/JSON v1, generic CLI, MCP stdio, grant scopes, human review, revision 409, atomic batches, idempotent receipts, and readback.
Prototype or planned
The running API returns Context Packets, but a standalone JSON Schema, complete examples, per-tool guides, and conformance tests are not published.
Not included
There is no public cloud Agent API, cloud synchronization, real-time shared workspace, automatic Git scanning, automatic Agent execution, system authority, or named official one-click integration.