Skip to main content

​
Overview

The Alfred API gives you full programmatic access to your vault, specialists, workflows, and service management. Everything you can do in the dashboard, you can do via the API.
The base URL for all API endpoints is https://alfred.black/api/v1. Authenticate every request with your API key.

​
Authentication

Every request requires a Bearer token in the Authorization header: 
curl https://alfred.black/api/v1/vault/context \
  -H "Authorization: Bearer alf_your_key_here"
Create API keys in your dashboard under Settings > API Keys. See the Authentication page for details.

​
Request format

All requests that send data must use application/json as the Content-Type: 
curl -X POST https://alfred.black/api/v1/vault/inbox \
  -H "Authorization: Bearer alf_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"filename": "notes.md", "content": "..."}'

​
Response format

All responses return JSON. Successful responses have a structure specific to each endpoint. Error responses follow a consistent format: 
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable message",
    "details": {
      "additional": "context"
    }
  }
}

​
Error codes

CodeHTTP StatusDescription
UNAUTHORIZED401Missing, malformed, or invalid API key
VALIDATION_ERROR400Request body failed validation (missing required fields, invalid types)
NOT_FOUND404Requested resource does not exist
CONFLICT409Operation conflicts with current state (e.g., record already exists)
EXEC_ERROR500Operation execution failed
INTERNAL_ERROR500Unexpected server error

​
Endpoint groups

The API is organized into 8 functional groups with 86 endpoints:

Vault (12 endpoints)

Record CRUD, search, inbox management, schema inspection.

Workers (15 endpoints)

Curator, Janitor, Distiller, and Surveyor control. Start, stop, scan, run.

Workflows (7 endpoints)

Workflow management. List, start, terminate, signal, cancel, view history.

Schedules (7 endpoints)

Recurring workflows. Create, pause, unpause, trigger, delete schedules.

Devices (7 endpoints)

Device pairing. Approve, reject, remove, rotate keys, revoke access.

OpenClaw (13 endpoints)

Gateway management. Health, skills, sessions, agents, plugins, hooks, secrets.

Logs (1 endpoint)

Real-time SSE log streaming from your services.

Instance (24 endpoints)

Health checks, system info, service management, credentials, specialist config.

​
Next steps

Authentication

Learn how to authenticate API requests

Vault endpoints

Start with vault operations