REST API

The Agentcy HTTP API is served by agentcy-api (Axum 0.8). All routes live under the /api/v1 prefix.

• Base URL (self-hosted default): http://localhost:8080/api/v1
• Auth: JWT (Bearer token) for user routes. Local provider signs with JWT_SECRET (HS256). OIDC provider verifies via JWKS (RS256). Some routes use other auth (worker tokens, webhook HMAC, pipeline JWT) — noted below.
• Content type: application/json unless otherwise noted.
• Streaming: chat uses Server-Sent Events (SSE). WebSocket updates (graph changes, task runs) go through a separate endpoint exposed by agentcy-ws.

Quickstart — authenticate and chat

# 1. Log in
TOKEN=$(curl -s http://localhost:8080/api/v1/auth/login \
  -H 'content-type: application/json' \
  -d '{"email":"admin@localhost","password":"admin"}' \
  | jq -r .token)

# 2. List connectors
curl -s http://localhost:8080/api/v1/sources \
  -H "authorization: Bearer $TOKEN" | jq

# 3. Create a conversation and send a message (SSE stream)
CONV=$(curl -s http://localhost:8080/api/v1/chat/conversations \
  -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{"title":"hello"}' | jq -r .id)

curl -N http://localhost:8080/api/v1/chat/conversations/$CONV/messages \
  -H "authorization: Bearer $TOKEN" \
  -H 'content-type: application/json' \
  -d '{"content":"list my kubernetes pods"}'

Route groups

All paths below are relative to /api/v1. Columns: path prefix · auth · purpose · source file.

Public (no JWT)

Prefix	Auth	Purpose	File
/health	none	Readiness + feature flags + DB reachability.	routes/health.rs
/auth	none	POST /login, POST /register, GET /me, OIDC callbacks.	routes/auth.rs
/sources/oauth/*	none	OAuth callback receivers (GitHub, Google, Read.ai, ...).	routes/sources.rs::public_router
/hooks/*	HMAC	Inbound webhook receiver. Signature in X-Agentcy-Signature.	routes/webhook_receiver.rs
/chat/incoming/*	shared secret	Inbound chat webhooks (channels, forms).	routes/chat.rs::incoming_webhook_router
/pipeline-agent/*	pipeline JWT	Agent run inside a pipeline execution.	routes/pipeline_agent.rs
/cli/*	none	CLI binary download + install script.	routes/cli_download.rs::public_router
/sandbox/preview/*	?token=	Sandbox preview proxy, self-auth via query token for iframe use.	routes/sandbox_preview.rs::preview_router
/workers (worker routes)	worker token	Worker daemon registration + heartbeat.	routes/workers.rs::worker_auth_routes

JWT-protected (user session)

Prefix	Purpose	File
/graph	Node search, subgraph expansion, Cypher, stats.	routes/graph.rs
/sources	Connector CRUD, validate, sync, jobs, sync history.	routes/sources.rs
/ingestion	Run ingestion jobs, monitor pipelines.	routes/ingestion.rs
/chat	Conversations, messages (SSE), tool calls, approvals.	routes/chat.rs
/agents	Registered agents, execution.	routes/agents.rs
/settings	Org settings, LLM config, feature flags.	routes/settings.rs
/api-keys	API key CRUD + rotation.	routes/api_keys.rs
/activity	Activity feed, audit log.	routes/activity.rs
/webhooks	Webhook CRUD, delivery log.	routes/webhooks.rs
/webhook-samples	Canned payloads for triggering test webhooks.	routes/webhook_samples.rs
/tasks	Scheduled tasks, manual triggers, run history.	routes/tasks.rs
/task-recommendations	Suggested tasks from graph analysis.	routes/task_recommendations.rs
/channels	Channel catalog, configure, QR flow, bindings, test, reload.	routes/channels.rs
/cron-channels	Cron-triggered channel messages.	routes/tasks.rs
/platform	Platform admin — orgs, invites, users.	routes/platform_admin.rs
/skills	Custom skill CRUD, approval workflow.	routes/skills.rs
/artifacts	Artifact metadata + download links.	routes/artifacts.rs
/sandboxes	Sandbox port mappings, session lookup.	routes/sandbox_preview.rs::ports_router
/pipelines	Pipeline definitions, runs, revert.	routes/pipelines.rs
/notifications	Notifications history + mark-read.	routes/notifications.rs
/users	Current user profile, org membership.	routes/users.rs
/memory	Org memory CRUD, recall, graph sync.	routes/memory.rs
/realms	Realm CRUD, list available.	routes/realms.rs
/ciab-native	CIAB coding-agent tools (local + EC2 runtimes).	routes/ciab_native.rs

Feature-gated (JWT)

Prefix	Flag	File
/rag	features.rag	routes/rag.rs
/workers (user endpoints)	features.workers	routes/workers.rs::worker_user_routes
/orchestrator	features.orchestrator	routes/orchestration_gateway
/voice	features.voice	routes/voice.rs
/ciab	Cargo feature connectors-dev	agentcy_source_ciab::proxy::router
/policies	features.policies	routes/policies.rs (adds policy middleware)

Auth

Local

POST /api/v1/auth/login
{
  "email": "admin@localhost",
  "password": "admin"
}

{
  "token": "eyJ...",
  "expires_at": "2026-04-25T12:00:00Z",
  "user": { "id": "...", "email": "admin@localhost", "role": "owner" }
}

OIDC

Configure at boot:

AUTH_PROVIDER=oidc
JWKS_URL=https://your-issuer/.well-known/jwks.json
JWT_ISSUER=https://your-issuer
JWT_AUDIENCE=agentcy

The API then accepts bearer tokens issued by the configured IdP.

API keys

Long-lived programmatic access, scoped per org. Create via POST /api-keys. Pass as Authorization: Bearer <key> — the auth middleware accepts both JWTs and API keys.

Worker tokens

Worker daemons authenticate with a separate token (set via WORKER_TOKEN) on /workers endpoints — not user-facing.

Webhook signatures

Inbound webhooks on /hooks/* are HMAC-signed. Header: X-Agentcy-Signature: sha256=<hex>. Secret is per-webhook, returned at creation.

Chat streaming

POST /api/v1/chat/conversations/:id/messages
Content-Type: application/json
Authorization: Bearer <jwt>

{ "content": "how many pods are down?" }

Response is SSE. Each chunk is one of:

event: message_start
data: {"message_id":"..."}

event: content_delta
data: {"delta":"I'll check the cluster..."}

event: tool_call_start
data: {"tool_call_id":"...","name":"execute_connector_tool","connector":"kubernetes"}

event: approval_required
data: {"approval_id":"...","tool":"execute_connector_tool","args":{...}}

event: tool_result
data: {"tool_call_id":"...","result":{...}}

event: message_end
data: {"finish_reason":"end_turn","usage":{...}}

Respond to an approval:

POST /api/v1/chat/conversations/:id/approvals/:approval_id
{ "approved": true }

See Tool Calling & the Catalog and Approval Flows for the full flow.

Health check

GET /api/v1/health

{
  "status": "ok",
  "features": {
    "rag": true, "workers": true, "orchestrator": false,
    "voice": false, "policies": false
  },
  "dependencies": {
    "postgres": "ok",
    "neo4j":    "ok",
    "redis":    "ok",
    "llm":      "ok"
  }
}

Errors

All error responses use a consistent shape:

{
  "error": {
    "code": "source_validation_failed",
    "message": "GitHub token is missing required scopes",
    "details": { "missing_scopes": ["repo"] }
  }
}

Common status codes:

Code	Meaning
400	Validation error (bad payload).
401	Missing or invalid auth.
403	Policy deny (audited).
404	Resource not found / wrong org.
409	Conflict (e.g. duplicate name, sync in progress).
422	Upstream provider rejected (e.g. invalid credentials).
429	Rate limited.
503	Sidecar unavailable (OpenFang off, worker down, etc.).

Pagination

Collection endpoints take ?limit (default 50, max 200) and ?cursor. Responses include:

{
  "items": [...],
  "next_cursor": "eyJ...",
  "total": 127
}

Idempotency

Mutating endpoints that create records accept Idempotency-Key: <uuid>. Safe to retry — duplicates return the original resource.

Clients

• Official SDKs — internal agentcy-sdk crate for Rust; Next.js client in frontend/lib/api/client.ts for the web UI.
• OpenAPI — the server exposes an OpenAPI 3.1 document at GET /api/v1/openapi.json (when the feature is built with --features openapi-schema). Use it to generate clients.
• curl — all examples on this page are copy-pasteable.

Next steps

• Environment Variables — every config knob for the API.
• Chat API guide — streaming, retries, history.
• Webhooks & Triggers — signature verification.