Amolfi API

Authentication

Use a workspace API key to call Amolfi from your server. Send it as a Bearer token with each request.

Authorizationheader · required

Bearer amolfi_sk_…

Content-Typeheader

application/json for JSON request bodies.

One key. One workspace.

The key identifies the workspace. Each tool also checks its required scope and the current permissions of the member who created the key.

For the invoice example, use a key with finance.invoices.read and a member with Finance view access. A key without that scope returns SCOPE_REQUIRED.

Keep keys in server-side environment variables. The code examples read AMOLFI_API_KEY.

curl https://api.amolfi.com/v1/tools/finance_list_invoices \
  -H "Authorization: Bearer $AMOLFI_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"status":"open","limit":3}'

Content-Type: application/json
X-Amolfi-Request-Id: <request-id>
X-Amolfi-Api-Version: 2026-08-12

Explore the API schema

The public OpenAPI document describes available tools, their inputs, responses and authentication requirements. Use it to build an integration against the current contract.

/v1/openapi.jsonGET · public

The machine-readable OpenAPI 3.1 document.

/v1/scopesGET · public

Discover scopes, associated tools, actions and roles.

/v1/healthGET · public

Check that the API is reachable.

These discovery endpoints do not require a key. Authenticated workspace requests belong on your server.

curl https://api.amolfi.com/v1/openapi.json

{
  "openapi": "3.1.0",
  "paths": {
    "/v1/tools/finance_list_invoices": {
      "post": { "operationId": "finance_list_invoices" }
    }
  }
}

Read workspace data

Bring workspace records into your internal tools. Call a named tool with its JSON input and receive a structured result.

This example fetches up to three open invoices. It requires finance.invoices.read.

statusstring · optional

Filter by invoice status. This example uses open.

limitinteger · optional

Maximum number of invoices to return. This example uses 3.

Read the result

Invoice records appear in data.invoices. Amounts such as total_cents use minor currency units. The result also includes a receipt and envelope metadata.

Check meta.truncated before treating a result as complete.

curl https://api.amolfi.com/v1/tools/finance_list_invoices \
  -H "Authorization: Bearer $AMOLFI_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"status":"open","limit":3}'

[
  {
    "id": "11111111-1111-4111-8111-111111111111",
    "invoice_number": "INV-1042",
    "customer_name": "Acme Studio",
    "currency": "USD",
    "status": "sent",
    "total_cents": 420000,
    "outstanding_cents": 420000
  }
]

Start an agent session

Give an agent a task, then follow its progress from your application. Start a session turn with a message; send the returned session ID to continue the conversation.

messagestring · required

The task or follow-up message for the agent.

session_idstring · optional

An existing session to continue. Omit it to start a new one.

Starting a turn requires sessions.sessions.write. Read activity with agent_session_events_list and the sessions.sessions.read scope.

Follow the work

Pass the session ID and an after_seq cursor when reading events. Use next_after_seq for the next request.

Actions that send, spend, sign or publish still return to an owner for approval in Amolfi.

curl https://api.amolfi.com/v1/tools/agent_session_turn_start \
  -H "Authorization: Bearer $AMOLFI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $REQUEST_ID" \
  --data '{"message":"Summarize my open invoices."}'

{
  "session_id": "11111111-1111-4111-8111-111111111111",
  "run_id": "22222222-2222-4222-8222-222222222222",
  "seq": "1",
  "route": "cloud",
  "replayed": false
}

React to workspace events

Receive a signed delivery when an invoice is paid, a contract is signed or a run completes. Register your endpoint in Settings → Developer → Webhooks.

• invoice.paidAn invoice is fully paid
• contract.signedA contract is signed
• run.completedAn agent run finishes

Verify every delivery

Verify X-Amolfi-Signature against the raw request bytes. First SHA-256 hash the webhook secret; use its hexadecimal digest as the HMAC-SHA256 key string.

Delivery is at least once. Deduplicate using X-Amolfi-Delivery before processing an event.

You can inspect existing subscriptions with admin_webhooks_list and the workspace.webhooks.read scope.

curl https://api.amolfi.com/v1/tools/admin_webhooks_list \
  -H "Authorization: Bearer $AMOLFI_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{}'

{
  "event": "invoice.paid",
  "timestamp": "2026-09-22T12:00:00.000Z",
  "data": {
    "id": "11111111-1111-4111-8111-111111111111",
    "invoice_number": "INV-1042",
    "status": "paid",
    "currency": "USD",
    "total_cents": 420000,
    "paid_cents": 420000
  }
}

Errors & retries

Use HTTP status and the JSON error code to decide what to do next. Save X-Amolfi-Request-Id when investigating a failed request.

401unauthorized

Check whether the key is missing, invalid, expired or revoked.

403forbidden

Check the required scope and the member’s workspace permissions.

404not found

The resource is unavailable in this workspace.

409conflict

An idempotency key was reused for a different request.

429throttled

Retry with exponential backoff and jitter.

Retry without repeating a write

Send an Idempotency-Key on write and proposal requests. Reuse the same key and request body when retrying; matching requests replay the stored result for 24 hours.

Handle throttling with backoff. There are no rate-limit remaining or reset headers to rely on.

curl https://api.amolfi.com/v1/tools/finance_list_invoices \
  -H "Authorization: Bearer $AMOLFI_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{"status":"open","limit":3}'

{
  "error": {
    "code": "SCOPE_REQUIRED",
    "message": "Required scope: finance.invoices.read"
  }
}

Your workspace, from the terminal

Use the CLI for the same workspace access from your terminal. Sign in with a device code, inspect available scopes and work with agent sessions.

Install @amolfi/cli with Node.js 20 or later. Run amolfi login and follow the sign-in instructions.

npm install -g @amolfi/cli

amolfi login
amolfi health
amolfi scopes