API reference

Nexus Core exposes a single REST API, grouped into scopes. Every endpoint speaks JSON; OpenAPI is generated by utoipa and served live when Core runs.

Scope	Purpose
/agents-api	Agent CRUD, clone, enable/disable, skill assignment
/skills-api	Skill CRUD, versioning, test, publish
/memory-api	Memory search, scoped reads/writes, approval queue
/goals-api	Create goals, decompose into tasks
/tasks-api	Task lifecycle reads/writes
/runs-api	Agent runs: start, cancel, logs, results
/board-api	Internal board + sync triggers
/approvals-api	Human-approval queue
/webhooks-api	Inbound webhooks (Plane, CI)

Live OpenAPI

When Core is running:

• Swagger UI — https://api.nexus.dev/swagger-ui/
• Raw JSON — https://api.nexus.dev/api-docs/openapi.json

Base URL

Production: https://api.nexus.dev · Local dev: http://localhost:8080

Authentication

Scheme	Header	Used by
Admin JWT	Authorization: Bearer <jwt>	UI / operators
API key	x-nexus-api-key: <key>	machine clients
Agent token	Authorization: Bearer <agent-token>	run pods reporting back

Auth and permissions are handled by the nexus-auth crate. See Security & permissions.

Common shapes

Errors:

{ "error": "human-readable message" }

Status codes: 200 OK · 201 Created · 400 validation · 401 auth · 403 forbidden · 404 not found · 409 conflict · 429 rate-limited · 5xx server/upstream.

Examples

Create an agent

curl -X POST https://api.nexus.dev/agents-api \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backend Implementer",
    "slug": "backend-implementer",
    "model": { "provider": "openai", "model": "gpt-5.5-thinking", "temperature": 0.2 },
    "runtime": { "image": "nexus-agent-runner:latest", "cpu": "2", "memory": "4Gi", "timeout_minutes": 60 },
    "skills": ["rust-backend-development"],
    "memory_policy": { "read_scopes": ["global","project","agent_private"], "write_scopes": ["project","agent_private"], "auto_save": true },
    "tools": ["git","shell","cargo"],
    "permissions": { "can_commit": true, "can_open_pr": true, "can_merge": false }
  }'

Create a goal

curl -X POST https://api.nexus.dev/goals-api \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{ "project_id": "nexus", "title": "Build authentication system" }'

Returns the goal plus drafted tasks (status draft) awaiting approval.

Start a run

curl -X POST https://api.nexus.dev/runs-api \
  -H "Authorization: Bearer $JWT" \
  -d '{ "agent_id": "agent_backend_implementer", "task_id": "task_456" }'

Stream run logs

curl -N https://api.nexus.dev/runs-api/run_123/logs

What's not in the API yet

• Cursor-based pagination (current limits are generous defaults)
• GraphQL (REST suffices)
• Vector memory search (text + tags first)
• Jira board adapter (Plane first)

Tracked on the roadmap.

Related

• Architecture · Operations
• Data model