Agent integration

The shape of it

An agent edits a doc in one POST:

curl -X POST https://app.geoff.ai/api/docs/$DOC_ID/agent-edit \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"instruction":"Add a \"Risks\" section with 3 bullet items."}'

Response on success:

{
  "commitCid": "baf...",
  "bytesEncrypted": 412,
  "tokensUsed": { "input": 1847, "output": 134 },
  "diffBytes": 290
}

The server fetches the current markdown, runs an LLM call as the doc owner to produce the edited markdown, encrypts it, pushes a new rack commit, and returns the new commit CID + the raw token counts that were billed to the owner.

Getting a token

Only the doc owner can mint agent tokens. From the owner’s browser:

curl -X POST https://app.geoff.ai/api/docs/$DOC_ID/members \
  -H "Content-Type: application/json" -b cookie-jar.txt \
  -d '{
        "subjectType": "agent",
        "subjectId": "my-assistant",
        "role": "editor",
        "label": "Launch checklist helper"
      }'

Response:

{
  "member": { "id": "...", "subjectType": "agent", "role": "editor", ... },
  "agentToken": "eyJhbGciOi..."
}

The agentToken is shown exactly once. Paste it into the agent’s config and treat it like an API key — it carries the agent’s edit scope and nothing else.

Agents get a strict cap by default: 20 edits/day and 70 000 tokens/day (50 k input + 20 k output). The owner can override both at invite time via dailyEditCap and dailyTokenCap.

Billing

1x metering invariant. The owner is billed the exact token count StackNet reports (input_tokens + output_tokens), with no multiplier for the encryption overhead. Encrypted and plaintext docs cost identically for the same LLM work.
Per-agent daily caps, per-doc global caps, and short-window burst limits (5 edits / 60 s per agent-doc pair) all enforce before any LLM call.
See Billing for details.

Revocation & rotation

Owner revokes by member id:

curl -X DELETE -b cookie-jar.txt \
  https://app.geoff.ai/api/docs/$DOC_ID/members/$MEMBER_ID

Effective immediately — the next agent-edit call with the revoked token returns 403 forbidden:document "Agent grant revoked". The JWT signature alone is not sufficient: every request re-checks DocMember.revokedAt in the DB. To rotate a compromised token: revoke + re-invite. The new invite gets a fresh jti and a fresh JWT.

Failure modes, by status code

Status	Meaning	Common cause
`401`	Missing or malformed `Authorization: Bearer <jwt>`	Client didn’t send the token
`403 forbidden:document`	Token scoped to wrong doc, wrong role, revoked, or blocked by the injection filter	Audit the returned message
`402 payment_required:document`	Owner delegation expired	Ask the owner to sign in and touch the doc; see Delegation expiry
`429 rate_limit:document`	Daily edit cap, daily token cap, doc-wide cap, or 60-second burst cap hit	Server log has `[agent-edit] cap_hit reason=…` with exact `used/cap` numbers
`400 bad_request:document`	Empty or oversize instruction (> 32 KB)	Trim the instruction
`403 forbidden:document` + diff cap	Edit produced > 16 KB of changed markdown	Split the edit into multiple calls

Prompt-injection filter

The agent-edit endpoint runs a short-list regex filter on the instruction before calling StackNet. Current rules reject known exfil patterns (override-instructions, reveal-system-prompt, exfil-secrets, role-flip, tool-abuse) and log every hit. This is a bounded-damage defense, not prevention. The real money- preserving defense is the per-agent daily token cap. Don’t design around the filter — design around the cap.

Delegation expiry

Agent edits require a valid StackAuth JWT for the doc owner, captured at doc-create time (or on the owner’s next edit). StackAuth JWTs expire. When the captured JWT’s exp has passed, agent edits fail with 402 payment_required:document. Recovery: the owner signs in and touches the doc once (any PATCH). Their fresh session JWT is captured and re-wrapped, unblocking agents. A dedicated “refresh delegation” endpoint is on the roadmap so the owner doesn’t need to make a content edit.

End-to-end example

bash walkthrough: owner mints → agent edits → owner revokes

# 1. Owner (cookie-authed) creates the doc
DOC_ID=$(curl -sS -b cookie.jar -X POST https://app.geoff.ai/api/docs \
  -H "Content-Type: application/json" \
  -d '{"title":"Launch checklist","content":"# Launch\n\n- [ ] pick a date\n- [ ] book venue\n"}' \
  | jq -r .id)

# 2. Owner invites an agent
AGENT_TOKEN=$(curl -sS -b cookie.jar -X POST \
  https://app.geoff.ai/api/docs/$DOC_ID/members \
  -H "Content-Type: application/json" \
  -d '{"subjectType":"agent","subjectId":"ops-bot","role":"editor","label":"Ops bot"}' \
  | jq -r .agentToken)

# 3. Agent runs an edit
curl -sS -X POST https://app.geoff.ai/api/docs/$DOC_ID/agent-edit \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"instruction":"Add a Risks section with 3 bullet items.","message":"risks"}'

# 4. Owner inspects usage
curl -sS -b cookie.jar https://app.geoff.ai/api/docs/$DOC_ID/usage | jq .

# 5. Owner revokes
MEMBER_ID=$(curl -sS -b cookie.jar \
  https://app.geoff.ai/api/docs/$DOC_ID/members \
  | jq -r '.members[] | select(.subjectId == "ops-bot").id')
curl -sS -X DELETE -b cookie.jar \
  https://app.geoff.ai/api/docs/$DOC_ID/members/$MEMBER_ID

Getting Started

MCP Server

Platform Features

Geoff Docs

The shape of it

Getting a token

Billing

Revocation & rotation

Failure modes, by status code

Prompt-injection filter

Delegation expiry

End-to-end example

​The shape of it

​Getting a token

​Billing

​Revocation & rotation

​Failure modes, by status code

​Prompt-injection filter

​Delegation expiry

​End-to-end example

The shape of it

Getting a token

Billing

Revocation & rotation

Failure modes, by status code

Prompt-injection filter

Delegation expiry

End-to-end example