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

Get a key

POST /v1/device/code

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.

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

Response: user_code, verification_uri, device_code, expires_in, interval. Poll POST /v1/device/token with device_code every interval seconds until it returns status approved and an api_key. A bodyless or malformed request to either endpoint returns 400 invalid_json. POST /v1/keys is closed on this deployment: it always returns 403 anonymous_keys_disabled, sign in with memorable login instead. GET /v1/usage/me is internal to the CLI's own status checks, not a public endpoint.

Create a procedure

POST /v1/extract

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.

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",
    "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 }
    ],
    "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).

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.

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. The free allowance is 1,000 memorables a month with a one-time reserve of 500 behind it.

Security

• What is kept, and only this: a workspace key writes one workflows row per prompt and one procedures row per admitted procedure. The corpus is never sent.
• Your database stays yours. The API never receives connection credentials.
• Scrubbed input only. The CLI keeps twelve allow-listed argument fields, replaces credential-shaped strings, and sends nothing else.
• Injection-hardened recall. Stored procedures are re-rendered as explicitly inert reference data before they ever reach an agent's context.