API Reference

The Acrobi Cortex REST API gives you programmatic access to agents, tasks, swarms, memories, skills, integrations, and all platform features.

Base URL

https://api.cortex.acrobi.com

Local development:

http://localhost:3001

Versioning

The API is currently at v1. Breaking changes will be introduced under a new version prefix (e.g. /v2/). The current unversioned routes are stable.

Content Type

All requests and responses use application/json. Always include:

Content-Type: application/json

Authentication

All protected endpoints require a Bearer token in the Authorization header:

Authorization: Bearer <your-api-token>

Tokens are issued via the /api/auth/login endpoint or created as long-lived API keys in the dashboard under Settings → API Keys.

Agent-to-Agent calls

Agents calling the API on behalf of a task should pass X-Agent-Name and X-Task-Id headers for audit tracing.

Standard Response Shapes

Success:

{
  "success": true,
  "data": { ... }
}

Success with pagination:

{
  "success": true,
  "data": [...],
  "pagination": {
    "limit": 20,
    "offset": 0,
    "total": 143
  }
}

Error:

{
  "error": "Human-readable message describing what went wrong"
}

HTTP Status Codes

Code	Meaning
200	OK — request succeeded
201	Created — resource was created
400	Bad Request — missing or invalid parameters
401	Unauthorized — missing or invalid auth token
403	Forbidden — valid token but insufficient permissions
404	Not Found — resource does not exist
429	Too Many Requests — rate limit exceeded
500	Internal Server Error — something went wrong on our end

Rate Limiting

Every response includes rate limit headers:

Header	Description
X-RateLimit-Limit	Maximum requests allowed in the window
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Reset	Unix timestamp when the window resets
Retry-After	Seconds to wait (only on 429 responses)

Default limits: 1 000 requests / minute per API key. Burst-heavy operations (execute, swarm deploy) count as 5 requests each.

Pagination

List endpoints accept limit and offset query parameters:

Parameter	Default	Max	Description
limit	20	100	Number of items to return
offset	0	—	Number of items to skip

Example:

curl "https://api.cortex.acrobi.com/api/agents?limit=10&offset=20" \
  -H "Authorization: Bearer <token>"

Scope Headers

Multi-tenant endpoints respect optional scope headers for organization and project isolation:

Header	Description
X-Scope-Organization-Id	Restrict to a specific organization
X-Scope-Project-Id	Restrict to a specific project

API Domains

Domain	Description
Agents	Create, configure, execute, and monitor agents
Tasks	Kanban tasks with status and agent assignment
Skills	Reusable skill handlers assignable to agents
Swarms	Multi-agent swarm orchestration
Integrations	External service connections
Webhooks	Event-driven outbound notifications
Agent Status	Real-time agent status reporting and heartbeats
Memories	Persistent knowledge storage and search
LLM Providers	Configure and test language model providers
Conversations	Conversation history and full-text search
Cron Jobs	Scheduled recurring agent tasks
Documents	Structured document storage