REST API

Base URL#

A Station is one container serving three surfaces from one origin: the Studio console at /, this REST API under /v1, and the MCP endpoint at /mcp/. All three authenticate with the same keys and reach forests through the same policy gate.

https://station.example.com/v1

Run locally, station serve binds 127.0.0.1:8800 by default, so the base URL is http://localhost:8800/v1. Both the bind address and the port are flags:

station serve --root /forests --registry /registry/station.db \
  --host 0.0.0.0 --port 8800 --writable

Every request and every response is JSON, with one exception: POST /v1/admin/snapshots/import takes a multipart form because it carries a bundle file. Bodies are optional on primitive routes: an empty body is read as {}, and a body that is not a JSON object is refused with E_SCHEMA.

Versioning and changes#

This reference describes the Station shipped with MonkeyLLM v0.1.0, reviewed 2026-08-15. The engine is pre-1.0: it is in use, the shapes below are the shapes it returns today, and the surface is still moving. Pin the version you tested against.

/v1 is the compatibility unit, and what it promises is narrow and mechanical:

• Fields may be added. A new key in a response object, a new optional parameter on a request. Parse defensively: ignore keys you do not know rather than rejecting the payload.
• Fields are not removed or retyped under the same prefix. A route that has to drop a field or change its type gets a new prefix instead. /v1 does not change meaning underneath a client that already works.
• Error codes are stable, messages are not. Branch on error.code (see Errors). Never match on error.message or error.hint: both are written for a human reading a log and are edited freely.
• Budgets and caps are deployment settings, not contract. The default k, the token budgets and the rate limits move with configuration. Read them from the response (truncated, the RateLimit-* headers) rather than assuming a number.

Breaking changes are announced in the engine repository's release notes and carried in the changelog. GET /v1/health is the runtime check: it reports the mode and whether the Station is writable, which is what a client should assert on startup rather than inferring from a version string.

Authentication#

Every route except GET /v1/health and the three /v1/auth/* doors requires a key. A key identifies a principal; the principal holds grants; a grant binds one principal to one forest with capabilities and a branch scope. There is exactly one authorization path, and every door feeds into it.

Presenting a key#

Send the key as a bearer token, or in X-Api-Key if that is easier for your client. Keys begin with mk_. Only a digest is stored, so the plaintext exists exactly once, in the reply to the call that minted it.

curl -s https://station.example.com/v1/me \
  -H "Authorization: Bearer $MONKEYLLM_KEY"

# The same key, sent the other way:
curl -s https://station.example.com/v1/me \
  -H "X-Api-Key: $MONKEYLLM_KEY"

A missing, unknown, revoked or expired key is one answer with status 401:

{
  "error": {
    "code": "E_FORBIDDEN",
    "message": "missing or invalid API key"
  }
}

Claiming a new Station#

This is the one unauthenticated write in the API, and it is safe for exactly one reason: it exists only while there is nothing to escalate from. The moment it succeeds, or the moment a deployment declares an environment super admin, the route answers exactly as an unrouted path does, with 404 and no such endpoint: /auth/setup. It never says already configured, because whether a Station is up for grabs is not public information.

curl -sX POST https://station.example.com/v1/auth/setup \
  -H 'content-type: application/json' \
  -d '{
    "username": "jimmy",
    "password": "a-long-enough-passphrase",
    "email": "[email protected]"
  }'

{
  "key": "mk_9tK2wQ8pv1RfL0nYcXhA6ZbM4sEuD3gJ7iOaVrT5kNw",
  "principal": "jimmy",
  "expires_at": "2026-08-16T09:41:12+00:00",
  "admin": true,
  "owner": true
}

Sessions from a password#

The session token is an ordinary API key with a short life, so everything downstream, authentication, policy and audit, is the single path it already was. The door decides how the principal was established, never what it may do.

curl -sX POST https://station.example.com/v1/auth/login \
  -H 'content-type: application/json' \
  -d '{"username": "jimmy", "password": "a-long-enough-passphrase"}'

{
  "key": "mk_Xb7QpL2mR9wKvA0sZfEyH4nJdT6cU1gOiB3rY8kNVta",
  "principal": "jimmy",
  "expires_at": "2026-08-15T21:41:12+00:00",
  "admin": true,
  "owner": true
}

A wrong password, an unknown user and a user with no password at all return the same 401 and the same message, invalid username or password. Distinguishing them would turn the login form into a directory of who exists.

Paired keys#

Pairing is the door you hand a machine. It is unauthenticated for the same reason login is: it reaches nothing the password could not already reach, so an admin gate in front of it would only route the same authority through a wider credential. What makes the result safe is that a paired key can only narrow, never add.

• The mask is a ceiling. A paired key carries {read, ingest} by default, and that set is also the maximum. Asking for write, tend, query or admin is refused with E_SCHEMA.
• Grants intersect the mask at the moment of use. A grant revoked after pairing is gone from the key immediately, and a paired key held by the owner is still refused every admin route.
• It always expires. 90 days by default, 365 at most. Absent or 0 means the default, never unlimited, and a request over the ceiling is told the ceiling rather than silently clamped.

curl -sX POST https://station.example.com/v1/auth/pair \
  -H 'content-type: application/json' \
  -d '{
    "username": "jimmy",
    "password": "a-long-enough-passphrase",
    "label": "claude-code",
    "caps": ["read", "ingest"],
    "expires_in_days": 90
  }'

{
  "api_key": "mk_D5vN8hZq2WcJ1yLpXeT7bR0mKsA4gFuI6oQnV3rYtBd",
  "principal": "jimmy",
  "caps": ["ingest", "read"],
  "expires_at": "2026-11-13T09:41:12+00:00"
}

Minting and revoking keys#

A key authenticates a principal, and a principal may hold grants on several forests, so issuing one requires admin on every forest that principal is granted, not merely on one of them. Otherwise the administrator of one forest could mint a credential that opens another. The owner satisfies this trivially.

curl -sX POST https://station.example.com/v1/admin/keys \
  -H "Authorization: Bearer $MONKEYLLM_KEY" \
  -H 'content-type: application/json' \
  -d '{"principal": "reporting-bot", "label": "nightly", "expires_in_days": 30}'

{
  "api_key": "mk_T4jRw9YbK1sQ6hLzXaP0cVnE8mdU2fGoI5rNtA7vZyC",
  "principal": "reporting-bot",
  "keys": [
    {
      "id": "6f1c0b8e4a2d97c53b0e1f8a6d4c2b90e7a1f3c5d8b6094e2a7c1f5b3d9e0a84",
      "principal": "reporting-bot",
      "label": "nightly",
      "created": "2026-08-15T09:41:12+00:00",
      "prefix": "mk_T4jRw",
      "expires_at": "2026-09-14T09:41:12+00:00",
      "revoked_at": null,
      "last_used_at": null,
      "status": "active"
    }
  ]
}

status is derived, one of active, expired or revoked. Session tokens minted by /v1/auth/login are deliberately excluded from this listing: they are the by-product of a login, not a credential anyone manages.

Capabilities and scope#

There are exactly six capabilities.

A grant also carries branch-prefix scope: allow and deny lists of subtree prefixes, where deny wins at any depth and an empty allow means the whole forest. Prefixes compare with a trailing slash, so a grant on projects/ cannot accidentally swallow projects-secret/. A grant may also pin tables, a per-dataset list of the SQL tables the principal may name.

Errors#

Every failure is one envelope. hint is present when there is something actionable to say, and it is written for the caller, so show it.

{
  "error": {
    "code": "E_FORBIDDEN",
    "message": "'tend' requires the 'tend' capability",
    "hint": "This principal holds: ['ingest', 'read']."
  }
}

The code maps onto the HTTP status:

A code with no mapping falls back to 400. Beyond the table, three statuses come from the transport rather than from a code: 202 when a batch was accepted (see Ingestion), 304 when a payload or the Clipper archive revalidated against its ETag, and 429 from the password doors (see rate limits).

Any path under /v1 that matches no route answers as the API rather than falling through to the console: E_NOT_FOUND with no such endpoint: {path} and the hint Check the method too: several /v1/admin routes are POST-only.

Discovery#

Three routes answer what is this Station and what may I do here. Start with them: a scoped key has no master index, so roots is how a client learns where it may begin.

Health#

curl -s https://station.example.com/v1/health

{
  "status": "ok",
  "mode": "registry",
  "writable": true,
  "setup_required": false,
  "password_login": true
}

mode is registry when the Station hosts many forests under a root, single when it serves one. setup_required and password_login say which pre-identity screen a console should render. They reveal that a door exists, never who may walk through it.

Who am I#

curl -s https://station.example.com/v1/me \
  -H "Authorization: Bearer $MONKEYLLM_KEY"

{
  "principal": "reporting-bot",
  "grants": [
    {
      "forest": "handbook",
      "caps": ["ingest", "read"],
      "allow": ["policies/"],
      "deny": ["policies/legal-hold/"],
      "tables": {},
      "roots": ["policies/_index"]
    }
  ],
  "admin": false,
  "owner": false
}

For the owner there is no grant table to read, the authority is a bit, so every forest the pool currently holds is projected as a full-capability grant. When the key carries a capability mask, the caps reported here are the masked ones: what a console renders from this is what the key can actually do.

List forests#

curl -s https://station.example.com/v1/forests \
  -H "Authorization: Bearer $MONKEYLLM_KEY"

{
  "forests": [
    {
      "id": "handbook",
      "active": true,
      "caps": ["ingest", "read"],
      "roots": ["policies/_index"]
    }
  ],
  "mode": "registry"
}

active says the forest is already open in the pool. roots is ["_index"] for an unrestricted grant, and one {prefix}/_index per allowed subtree otherwise: there is no implicit grant on the ancestors of a granted subtree, because the master index names every branch in the forest.

Forest primitives#

One route shape covers every call. POST the arguments as a JSON object to the primitive name, under the forest:

POST /v1/forests/{forest}/{primitive}

The names this route serves:

Any other name answers 404 with no such endpoint: {name} and a hint listing the served set. Two extras apply to every call on this route:

• hybrid (boolean, default false) turns on hybrid entry search for this call, fusing the vector index with BM25. It is consumed by the host, never passed to the primitive, and it is reset on every call rather than left over from the last one.
• A Server-Timing response header carries the host clocks, in milliseconds. It is emitted for refusals too, because how long a 403 took is not a fact about the forest behind it.
  httpCopy

  Server-Timing: vine;dur=62.4, model;dur=1840.2, cache;dur=1.8, host;dur=9.1

  vine is the engine, model the provider round trip when there was one, cache the answer store when it was consulted, and host whatever is left: policy, the audit record, serialisation and the thread hop.

locate#

curl -sX POST https://station.example.com/v1/forests/handbook/locate \
  -H "Authorization: Bearer $MONKEYLLM_KEY" \
  -H 'content-type: application/json' \
  -d '{"query": "expense reimbursement", "k": 3, "scope": "bananas"}'

import httpx

STATION = "https://station.example.com"
KEY = "mk_..."

def call(forest: str, primitive: str, **body):
    r = httpx.post(
        f"{STATION}/v1/forests/{forest}/{primitive}",
        headers={"Authorization": f"Bearer {KEY}"},
        json=body,
        timeout=180.0,
    )
    payload = r.json()
    if "error" in payload:
        err = payload["error"]
        raise RuntimeError(f"{err['code']}: {err['message']}")
    return payload

hits = call("handbook", "locate", query="expense reimbursement", k=3,
            scope="bananas")
for hit in hits["results"]:
    print(hit["score"], hit["id"], "-", hit["summary"])

const STATION = 'https://station.example.com';
const KEY = process.env.MONKEYLLM_KEY!;

type VineError = { error: { code: string; message: string; hint?: string } };

async function call<T>(
  forest: string,
  primitive: string,
  body: Record<string, unknown> = {},
): Promise<T> {
  const res = await fetch(`${STATION}/v1/forests/${forest}/${primitive}`, {
    method: 'POST',
    headers: {
      authorization: `Bearer ${KEY}`,
      'content-type': 'application/json',
    },
    body: JSON.stringify(body),
  });
  const payload = (await res.json()) as T | VineError;
  if (payload && typeof payload === 'object' && 'error' in payload) {
    const { code, message } = (payload as VineError).error;
    throw new Error(`${code}: ${message}`);
  }
  return payload as T;
}

const hits = await call<{
  results: { id: string; score: number; summary: string }[];
  truncated: boolean;
}>('handbook', 'locate', {
  query: 'expense reimbursement',
  k: 3,
  scope: 'bananas',
});

{
  "results": [
    {
      "id": "policies/expenses",
      "kind": "banana",
      "type": "note",
      "title": "Expense policy",
      "summary": "What the company reimburses, the receipt rule and the limits per category.",
      "trail": ["_index", "policies/_index"],
      "score": 1.2841,
      "heat": 0.34
    },
    {
      "id": "policies/travel",
      "kind": "banana",
      "type": "note",
      "title": "Travel booking",
      "summary": "How to book flights and hotels, and which fares need approval.",
      "trail": ["_index", "policies/_index"],
      "score": 0.7712,
      "heat": 0.05
    }
  ],
  "truncated": false
}

trail is the ancestor chain, filtered to what the key may see. heat is accumulated pheromone: successful hunts reinforce the nodes they used, so a corpus that is used becomes cheaper to navigate. Branch results also carry coverage, a one-line count of what is under them.

look#

curl -sX POST https://station.example.com/v1/forests/handbook/look \
  -H "Authorization: Bearer $MONKEYLLM_KEY" \
  -H 'content-type: application/json' \
  -d '{"id": "policies/expenses"}'

{
  "id": "policies/expenses",
  "type": "note",
  "title": "Expense policy",
  "summary": "What the company reimburses, the receipt rule and the limits per category.",
  "tags": ["finance", "policy"],
  "confidence": 0.9,
  "updated": "2026-07-30",
  "edges_out": [
    {
      "rel": "related-to",
      "target": "policies/travel",
      "target_summary": "How to book flights and hotels, and which fares need approval."
    }
  ],
  "edges_in": [
    { "rel": "mentions", "source": "policies/onboarding" }
  ],
  "outline": ["Limits", "Receipts", "Approvals"],
  "stats": { "body_tokens": 812, "degree": 2, "heat": 0.34 }
}

The digest changes shape with the node:

• A branch carries children, coverage and, when the index declares them, cross_trails.
• A banana carries outline, the list of its section headers.
• A dataset additionally carries query_manual (tables, columns and example queries), sample_rows and the operator notes in notes. This is the path an agent takes before running SQL.

edges_out and edges_in are capped at 12 each and ordered by the heat of the node on the other end. If the digest still exceeds its 500-token budget, sample_rows is dropped and truncated: true appears.

move#

curl -sX POST https://station.example.com/v1/forests/handbook/move \
  -H "Authorization: Bearer $MONKEYLLM_KEY" \
  -H 'content-type: application/json' \
  -d '{"id": "policies/_index", "rel": "children"}'

{
  "neighbors": [
    {
      "id": "policies/expenses",
      "rel": "children",
      "direction": "out",
      "type": "note",
      "summary": "What the company reimburses, the receipt rule and the limits per category.",
      "heat": 0.34
    },
    {
      "id": "policies/travel",
      "rel": "children",
      "direction": "out",
      "type": "note",
      "summary": "How to book flights and hotels, and which fares need approval.",
      "heat": 0.05
    }
  ],
  "truncated": false
}

pick#

curl -sX POST https://station.example.com/v1/forests/handbook/pick \
  -H "Authorization: Bearer $MONKEYLLM_KEY" \
  -H 'content-type: application/json' \
  -d '{"id": "policies/expenses", "section": "Receipts"}'

{
  "id": "policies/expenses",
  "title": "Expense policy",
  "section": "Receipts",
  "body": "## Receipts\n\nAny single item over 25 EUR needs a receipt...",
  "body_tokens": 148,
  "truncated": false
}

A body over 4000 tokens is never silently cut. Instead the call answers the outline plus a hint, so the caller can ask for one section:

{
  "id": "policies/handbook-full",
  "title": "The whole handbook",
  "outline": ["Limits", "Receipts", "Approvals", "Appeals"],
  "body_tokens": 9120,
  "truncated": true,
  "hint": "Body exceeds 4000 tokens. Use section=<header> to harvest one section."
}

scan#

curl -sX POST https://station.example.com/v1/forests/handbook/scan \
  -H "Authorization: Bearer $MONKEYLLM_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "parent_id": "policies/_index",
    "filter": {"type": "note", "updated_after": "2026-01-01"},
    "fields": ["id", "title", "updated"],
    "recursive": true,
    "limit": 25
  }'

{
  "nodes": [
    { "id": "policies/expenses", "title": "Expense policy", "updated": "2026-07-30" },
    { "id": "policies/travel", "title": "Travel booking", "updated": "2026-03-02" }
  ],
  "truncated": false
}

sniff#

curl -sX POST https://station.example.com/v1/forests/handbook/sniff \
  -H "Authorization: Bearer $MONKEYLLM_KEY" \
  -H 'content-type: application/json' \
  -d '{"terms": ["INV-1045", "reimbursement"], "scope": "policies", "k": 5}'

{
  "results": [
    {
      "id": "policies/expenses",
      "type": "note",
      "title": "Expense policy",
      "trail": ["_index", "policies/_index"],
      "score": 1.34,
      "heat": 0.34,
      "match_count": 2,
      "truncated_matches": false,
      "matches": [
        {
          "section": "Receipts",
          "line": 42,
          "snippet": "...the disputed invoice INV-1045 was reimbursed in full after..."
        }
      ]
    }
  ],
  "scanned_nodes": 37,
  "truncated": false
}

Each result carries at most 3 matches, with truncated_matches saying when there were more. scanned_nodes counts the bodies that were opened, and for a scoped key it is recomputed from what that key can see, so it is never a measurement of the forest's real size.

harvest#

This is the call for a client that brings its own model. It runs locate and sniff, fuses the two rankings, and returns each winner with the full body when it fits or the matched sections when it does not, always with exact snippets and the trail. Your model decides what to do next.

curl -sX POST https://station.example.com/v1/forests/handbook/harvest \
  -H "Authorization: Bearer $MONKEYLLM_KEY" \
  -H 'content-type: application/json' \
  -d '{"query": "what is our expense policy?", "terms": ["receipt"], "k": 3}'

{
  "query": "what is our expense policy?",
  "terms": ["receipt"],
  "results": [
    {
      "id": "policies/expenses",
      "title": "Expense policy",
      "type": "note",
      "trail": ["_index", "policies/_index"],
      "summary": "What the company reimburses, the receipt rule and the limits per category.",
      "score": 0.0328,
      "found_by": ["locate", "sniff"],
      "matches": [
        {
          "section": "Receipts",
          "line": 40,
          "snippet": "...any single item over 25 EUR needs a receipt attached..."
        }
      ],
      "content": [
        {
          "section": null,
          "body": "# Expense policy\n\n## Limits\n...",
          "body_tokens": 812
        }
      ]
    }
  ],
  "truncated": false,
  "trace": {
    "steps": [
      { "step": "locate", "ms": 11.4, "tokens": 320 },
      { "step": "sniff", "ms": 47.9, "tokens": 260 },
      { "step": "pick", "ms": 3.1, "tokens": 812, "id": "policies/expenses" }
    ],
    "retrieval_ms": 62.4,
    "total_ms": 62.4
  }
}

found_by says which half of the sweep found the node, and content is either one entry with the whole body, up to two matched sections, or the outline when the body is large and no section could be attributed. Dataset results additionally carry notes, because what a person wrote about how to read the data should not depend on whether the question happened to match it. Results are dropped whole from the tail to fit the 4000-token budget, never sliced mid-body.

answer#

The one call that replaces a knowledge-base lookup plus a summarisation round trip. The model only ever sees material the principal could already read, so binding a model cannot become a way around the policy. It needs a model bound to the answer role for this forest; without one it answers E_SCHEMA and tells you where to bind it.

curl -sX POST https://station.example.com/v1/forests/handbook/answer \
  -H "Authorization: Bearer $MONKEYLLM_KEY" \
  -H 'content-type: application/json' \
  -d '{"question": "what is our expense policy?", "k": 3}'

import httpx

STATION = "https://station.example.com"
KEY = "mk_..."

r = httpx.post(
    f"{STATION}/v1/forests/handbook/answer",
    headers={"Authorization": f"Bearer {KEY}"},
    json={"question": "what is our expense policy?", "k": 3},
    timeout=180.0,          # a provider round trip lives inside this call
)
payload = r.json()

if "error" in payload:
    raise RuntimeError(payload["error"]["message"])

print(payload["answer"])
print("grounded in:", payload["evidence"])
print("server timing:", r.headers.get("server-timing"))

const res = await fetch(
  'https://station.example.com/v1/forests/handbook/answer',
  {
    method: 'POST',
    headers: {
      authorization: `Bearer ${process.env.MONKEYLLM_KEY}`,
      'content-type': 'application/json',
    },
    body: JSON.stringify({ question: 'what is our expense policy?', k: 3 }),
  },
);

type Answer = {
  answer: string;
  model: string;
  evidence: string[];
  sources: { id: string; title: string; summary: string; type: string }[];
  cached?: boolean;
};

const payload = (await res.json()) as Answer;
console.log(payload.answer, payload.evidence);
console.log(res.headers.get('server-timing'));

{
  "answer": "Anything over 25 EUR needs a receipt, and travel over 500 EUR needs your manager's approval before booking.",
  "model": "qwen3:14b",
  "model_ms": 1840.2,
  "usage": { "prompt": 2914, "completion": 84, "calls": 1 },
  "evidence": ["policies/expenses", "policies/travel"],
  "sources": [
    {
      "id": "policies/expenses",
      "title": "Expense policy",
      "summary": "What the company reimburses, the receipt rule and the limits per category.",
      "type": "note"
    }
  ],
  "harvest": { "query": "what is our expense policy?", "results": [] },
  "trace": {
    "steps": [
      { "step": "locate", "ms": 11.4, "tokens": 320 },
      { "step": "sniff", "ms": 47.9, "tokens": 260 },
      { "step": "model", "ms": 1840.2, "detail": "qwen3:14b" }
    ],
    "retrieval_ms": 62.4,
    "total_ms": 1902.6
  },
  "cost": {
    "prompt_tokens": 2914,
    "completion_tokens": 84,
    "calls": 1,
    "priced": false
  }
}

evidence is the list of node ids the answer stands on, in rank order, and sources is the same list with enough metadata to render a citation. harvest is the whole retrieval bundle the model read, so you can show your user exactly what grounded the answer. cost appears when a provider actually ran; priced: false means the provider publishes usage but no rates, which is reported as not priced rather than as free.

A repeat of a question may be served from the forest's answer store. A hit is labelled and carries no model_ms and no trace, because no provider ran:

{
  "answer": "Anything over 25 EUR needs a receipt, and travel over 500 EUR needs your manager's approval before booking.",
  "model": "qwen3:14b",
  "usage": { "prompt": 2914, "completion": 84, "calls": 1 },
  "cached": true,
  "cached_at": "2026-08-15T08:12:44+00:00",
  "evidence": ["policies/expenses", "policies/travel"],
  "sources": [],
  "harvest": { "query": "what is our expense policy?", "results": [] }
}

query#

curl -sX POST https://station.example.com/v1/forests/handbook/query \
  -H "Authorization: Bearer $MONKEYLLM_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "id": "finance/ledger-2026",
    "sql": "SELECT month, SUM(amount) AS total FROM entries GROUP BY month"
  }'

{
  "columns": ["month", "total"],
  "rows": [
    ["2026-01", 481200.55],
    ["2026-02", 512844.10]
  ],
  "row_count": 2,
  "limited": false,
  "elapsed_ms": 3.71
}

A statement with no LIMIT gets LIMIT 200 appended, and limited: true says the cap was reached. Execution is capped at 2 seconds, past which the call answers E_TIMEOUT. A mistyped table or column answers E_QUERY_INVALID with the real names in the hint, so a generated query can correct itself without spending a look. When the grant pins tables for this dataset, naming any other table answers E_FORBIDDEN.

plant#

curl -sX POST https://station.example.com/v1/forests/handbook/plant \
  -H "Authorization: Bearer $MONKEYLLM_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "node": {
      "id": "policies/per-diem",
      "parent": "policies/_index",
      "type": "note",
      "title": "Per diem rates",
      "summary": "Daily allowance per country and what it is meant to cover.",
      "tags": ["finance"],
      "body": "# Per diem rates\n\n## Europe\n55 EUR per day."
    }
  }'

{
  "id": "policies/per-diem",
  "commit": "4f1b0c9a8d2e6b3705c1f4a9e8d7b6c5a4930f21",
  "trail": ["_index", "policies/_index"]
}

A write outside the grant is refused as E_FORBIDDEN, not as not-found: the caller supplied the id, so nothing is disclosed by saying so. The commit is stamped with the acting principal, and commit in the response is that stamped sha.

graft#

curl -sX POST https://station.example.com/v1/forests/handbook/graft \
  -H "Authorization: Bearer $MONKEYLLM_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "id": "policies/per-diem",
    "patch": {
      "set_frontmatter": {"summary": "Daily allowance per country, updated for 2027."},
      "add_links": [{"rel": "related-to", "target": "policies/expenses"}],
      "append_section": {"header": "Asia", "body": "70 EUR per day."}
    }
  }'

{
  "id": "policies/per-diem",
  "commit": "9c2d7e5b1a0f8364d5e2c7b9a1e0f8364d5e2c7b",
  "fortified": [{ "rel": "related-to", "target": "policies/expenses" }],
  "trail": ["_index", "policies/_index"]
}

Two rules the patch validator enforces: replace_body cannot be combined with section operations (send the whole body, or section patches, not both), and an index node's body is the indexer's render, so an index accepts section operations only. fortified lists the links that already existed and were reinforced rather than duplicated.

tend#

curl -sX POST https://station.example.com/v1/forests/handbook/tend \
  -H "Authorization: Bearer $MONKEYLLM_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "id": "finance/ledger-2026",
    "sql": "UPDATE entries SET amount = 1290.00 WHERE id = 4471"
  }'

{
  "id": "finance/ledger-2026",
  "rows_affected": 1,
  "payload_hash": "b71d0f4c8a2e59637d1c0b8f4a2e5963d7c1b0f8a4e2596371d0c8b4f2a0e5963",
  "commit": "7a3e1c0b9d8f2465e3c1a0b9d8f24657e3c1a0b9",
  "elapsed_ms": 2.14
}

The binary never enters git. What is committed is the node's .md carrying the new payload_hash, which is the audit reference for the change.

curate#

curl -sX POST https://station.example.com/v1/forests/handbook/curate \
  -H "Authorization: Bearer $MONKEYLLM_KEY" \
  -H 'content-type: application/json' \
  -d '{"id": "policies/per-diem"}'

{
  "id": "policies/per-diem",
  "model": "qwen3:14b",
  "before": "Daily allowance per country, updated for 2027.",
  "after": "Per diem rates by region: 55 EUR in Europe, 70 EUR in Asia, covering meals and local transport.",
  "tags": ["finance", "travel"]
}

The reply is a proposal for a human or a caller to apply with graft. The curator validates the model against the summary contract and retries, so a model that writes a 200-token summary is corrected rather than trusted.

Ingestion#

curl -sX POST https://station.example.com/v1/forests/handbook/ingest \
  -H "Authorization: Bearer $MONKEYLLM_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "mode": "upload",
    "dest": "policies",
    "files": [
      {"name": "per-diem.md", "text": "# Per diem\n\n55 EUR per day in Europe."},
      {"name": "handbook.docx", "b64": "UEsDBBQABgAIAAAAIQ..."}
    ]
  }'

HTTP/1.1 202 Accepted

{
  "job": {
    "id": "ing-4b7f21ac",
    "forest": "handbook",
    "mode": "upload",
    "state": "running",
    "done": 0,
    "total": 2,
    "current": null,
    "stage": null,
    "errors": 0,
    "started": "2026-08-15T09:41:12Z"
  }
}

Batches run as jobs. One batch per forest at a time: a second one while the first is running answers 409, naming the job you can watch or cancel.

HTTP/1.1 409 Conflict

{
  "error": {
    "code": "E_LOCKED",
    "message": "an ingest job is already running on this forest: ing-4b7f21ac",
    "hint": "Watch it under GET /v1/forests/{forest}/jobs, cancel it, or wait for it to finish."
  }
}

{
  "source": "/srv/documents/handbook",
  "can_sync": true,
  "host_paths": true
}

source is the root a prior adopt recorded, can_sync says that root is still inside the ingest roots this Station may read, and host_paths says whether mirroring a host folder is offered at all. A console that offers a sync button without reading this is offering a button whose scope is invisible.

Ingest jobs#

A job is process state, never forest content, so reading one touches no forest: no lane, no trace event, no pheromone. That is what keeps polling free while a batch runs. All three routes require the ingest capability, on the reasoning that whoever could have started the batch may watch it.

{
  "job": {
    "id": "ing-4b7f21ac",
    "forest": "handbook",
    "mode": "upload",
    "state": "done",
    "done": 2,
    "total": 2,
    "current": null,
    "stage": null,
    "errors": 0,
    "started": "2026-08-15T09:41:12Z",
    "finished": "2026-08-15T09:41:29Z",
    "report": {
      "planted": ["policies/per-diem", "policies/handbook"],
      "branches": ["policies/_index"],
      "updated": [],
      "unchanged": [],
      "stale": [],
      "unsupported": [],
      "errors": [],
      "mode": "upload",
      "staged": ["per-diem.md", "handbook.docx"],
      "rollup": null,
      "commit": "b2c9e7a1d0f83546c9b2e7a1d0f83546c9b2e7a1",
      "commit_before": "a1b8d6c0f9e72435b8a1d6c0f9e72435b8a1d6c0",
      "curated": true,
      "bound": true,
      "curation": { "llm_summaries": 2, "branch_rollups": 1 }
    }
  }
}

Map projections#

Two GET routes hand back a whole region in one payload, under the caller's own policy. They are not primitives and grant nothing new: every id they return is one the same principal could reach through look. What they add is shape, which a per-node walk cannot give without asking once per node.

curl -s "https://station.example.com/v1/forests/handbook/graph?scope=policies&limit=500" \
  -H "Authorization: Bearer $MONKEYLLM_KEY"

{
  "nodes": [
    {
      "id": "policies/expenses",
      "kind": "banana",
      "type": "note",
      "title": "Expense policy",
      "summary": "What the company reimburses, the receipt rule and the limits per category.",
      "tags": ["finance", "policy"],
      "parent": "policies/_index",
      "coverage": null,
      "body_tokens": 812,
      "payload": null,
      "payload_type": null,
      "created": "2026-02-11",
      "updated": "2026-07-30",
      "degree": 2,
      "heat": 0.34
    }
  ],
  "edges": [
    {
      "src": "policies/expenses",
      "rel": "related-to",
      "dst": "policies/travel",
      "confidence": 1.0
    }
  ],
  "truncated": false,
  "types": ["dataset", "entity", "media", "note"],
  "rels": ["part-of", "related-to", "succeeds"],
  "derived": true
}

An edge needs both ends visible, because one visible end discloses the other, and degree is recomputed from the edges that survived rather than read off the catalog. When the node count exceeds the limit, the most connected nodes are kept, ranked over the in-scope edge set only, and truncated: true says so. types and rels are the dialect this forest declares, so a legend names what the forest actually holds.

{
  "heat": [
    { "id": "policies/expenses", "heat": 0.34 },
    { "id": "policies/travel", "heat": 0.05 }
  ],
  "stats": { "rows": 2, "max": 0.34, "mean": 0.195 },
  "truncated": false,
  "derived": true
}

Payload bytes#

This is a human surface: the console shows the screenshot, the browser saves the database. The node id goes into the path as-is, slashes included. It is served by a read-only Station too, because it writes nothing.

curl -s -o screenshot.png -D - \
  "https://station.example.com/v1/forests/handbook/payload/media/onboarding-screenshot" \
  -H "Authorization: Bearer $MONKEYLLM_KEY"

HTTP/1.1 200 OK
content-type: image/png
content-length: 184223
cache-control: private
etag: 7c1e0b9a4d2f8365...

<binary image bytes>

ETag is the passport's own payload_hash, and If-None-Match is honoured with a 304, so a client that cached the bytes revalidates against the map instead of downloading again. Four situations answer the same 404 node not found: the node is out of scope, the node does not exist, it has no payload, or the map claims bytes the disk does not have. A remote payload is refused with E_SCHEMA rather than fetched, because a network dependency does not belong inside a read.

Administration#

The console needs a surface, not a side channel, so governance is ordinary REST. Every route below requires admin, and where a forest is named, admin on that forest. Two rules run through all of them: a principal only ever sees governance data for forests they administer, and minting or revoking a credential requires admin on every forest that principal holds.

The four below are the path from an empty Station to a forest an agent can answer from: create the forest, put the people on it, declare where a model lives, and bind a model to a role. The rest of the table is covered under the remaining admin routes.

Create a forest#

Creation is init_forest and nothing else, so what this produces is byte-identical to what vine init produces on the same machine. The Station adds no second way to make a forest. Authority is admin on an existing forest, or the owner bit, which is the only authority an empty registry can offer. On success the caller is granted every capability on the new forest, because a forest nobody can open is a silent failure with a 200.

curl -sX POST https://station.example.com/v1/admin/forests \
  -H "Authorization: Bearer $MONKEYLLM_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "id": "handbook",
    "title": "Company handbook",
    "summary": "Policies, onboarding and the support playbook."
  }'

{
  "forest": {
    "id": "handbook",
    "title": "Company handbook",
    "commit": "4f1c2a9e7b30d5482c1a9e7b30d5482c1a9e7b30"
  },
  "grants": [
    {
      "forest": "handbook",
      "caps": ["admin", "ingest", "query", "read", "tend", "write"],
      "allow": [""],
      "deny": [],
      "tables": {}
    }
  ]
}

People#

Governance shaped like a person rather than like the tables. Grants, passwords and keys are three tables and one thought, so this route applies any combination in one request and the console asks once.

It is a composite, never a new authority. The steps run in a fixed order (grant, revoke access, password, issue key, revoke keys), each re-checks the rule that already governed it, and a step you may not perform is refused without abandoning the ones you may: half a submitted form dropped in silence is worse than either doing it or failing it. Steps that landed come back in applied, the rest in refused with a reason and, for a multi-forest grant, the forest id. The status is 200 whenever anything at all was applied, and 403 only when nothing was.

curl -sX POST https://station.example.com/v1/admin/people \
  -H "Authorization: Bearer $MONKEYLLM_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "principal": "support-bot",
    "grant": {
      "forests": ["handbook", "tickets"],
      "caps": ["read", "query"],
      "allow": ["support/"],
      "deny": ["support/legal-hold/"]
    },
    "issue_key": {"label": "support-bot ci", "expires_in_days": 90}
  }'

{
  "principal": "support-bot",
  "applied": ["grant", "issue_key"],
  "refused": [
    {
      "step": "grant",
      "message": "you do not administer 'tickets'",
      "hint": null,
      "forest": "tickets"
    }
  ],
  "api_key": "mk_L8pQ2vN5wR0kJ7yTcXhBmA4sZfEuD1gOi3rYtV6bNqe"
}

On GET, each person carries manageable: false means you administer some of their forests but not all, so their tokens array comes back empty. You can see the person; you cannot touch their credentials.

Providers#

A provider is any OpenAI-compatible /v1: OpenRouter, LiteLLM, vLLM, a local llama.cpp. The key is write-only. It goes in on a POST and never comes back out, so GET reports has_key and nothing more.

curl -sX POST https://station.example.com/v1/admin/providers \
  -H "Authorization: Bearer $MONKEYLLM_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "name": "local",
    "endpoint": "http://llama:8090/v1",
    "api_key": ""
  }'

{
  "providers": [
    {
      "name": "local",
      "endpoint": "http://llama:8090/v1",
      "has_key": false,
      "origin": "console",
      "created": "2026-08-15T09:41:12+00:00"
    }
  ]
}

Send name to test a stored provider, or endpoint and api_key to test one before declaring it. Prices come back when the provider states them; a local Ollama or llama.cpp states none, and silence is reported as silence rather than as zero.

{
  "ok": true,
  "count": 2,
  "models": [
    { "id": "qwen3-30b-a3b", "name": null,
      "prompt": null, "completion": null, "context": 32768 },
    { "id": "qwen3-embedding-0.6b", "name": null,
      "prompt": null, "completion": null, "context": 8192 }
  ]
}

Model bindings#

A binding says which model plays which role for one forest. The four roles are ingest (curation summaries), answer, vision and embed. An unbound role is not an error: the stage it drives is simply skipped, so a forest with no ingest binding adopts with mechanical summaries and a forest with no answer binding refuses POST /v1/forests/{forest}/answer.

curl -sX POST https://station.example.com/v1/admin/models \
  -H "Authorization: Bearer $MONKEYLLM_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "forest": "handbook",
    "role": "answer",
    "provider": "local",
    "model": "qwen3-30b-a3b",
    "max_tokens": 600,
    "reasoning": "off"
  }'

{
  "bindings": [
    {
      "forest": "handbook",
      "role": "answer",
      "provider": "local",
      "model": "qwen3-30b-a3b",
      "max_tokens": 600,
      "reasoning": "off"
    },
    {
      "forest": "handbook",
      "role": "ingest",
      "provider": "local",
      "model": "qwen3-30b-a3b",
      "max_tokens": 600,
      "reasoning": "off"
    }
  ]
}

Granting access#

curl -sX POST https://station.example.com/v1/admin/grant \
  -H "Authorization: Bearer $MONKEYLLM_KEY" \
  -H 'content-type: application/json' \
  -d '{
    "principal": "reporting-bot",
    "forest": "handbook",
    "caps": ["read", "query"],
    "allow": ["policies/"],
    "deny": ["policies/legal-hold/"],
    "tables": {"finance/ledger-2026": ["entries"]},
    "issue_key": true
  }'

{
  "principal": "reporting-bot",
  "grants": [
    {
      "forest": "handbook",
      "caps": ["query", "read"],
      "allow": ["policies/"],
      "deny": ["policies/legal-hold/"],
      "tables": { "finance/ledger-2026": ["entries"] }
    }
  ],
  "api_key": "mk_L8pQ2vN5wR0kJ7yTcXhBmA4sZfEuD1gOi3rYtV6bNqe"
}

An unknown capability answers E_SCHEMA naming it. allow and deny are branch prefixes and are normalised with a trailing slash on the way in. tables maps a dataset node id to the tables the principal may name in SQL.

Reading the audit log#

curl -s "https://station.example.com/v1/admin/audit?limit=50&principal=reporting-bot" \
  -H "Authorization: Bearer $MONKEYLLM_KEY"

{
  "entries": [
    {
      "ts": "2026-08-15T09:41:12+00:00",
      "principal": "reporting-bot",
      "forest": "handbook",
      "primitive": "answer",
      "args": "{\"question\": \"what is our expense policy?\", \"k\": \"3\"}",
      "result": "ok",
      "size": 4821,
      "commit_sha": null
    }
  ]
}

Arguments are digested, never stored verbatim: any value over 80 characters becomes <n chars>. The log records who read what, not the content they read. Writes additionally carry commit_sha, and every write commit inside the forest is stamped with the acting principal, so which agent read which nodes in which order is reconstructible after the fact.

The remaining admin routes#

The rest of the table above are operational rather than structural, and they share one shape: GET reads the current state, POST changes it and answers with the same object the GET would have returned, so a console never has to re-fetch.

• GET /v1/admin/principals and GET /v1/admin/keys are the read side of /v1/admin/people, split by table for a console that wants one or the other. POST /v1/admin/keys mints and revokes under the same whole-person rule.
• POST /v1/admin/password sets or clears one principal's console password, again whole-person.
• GET /v1/admin/health?forest=<id> relays the Ranger's report for one forest. It needs an admin grant that is not limited to a branch, because the report counts lint errors and names nodes everywhere: a scoped principal served a filtered version would be reading numbers that quietly describe nodes they may not see. GET /v1/health is the unauthenticated liveness check and is not this route.
• GET, POST /v1/admin/canopy and GET, POST /v1/admin/cache read and change the optional vector layer and the answer cache for one forest. Building the Canopy re-embeds every summary and the caller waits, deliberately: a fire-and-forget build would leave the console unable to say whether the index it is about to rely on exists.
• POST /v1/admin/reindex rebuilds _derived/catalog.db from the files. It is offered by a read-only Station too, because _derived/ is not the content: rebuilding it plants nothing and commits nothing.
• The three /v1/admin/snapshots routes are owner-only, for the reason given in the table: a bundle is the whole forest with its whole history, so every branch scope collapses the moment the bytes leave.

Budgets, truncation and rate limits#

There is no cursor pagination anywhere in this API, and that is deliberate. Every read answers within a declared token budget, and a cut result always says truncated: true. A caller that sees it should ask narrower, not retry harder.

Other bounds worth knowing:

• Map projections default to 2000 rows and cap at 10000.
• The audit log caps limit at 500.
• Job records keep the 20 most recent per forest.
• The MCP view tool refuses images over 6 MiB. The payload route has no such bound.

Rate limits#

There is no rate limit on key-authenticated routes. The two password doors, /v1/auth/login and /v1/auth/pair, share one fixed-window counter: 5 failures per 60 seconds per combination of username and client host. Past the limit the answer costs no password comparison at all:

HTTP/1.1 429 Too Many Requests

{
  "error": {
    "code": "E_FORBIDDEN",
    "message": "too many attempts; try again shortly"
  }
}

The same message appears whether the username exists or not, so the limiter cannot become the directory the login refusal already refuses to be. A successful sign-in clears the window. The counter lives in process, so a restart forgets it.

Next steps#