Extraction API

Authentication

Every request requires a bearer token in the Authorization header. Requests without a valid token return 401. Keys look like mk_… and are issued through the device flow above. The key itself is never stored: only a SHA-256 hash of it is.

Authorization: Bearer $MEMORABLE_API_KEY

Every response carries a request_id (also in the x-memorable-request-id header). Include it when reporting a problem, it lets us find your exact request.

Get a key

Keys belong to a workspace, so getting one means signing in. The CLI does it for you: memorable login starts a device authorization (RFC 8628), prints a short code, waits while you approve it in a browser, and saves the key to ~/.memorable/config.json. That flow suits the machines that most need a key, a container, an SSH session, a CI runner, because it needs no reachable localhost.

POST /v1/keys used to issue anonymous keys and now returns 403. A key with no owner cannot be metered, revoked, or shown to the person it belongs to.

curl -X POST https://memorable-extraction-api.memorable.workers.dev/v1/device/code \
  -H "Content-Type: application/json" -d '{"hostname":"my-laptop"}'

# → { "user_code": "TN9G-VTQX", "verification_uri": "https://memorable.sh/dash/device",
#     "device_code": "…", "expires_in": 600, "interval": 5 }
# then poll POST /v1/device/token with { "device_code": "…" } until it returns
# { "status": "approved", "api_key": "mk_…" }

Create a procedure

Converts a trace into a ProcedureDraft. Any harness is accepted: known harnesses (claude-code, codex, opencode) get curated activity registries; every other harness string is served by a generic tier that still infers execution from command-shaped input.

Body parameters

Response fields

curl https://memorable-extraction-api.memorable.workers.dev/v1/extract \
  -H "Authorization: Bearer $MEMORABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "run-183",
    "task_description": "rotate the TLS cert for api.example.com",
    "harness": "my-python-orchestrator",
    "tool_calls": [
      {"name": "shell",
       "input": {"command": "certbot renew"},
       "result": {"ok": true}},
      {"name": "shell",
       "input": {"command": "nginx -s reload"},
       "result": {"ok": true}}
    ]
  }'

{
  "draft": {
    "title": "rotate the TLS cert for api.example.com",
    "session_id": "run-183",
    "schema_version": "1.0.0",
    "trigger_signature": {
      "summary_text": "rotate the TLS cert for api.example.com",
      "entities": {
        "file_paths": [],
        "commands": ["certbot renew", "nginx -s reload"],
        "tool_names": ["shell"]
      },
      "search_text": "rotate the TLS cert ..."
    },
    "steps": [
      { "seq": 1, "action": "shell", "activity_class": "execute",
        "command": "certbot renew", "repeat_count": 1 },
      { "seq": 2, "action": "shell", "activity_class": "execute",
        "command": "nginx -s reload", "repeat_count": 1 }
    ],
    "preconditions": [],
    "postconditions": [
      "final command exited successfully: nginx -s reload"
    ],
    "embedding": [],
    "embedding_model": ""
  }
}

Embed a query

Query-side embedding for recall. Used only as a fallback, recall tries exact and lexical matching locally first (zero tokens, zero network), and the CLI prefers the embedding provider your GBrain already has configured.

curl https://memorable-extraction-api.memorable.workers.dev/v1/embed \
  -H "Authorization: Bearer $MEMORABLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "rotate the TLS cert"}'

Errors

Errors return JSON with an error code and, where useful, a detail message.

An embedding-provider failure is not an error: the draft still returns with embedding: [] and an embedding_error field, and recall degrades to lexical and exact matching.

Past the monthly allowance is a refusal rather than a degradation. The response is still 200 and still carries the draft, because nothing about the request was wrong and retrying it changes nothing, but it carries refused: "allowance_exhausted" and a detail sentence written for a person. No memorable is created: no row is written and no embedding call is made. Capture resumes when the period resets or the plan changes. The free allowance is 1,000 memorables a month with a one-time reserve of 500 behind it.

Rate limits

300 requests per 60 seconds per API key, enforced at the edge, and 5,000 requests per key per day. A body is capped at 8 MB and 2,000 tool calls, and the prompt at 2,000 characters. A typical integration makes one /v1/extract call per completed workflow, which sits far below both limits.

Security

• What is kept, and only this. A workspace key writes one workflows row per prompt (the prompt text, the harness, the tool-call count, the judge's verdict) and one procedures row per admitted procedure (title, steps, trigger signature, conditions, embedding). The corpus is never sent. Request bodies are never logged, and only a SHA-256 hash of a key is stored.
• Your database stays yours. The API never receives connection credentials. Writes happen on your machine through your existing GBrain connection, into an isolated source.
• Pre-scanned input only.The CLI sends only content that has already passed GBrain's secret scanner, and refuses to send a session that was written unscanned.
• Injection-hardened recall.Stored procedures are re-rendered as explicitly inert reference data, stripped of control characters and size-capped, before they ever reach an agent's context.