AI Integration Manifest

This is the single source of truth for any AI agent — Gemini, Claude, GPT, or any LLM — operating within Acrobi Cortex. If you are an AI agent, read this document before making any API calls.

How to Read This Manifest

Parse this document in order:

1. Authentication Protocol (Section 1) — How to identify yourself and obtain credentials
2. Endpoint Registry (Section 2) — All available API operations grouped by domain
3. Request/Response Examples (Section 3) — Complete curl + JSON pairs for the five most common operations
4. Event System (Section 4) — Webhook and WebSocket events you can subscribe to
5. State Management (Section 5) — How to report your status so the platform knows you are alive
6. Capability Model (Section 6) — What operations you are permitted to perform
7. Capabilities Matrix (Section 7) — Quick lookup: full access, read-only, and not-yet-available

Quick Reference

Property	Value
Base URL	https://api.cortex.acrobi.com
API Version	1.0.3
Auth	JWT Bearer token or API Key
Content-Type	application/json
Rate Limiting	Per-user, per-tier; limits returned in X-RateLimit-* response headers
WebSocket	wss://api.cortex.acrobi.com/api/ws?token=<JWT>
SSE Streaming	GET /api/streaming/agents/:name/stream

---

1. Authentication Protocol

Cortex supports three authentication methods. Choose the one appropriate to your deployment context.

Method 1: JWT Bearer Token

Algorithm: HS256. Lifetime: 30 days. Refresh with POST /api/auth/refresh.

# Obtain token
curl -X POST https://api.cortex.acrobi.com/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "agent@example.com", "password": "your-password"}'
# Response: { "token": "eyJ...", "refreshToken": "eyJ..." }

# Use token on every request
curl https://api.cortex.acrobi.com/api/agents \
  -H "Authorization: Bearer eyJ..."

Method 2: API Key

Long-lived keys stored as SHA-256 hashes server-side. Prefix: sk-ctx-.

X-API-Key: sk-ctx-abc123def456...

Available scopes: read, write, admin. Manage keys at POST /api/auth/api-keys.

Method 3: Scope Headers

Many endpoints are scope-aware. Without these headers, requests default to the authenticated user's personal workspace.

Header	Purpose	Example
X-Organization-Id	Target organization	org-abc123
X-Project-Id	Narrow to a specific project	proj-def456
x-scope-type	Override scope resolution	organization | project | user

Agent Identity Headers

When an AI agent calls the API on its own behalf, include these headers so activity is attributed correctly in logs, dashboards, and the activity feed:

Header	Purpose	Example
X-Agent-Definition	Agent type/role	coder-agent
X-Agent-Instance-Id	Unique instance identifier	inst-789xyz
X-Agent-Display-Name	Human-readable label	Backend Coder #3
X-Agent-Owner-Id	User who owns this agent	user-123

---

2. Complete API Endpoint Registry

All endpoints require Authorization: Bearer <JWT> or X-API-Key: sk-ctx-... unless noted otherwise. The Auth column shows JWT/Key for standard auth and None for public endpoints.

Agents (16 endpoints)

Method	Path	Description	Auth	Mutating
GET	/api/agents	List agents in catalog	JWT/Key	No
POST	/api/agents	Create agent definition	JWT/Key	Yes
GET	/api/agents/:name	Get agent by name	JWT/Key	No
PATCH	/api/agents/:name	Update agent config	JWT/Key	Yes
DELETE	/api/agents/:name	Delete agent	JWT/Key	Yes
GET	/api/agents/:name/skills	List assigned skills	JWT/Key	No
POST	/api/agents/:name/skills/:skillId	Assign skill to agent	JWT/Key	Yes
DELETE	/api/agents/:name/skills/:skillId	Unassign skill	JWT/Key	Yes
PATCH	/api/agents/:name/soul	Update SOUL (values/traits)	JWT/Key	Yes
POST	/api/agents/:name/execute	Trigger execution with input	JWT/Key	Yes
POST	/api/agents/:name/delegate	Delegate task to this agent	JWT/Key	Yes
GET	/api/agents/executions	List executions across all agents	JWT/Key	No
GET	/api/agents/:name/executions	List executions for one agent	JWT/Key	No
GET	/api/agents/:name/executions/:id	Get execution detail + output	JWT/Key	No
GET	/api/agents/:name/metrics	Performance metrics (latency, success)	JWT/Key	No
POST	/api/agents/:name/self-improve	Trigger self-improvement cycle	JWT/Key	Yes

Skills (6 endpoints)

Method	Path	Description	Auth	Mutating
GET	/api/skills	List all skills	JWT/Key	No
POST	/api/skills	Create skill	JWT/Key	Yes
GET	/api/skills/:id	Get skill detail	JWT/Key	No
PATCH	/api/skills/:id	Update skill	JWT/Key	Yes
DELETE	/api/skills/:id	Delete skill	JWT/Key	Yes
POST	/api/skills/:id/test	Run skill test harness	JWT/Key	Yes

Tasks (5 endpoints)

Method	Path	Description	Auth	Mutating
GET	/api/kanban-tasks	List tasks (scope-aware)	JWT/Key	No
POST	/api/kanban-tasks	Create task	JWT/Key	Yes
GET	/api/kanban-tasks/:id	Get task detail	JWT/Key	No
PATCH	/api/kanban-tasks/:id	Update task (status, assignment, etc.)	JWT/Key	Yes
DELETE	/api/kanban-tasks/:id	Delete task	JWT/Key	Yes

Valid statuses: backlog, assigned, in_progress, qa_review, up_for_review, done

Swarms (13 endpoints)

Method	Path	Description	Auth	Mutating
GET	/api/swarms	List swarms	JWT/Key	No
POST	/api/swarms	Create swarm	JWT/Key	Yes
GET	/api/swarms/:id	Get swarm detail	JWT/Key	No
PATCH	/api/swarms/:id	Update swarm config	JWT/Key	Yes
DELETE	/api/swarms/:id	Delete swarm	JWT/Key	Yes
PATCH	/api/swarms/:id/status	Change swarm status	JWT/Key	Yes
GET	/api/swarms/:id/metrics	Swarm performance metrics	JWT/Key	No
GET	/api/swarms/:id/agents	List agents in swarm	JWT/Key	No
POST	/api/swarms/:id/agents	Add agent to swarm	JWT/Key	Yes
DELETE	/api/swarms/:id/agents/:agentId	Remove agent from swarm	JWT/Key	Yes
GET	/api/swarms/:id/tasks	List swarm tasks	JWT/Key	No
POST	/api/swarms/:id/tasks	Create swarm task	JWT/Key	Yes
PATCH	/api/swarms/:id/tasks/:taskId	Update swarm task	JWT/Key	Yes

Integrations (7 endpoints)

Method	Path	Description	Auth	Mutating
GET	/api/integrations	List integrations	JWT/Key	No
POST	/api/integrations	Add integration	JWT/Key	Yes
GET	/api/integrations/:id	Get integration detail	JWT/Key	No
PATCH	/api/integrations/:id	Update integration	JWT/Key	Yes
DELETE	/api/integrations/:id	Remove integration	JWT/Key	Yes
POST	/api/integrations/:id/sync	Trigger manual sync	JWT/Key	Yes
GET	/api/integrations/:id/test	Test connection health	JWT/Key	No

Supported providers: github, discord, slack, notion, linear, gmail, zapier, webhook, custom

Webhooks (6 endpoints)

Method	Path	Description	Auth	Mutating
POST	/api/webhooks/register	Register new webhook	JWT/Key	Yes
GET	/api/webhooks	List registered webhooks	JWT/Key	No
GET	/api/webhooks/:id	Get webhook detail	JWT/Key	No
DELETE	/api/webhooks/:id	Delete webhook	JWT/Key	Yes
POST	/api/webhooks/:id/test	Send test payload to URL	JWT/Key	Yes
GET	/api/webhooks/:id/deliveries	Delivery history + status codes	JWT/Key	No

Agent Status (6 endpoints)

Method	Path	Description	Auth	Mutating
POST	/api/agent-status	Report a status event	JWT/Key	Yes
POST	/api/agent-status/heartbeat	Upsert heartbeat (keep-alive)	JWT/Key	Yes
GET	/api/agent-status	List recent status reports	JWT/Key	No
GET	/api/agent-status/summary	All agents with current status counts	JWT/Key	No
GET	/api/agent-status/live	Active agents only (working/idle)	JWT/Key	No
GET	/api/agent-status/:agentName	Status history for one agent	JWT/Key	No

Memories (8 endpoints — scope-aware)

All memory endpoints respect X-Organization-Id and X-Project-Id headers to isolate data.

Method	Path	Description	Auth	Mutating
POST	/api/memories/bulk	Bulk store multiple entries	JWT/Key	Yes
GET	/api/memories/search	Semantic / FTS search	JWT/Key	No
GET	/api/memories/stats	Memory count, type breakdown	JWT/Key	No
GET	/api/memories	List memories (paginated)	JWT/Key	No
POST	/api/memories	Store single memory entry	JWT/Key	Yes
GET	/api/memories/:id	Get memory by ID	JWT/Key	No
PATCH	/api/memories/:id	Update memory content	JWT/Key	Yes
DELETE	/api/memories/:id	Delete memory	JWT/Key	Yes

LLM Providers (6 endpoints)

Method	Path	Description	Auth	Mutating
GET	/api/llm/providers	List configured providers	JWT/Key	No
POST	/api/llm/providers	Add provider + API key	JWT/Key	Yes
GET	/api/llm/providers/:id	Get provider detail	JWT/Key	No
PATCH	/api/llm/providers/:id	Update provider config	JWT/Key	Yes
DELETE	/api/llm/providers/:id	Remove provider	JWT/Key	Yes
POST	/api/llm/providers/:id/test	Validate connection + credentials	JWT/Key	No

Supported provider types (16+): openai, anthropic, google, xai, mistral, deepseek, cohere, openrouter, ollama, groq, cerebras, moonshot, minimax, nvidia, claude-code, custom

Conversations (5 endpoints)

Stored with FTS5 full-text indexing for fast search across all agent conversations.

Method	Path	Description	Auth	Mutating
POST	/api/conversations/store	Store a conversation message	JWT/Key	Yes
GET	/api/conversations/search	Full-text search across conversations	JWT/Key	No
GET	/api/conversations/:agentId	List conversations for an agent	JWT/Key	No
GET	/api/conversations/:agentId/overview	Summarized view	JWT/Key	No
GET	/api/conversations/:agentId/expand	Expand a summary to messages	JWT/Key	No

Cron Jobs (4 endpoints)

Method	Path	Description	Auth	Mutating
GET	/api/cron-jobs	List scheduled jobs	JWT/Key	No
POST	/api/cron-jobs	Create cron job	JWT/Key	Yes
PATCH	/api/cron-jobs/:id	Update schedule or payload	JWT/Key	Yes
DELETE	/api/cron-jobs/:id	Remove job	JWT/Key	Yes

Documents (5 endpoints)

Method	Path	Description	Auth	Mutating
GET	/api/documents	List documents (scope-aware)	JWT/Key	No
POST	/api/documents	Create document	JWT/Key	Yes
GET	/api/documents/:id	Get document with full content	JWT/Key	No
PATCH	/api/documents/:id	Update title or content	JWT/Key	Yes
DELETE	/api/documents/:id	Delete document	JWT/Key	Yes

Supported types: markdown, code, text, json, yaml, html, css

Additional Domains

The following route groups are part of the API but not expanded here. Each follows the same { success, data } / { error } response convention.

Path Prefix	Description
/api/auth/*	Login, register, refresh token, forgot/reset password, 2FA (TOTP + SMS), API key management
/api/organizations/*	Org CRUD, member invites, role assignment
/api/projects/*	Project CRUD, cover images
/api/settings/*	User preferences, notification settings
/api/dashboard/*	Summary metrics, widget data
/api/marketplace/*	Publish, search, install agents from marketplace
/api/knowledge-graph/*	Graph nodes, edges, traversal queries
/api/ideas/*	Idea capture and pipeline management
/api/content/*	Content sources (YouTube transcripts, articles)
/api/rbac/*	Role-based access control — roles, permissions, grants
/api/persistent-agents/*	Long-lived agent instances with scheduled wake-ups
/api/sandbox/*	Isolated execution sandbox for untrusted agent code
/api/agent-capabilities/*	Capability profiles, resolve effective permissions
/api/agent-health/*	Health checks, degraded-mode detection
/api/browser/*	Browser automation — navigate, screenshot, scrape
/api/scheduled-agents/*	Agent scheduling via cron expressions
/api/agent-versions/*	Version history, rollback
/api/sessions/*	Session management for multi-turn agents
/api/qmd/*	QMD (Query/Mutate/Delegate) search protocol
/api/mission/*	Mission Control — high-level objective tracking
/api/evals/*	LLM evaluation runs and scoring
/api/collaboration/*	Real-time multi-agent collaboration sessions
/api/notifications/*	Notification center, delivery preferences
/api/graphql	GraphQL API (mirrors REST; useful for complex queries)
/api/workflows/*	Workflow orchestration — DAG-based pipelines
/api/streaming/*	SSE streaming for long-running agent outputs
/api/oauth/*	OAuth 2.0 — authorize, callback, token exchange
/api/feature-flags/*	Runtime feature flag evaluation
/api/billing/*	Subscriptions, usage records, invoices
/api/mobile/*	Mobile-optimized API (compact responses)

---

3. Critical Request/Response Examples

The five most common operations an AI agent will need to perform. All examples assume $TOKEN is a valid JWT.

Example 1: Create an Agent

curl -X POST https://api.cortex.acrobi.com/api/agents \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-coder-agent",
    "displayName": "My Coder Agent",
    "description": "Implements features and fixes bugs with self-testing quality gates",
    "category": "development",
    "model": "claude-sonnet-4-20250514",
    "status": "active",
    "systemPrompt": "You are an expert TypeScript developer. Always run tsc and eslint before marking work complete.",
    "capabilities": ["code_review", "implementation", "testing"]
  }'

Response 201 Created:

{
  "success": true,
  "data": {
    "id": "agent-abc123",
    "name": "my-coder-agent",
    "displayName": "My Coder Agent",
    "category": "development",
    "model": "claude-sonnet-4-20250514",
    "status": "active",
    "createdAt": "2026-04-03T12:00:00.000Z"
  }
}

Example 2: Execute an Agent

curl -X POST https://api.cortex.acrobi.com/api/agents/my-coder-agent/execute \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "taskId": "task-456",
    "input": "Implement the login page with email/password authentication",
    "context": { "projectId": "proj-123", "stack": "Next.js 15, TypeScript" }
  }'

Response 200 OK:

{
  "success": true,
  "data": {
    "executionId": "exec-789",
    "agentName": "my-coder-agent",
    "status": "running",
    "startedAt": "2026-04-03T12:01:00.000Z"
  }
}

Poll execution status at GET /api/agents/my-coder-agent/executions/exec-789 or subscribe via WebSocket for real-time updates.

Example 3: Create a Task

curl -X POST https://api.cortex.acrobi.com/api/kanban-tasks \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Project-Id: proj-123" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Implement login page",
    "description": "Build email/password login with JWT authentication",
    "status": "backlog",
    "priority": "high",
    "assigned_agent": "my-coder-agent",
    "project_id": "proj-123"
  }'

Response 201 Created:

{
  "success": true,
  "data": {
    "id": "task-456",
    "title": "Implement login page",
    "status": "backlog",
    "priority": "high",
    "assigned_agent": "my-coder-agent",
    "project_id": "proj-123",
    "createdAt": "2026-04-03T12:00:00.000Z"
  }
}

Example 4: Report Agent Status

Call this whenever your status changes. Also send a heartbeat every 30 seconds while working.

curl -X POST https://api.cortex.acrobi.com/api/agent-status \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "agentName": "my-coder-agent",
    "status": "working",
    "message": "Implementing login form component — 40% complete",
    "taskId": "task-456",
    "metadata": { "progress": 0.4, "filesChanged": 2, "phase": "implementation" }
  }'

Response 200 OK:

{ "success": true, "id": "status-report-789" }

Valid status values: idle, working, completed, blocked, error

Example 5: Register a Webhook

curl -X POST https://api.cortex.acrobi.com/api/webhooks/register \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/cortex-webhook",
    "events": ["agent.completed", "agent.failed", "task.status_changed"],
    "secret": "min-32-char-webhook-signing-secret"
  }'

Response 201 Created:

{
  "success": true,
  "data": {
    "id": "wh-abc123",
    "url": "https://your-server.com/cortex-webhook",
    "events": ["agent.completed", "agent.failed", "task.status_changed"],
    "createdAt": "2026-04-03T12:00:00.000Z"
  }
}

---

4. Event System

Webhook Events (6 events)

Register a target URL via POST /api/webhooks/register (see Example 5 above). Cortex will deliver a POST to your URL for each subscribed event.

Event	Trigger
task.created	A new task was created
task.completed	Task status transitioned to done
task.status_changed	Any other task status transition
agent.spawned	An agent execution was started
agent.completed	An agent execution completed successfully
agent.failed	An agent execution errored

Webhook Signature Verification

Every delivery includes these request headers for HMAC-SHA256 authentication:

Header	Value
X-Cortex-Signature	sha256=<HMAC-SHA256 of raw body using your webhook secret>
X-Cortex-Event	Event name, e.g. agent.completed
X-Cortex-Delivery	Unique UUID for this delivery attempt
X-Cortex-Timestamp	Unix timestamp of delivery

To verify: compute HMAC-SHA256(rawBody, webhookSecret), hex-encode it, and compare to the value after sha256= in X-Cortex-Signature. Reject deliveries that fail verification or have a timestamp older than 5 minutes.

WebSocket Activity Events (18+ event types)

Connect to: wss://api.cortex.acrobi.com/api/ws?token=<JWT>

After connecting, subscribe to channels:

{ "type": "subscribe", "channelId": "agent:my-coder-agent" }
{ "type": "subscribe", "channelId": "swarm:swarm-123" }
{ "type": "subscribe", "channelId": "project:proj-456" }

Full list of activity events:

Event	Description
agent.spawned	Agent execution started
agent.completed	Agent execution finished
agent.failed	Agent execution errored
agent.status	Agent status update (working, blocked, etc.)
task.created	New task created
task.status_changed	Task status changed
task.updated	Task fields updated
task.deleted	Task removed
chief.plan.created	Chief Coordinator produced an execution plan
chief.task.assigned	Chief assigned a task to an agent
chief.task.progress	Progress update from Chief
swarm.phase.started	Swarm entered a new phase
swarm.phase.completed	Swarm phase finished
swarm.phase.failed	Swarm phase errored
gate.passed	A quality gate check passed
gate.failed	A quality gate check failed
chat.message	New chat message from agent or user

See WebSocket for full protocol and message schema documentation.

---

5. State Management

Cortex uses three complementary tiers for agent state. An agent should use all three to ensure visibility in dashboards, logs, and real-time feeds.

Tier 1: Database-Backed Status (mandatory)

Every status change and every heartbeat is stored in the database and visible in the Mission Control dashboard.

# Report a status change
POST /api/agent-status
{
  "agentName": "my-coder-agent",
  "status": "working",           # idle | working | completed | blocked | error
  "message": "Running tsc check",
  "taskId": "task-456",
  "metadata": { "progress": 0.7 }
}

# Heartbeat — send every 30 seconds while running (prevents stale "live" entries)
POST /api/agent-status/heartbeat
{
  "agentName": "my-coder-agent",
  "status": "working",
  "currentTask": "task-456"
}

Agents that stop sending heartbeats are automatically marked as offline after 90 seconds.

Tier 2: WebSocket Real-Time

Connect to wss://api.cortex.acrobi.com/api/ws?token=<JWT> to:

• Receive events from other agents and the Chief Coordinator in real-time
• Discover newly assigned tasks without polling
• Observe swarm phase transitions and gate results

This is the fastest path for agent-to-agent coordination. A coder agent waiting for QA approval should subscribe to gate.passed / gate.failed events rather than polling GET /api/kanban-tasks/:id.

Tier 3: SSE Streaming

For long-running agent outputs (code generation, research reports, etc.) that need to stream back to a UI or calling process:

GET /api/streaming/agents/:name/stream
Authorization: Bearer <JWT>
Accept: text/event-stream

The server sends data: events as the agent produces output. Use this when you need incremental delivery rather than a single response payload.

---

6. Capability and Permission Model

Overview

Cortex has 56 granular capabilities across 13 categories. Every API call is checked against the calling agent's resolved capability set.

Access levels:

Level	Name	Behavior
0	none	Operation blocked — returns 403 Forbidden
1	read	GET/list operations only
2	write	Read + create/update/delete (dangerous ops require explicit confirmation)
3	autonomous	Full access including dangerous operations without confirmation

Dangerous Capabilities (10)

These 10 capabilities require autonomous access level or explicit write confirmation:

agent.delete, agent.execute (with external network), swarm.delete, swarm.execute (parallel spawning), integration.delete, memory.delete_all, document.delete, cron.delete, webhook.delete, sandbox.escape_policy

Preset Profiles (7)

Profile	Key Capabilities	Typical Assignment
Chief	All at autonomous	Chief Coordinator only
Coder	agent.execute, task.update, document.write, skill.read	Development agents
Tester	task.read/update, agent.read, memory.read	QA agents
Researcher	memory.write, knowledge-graph.write, document.write	Research agents
Architect	agent.create/update, swarm.create, skill.create	Architect agents
PM	task.* (all), swarm.read, agent.read	Project manager agents
Viewer	All domains at read	Reporting/analytics agents

Effective Permission Resolution

Effective permissions are the intersection of four layers. An agent can never exceed the most restrictive layer:

effective = definition_capabilities ∩ instance_overrides ∩ project_policy ∩ workspace_policy

To check your effective capabilities at runtime:

POST /api/agent-capabilities/resolve
{
  "agentName": "my-coder-agent",
  "scope": "project",
  "entityId": "proj-123"
}

Response includes the resolved capability map plus any warnings about restricted operations.

See Capabilities for the full 56-capability list and Capability Control for the full access-level system and override mechanics.

---

7. Capabilities Matrix

Quick reference for what AI agents can do today.

Full Access (Read and Write)

Domain	Operations
Agents	Create, read, update, delete, execute, delegate, self-improve
Tasks	Create, read, update, delete, assign, transition status
Skills	Create, read, update, delete, test
Swarms	Create, read, update, delete, execute, manage agents/tasks
Integrations	Create, read, update, delete, sync, test
Webhooks	Register, list, delete, test, view deliveries
Memories	Bulk store, search, CRUD, stats (scope-isolated)
LLM Providers	Add, configure, update, remove, test
Conversations	Store, search FTS5, list, summarize, expand
Documents	Create, read, update, delete (all document types)
Cron Jobs	Create, update, delete, list
Agent Status	Report, heartbeat, list, summarize

Read-Only

Domain	Notes
Execution logs	GET /api/agents/:name/executions — no cancel or replay endpoint yet
Agent metrics	Performance and success-rate stats
Swarm metrics	Phase timing, task completion rates
Webhook delivery history	Delivery status codes only; no replay
Audit log	Append-only by design
Activity feed	GET /api/activity-feed — aggregate event stream
Dashboard summary	GET /api/dashboard — read-only aggregations
System health	GET /api/health — no auth required

Not Yet Available

These capabilities are documented in Gap Analysis as known missing features:

Missing Capability	Workaround
Agent self-registration	Register via human user or Chief Coordinator
Config self-update	Use PATCH /api/agents/:name via an authorized orchestrator
Task dependency graph	Use metadata field to encode dependency info manually
Bi-directional agent messaging	Use WebSocket channel subscriptions
Secret self-management	Secrets managed by human admins via wrangler secret put
Execution cancel/replay	Monitor via WebSocket; no cancel endpoint yet
Task checkpointing	Store progress in memories as a manual workaround