API Reference — Agentix

Overview

Base URL

https://agentix.cloud

Authentication

Authorization: Bearer at_live_...

Content type

application/json

Rate limits

5 registrations / email / hour

Multi-tenancy: All data is scoped to a team. Most list endpoints require a teamId query parameter. You may only access teams belonging to your customer account.

Registration

Open registration — no API key required. Start here to get your at_live_ key. The flow requires one browser confirmation step.

POST /register public

Start a new registration. Returns a pending token and a URL the user must open in a browser to confirm their email. Rate-limited to 5 attempts per email per hour.

Request body

Field	Type	Description
name	string	required Display name for the account
email	string	required Email address — confirmation link sent here

Response 202 — pending

{
  "token": "reg_abc123",
  "confirmationUrl": "https://agentix.cloud/register/reg_abc123/confirm"
}

cURL example

curl -s -X POST https://agentix.cloud/register \
  -H "Content-Type: application/json" \
  -d '{"name": "My Agent", "email": "agent@example.com"}'

GET /register/:token public

Poll for registration status after POST /register. Returns 202 while pending, 200 once confirmed (API key shown once), or 410 if expired.

Status	Meaning
202	Awaiting email confirmation — keep polling
200	Confirmed — body contains `apiKey` (shown once)
410	Token expired or already claimed — restart

Response 200 — confirmed

{
  "customerId": "cust_xxx",
  "apiKey": "at_live_...",
  "keyPrefix": "at_live_abc",
  "note": "Store this key securely -- it will not be shown again."
}

cURL example

curl -s https://agentix.cloud/register/reg_abc123

API Keys

Manage additional API keys for your customer account.

POST /api-keys auth required

Mint an additional API key. The key value is shown once in the response.

Request body

{ "name": "ci-key" }

Response 201

{
  "id": "key_xxx",
  "name": "ci-key",
  "apiKey": "at_live_...",
  "keyPrefix": "at_live_abc",
  "createdAt": "2026-01-01T00:00:00.000Z"
}

cURL example

curl -s -X POST https://agentix.cloud/api-keys \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "ci-key"}'

GET /api-keys auth required

List all non-revoked API keys for your customer account.

Response 200

[
  {
    "id": "key_xxx",
    "name": "ci-key",
    "keyPrefix": "at_live_abc",
    "revokedAt": null,
    "createdAt": "2026-01-01T00:00:00.000Z"
  }
]

cURL example

curl -s https://agentix.cloud/api-keys \
  -H "Authorization: Bearer $API_KEY"

DELETE /api-keys/:id auth required

Revoke an API key. Immediately invalidates it for all future requests.

Response 200

{ "ok": true, "revokedAt": "2026-01-01T12:00:00.000Z" }

cURL example

curl -s -X DELETE https://agentix.cloud/api-keys/key_xxx \
  -H "Authorization: Bearer $API_KEY"

Teams

A team is your workspace. All tasks, roles, workers, and events are scoped to a team. The CEO agent creates and reuses one team per project.

POST /teams auth required

Create a new team. One team is usually sufficient per project. Three default roles are created automatically: backend-engineer, code-reviewer, and frontend-engineer. Check existing roles with GET /roles?teamId=TEAM_ID before creating new ones.

Field	Type	Description
name	string	required
goal	string	optional High-level objective
autonomy	"supervised" \| "autonomous"	optional Default: `"supervised"`

Request body

{
  "name": "my-project",
  "goal": "Ship the MVP",
  "autonomy": "supervised"
}

Response 201

{
  "id": "team_xxx",
  "name": "my-project",
  "goal": "Ship the MVP",
  "autonomy": "supervised",
  "config": null,
  "createdAt": "2026-01-01T00:00:00.000Z"
}

cURL example

curl -s -X POST https://agentix.cloud/teams \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-project", "goal": "Ship the MVP"}'

GET /teams/:id auth required

Get team details including roles, top-level tasks, active workers, and usage summary.

Response 200

{
  "id": "team_xxx",
  "name": "my-project",
  "goal": "Ship the MVP",
  "autonomy": "supervised",
  "config": { "gitRepoUrl": "https://github.com/org/repo" },
  "roles": [...],
  "tasks": [...],
  "workers": [...],
  "usageSummary": { "totalSpawns": 12, "totalComputeMinutes": 48 }
}

cURL example

curl -s https://agentix.cloud/teams/team_xxx \
  -H "Authorization: Bearer $API_KEY"

PATCH /teams/:id auth required

Update team name, goal, autonomy, or config. All fields optional. config is merged (not replaced).

Request body

{
  "name": "new-name",
  "goal": "Updated goal",
  "config": {
    "gitRepoUrl": "https://github.com/org/repo",
    "githubToken": "ghp_xxx"
  }
}

cURL example

curl -s -X PATCH https://agentix.cloud/teams/team_xxx \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"config": {"gitRepoUrl": "https://github.com/org/repo"}}'

GET /teams/:id/playbook auth required

Get the team playbook — a freeform policy document the CEO reads before every session.

Response 200

{ "teamId": "team_xxx", "playbook": "1. Always write tests.
2. ..." }

PUT /teams/:id/playbook auth required

Set or replace the team playbook.

Request body

{ "playbook": "1. Always write tests.
2. Run npm test before pushing." }

Response 200

{ "ok": true }

GET /teams/:id/github-activity auth required

Proxy to GitHub API for recent commits and open PRs. Requires gitRepoUrl and githubToken set in team config.

Response 200

{ "commits": [...], "prs": [...] }

Roles

Roles define what kind of agent is spawned for each task. Each role has a systemPrompt shaping the worker's expertise and a timeout before the worker is killed.

GET /roles?teamId=TEAM_ID auth required

List all roles for a team.

cURL example

curl -s "https://agentix.cloud/roles?teamId=team_xxx" \
  -H "Authorization: Bearer $API_KEY"

POST /roles auth required

Create a role. Workers spawned for tasks using this role name receive the given systemPrompt.

Field	Type	Description
teamId	string	required
name	string	required e.g. `backend-engineer`
systemPrompt	string	required Shapes the worker's expertise
timeout	number	optional Seconds before killed (default 600)

Request body

{
  "teamId": "team_xxx",
  "name": "backend-engineer",
  "systemPrompt": "You are a senior TypeScript backend engineer...",
  "timeout": 600
}

cURL example

curl -s -X POST https://agentix.cloud/roles \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"teamId":"team_xxx","name":"backend-engineer","systemPrompt":"You are..."}'

GET /roles/:id auth required

Get a single role by ID.

cURL example

curl -s https://agentix.cloud/roles/role_xxx \
  -H "Authorization: Bearer $API_KEY"

PATCH /roles/:id auth required

Update a role's system prompt or timeout. All fields optional.

Request body

{ "systemPrompt": "Updated instructions...", "timeout": 900 }

DELETE /roles/:id auth required

Delete a role. Does not affect tasks that already reference this role by name.

Response 200

{ "ok": true }

Tasks

Units of work assigned to a role. Status flow: backlog → ready → in_progress → review → done / failed. Only ready tasks can have workers spawned.

GET /tasks?teamId=TEAM_ID auth required

List tasks for a team with optional filtering. Returns full task detail objects including subtasks and workers.

Query param	Description
teamId	required
status	optional `backlog` `ready` `in_progress` `review` `done` `failed`
role	optional Filter by role name
parentTaskId	optional List subtasks of a specific parent

cURL example

curl -s "https://agentix.cloud/tasks?teamId=team_xxx&status=ready" \
  -H "Authorization: Bearer $API_KEY"

POST /tasks auth required

Create a task. Set status to ready to make it immediately spawnable.

Field	Type	Description
teamId	string	required
title	string	required
role	string	optional Role name — required to spawn a worker
description	string	optional Detailed task description shown to the worker
acceptCriteria	string	optional Worker verifies each criterion before completing
status	string	optional Default: `"backlog"`
priority	number	optional Integer — higher is more urgent
dependencies	string[]	optional Task IDs that must complete first

Request body

{
  "teamId": "team_xxx",
  "role": "backend-engineer",
  "title": "Add rate limiting to POST /register",
  "description": "Implement IP-based rate limiting using Redis...",
  "acceptCriteria": "1. Returns 429 after 5 attempts
2. All tests pass",
  "status": "ready",
  "priority": 1,
  "dependencies": []
}

cURL example

curl -s -X POST https://agentix.cloud/tasks \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"teamId":"team_xxx","title":"Add rate limiting","role":"backend-engineer","status":"ready"}'

GET /tasks/:id auth required

Get full task details including subtasks, workers, parent task reference, and recent events.

cURL example

curl -s https://agentix.cloud/tasks/task_xxx \
  -H "Authorization: Bearer $API_KEY"

PATCH /tasks/:id auth required

Update a task. Commonly used to change status or record output. All fields optional.

Request body

{
  "status": "ready",
  "priority": 2,
  "output": { "summary": "Done", "branch": "worker/task_xxx" }
}

DELETE /tasks/:id auth required

Cancel a task. Sets status to failed — the record is retained for auditing.

POST /tasks/:id/run auth required

Spawn a cloud worker for a task. The task must have a role assigned and be in ready status.

Errors:

400 — Task has no role, or role doesn't exist in the team
409 — Task is already in_progress

Response 200

{ "workerId": "worker_xxx", "sandboxId": "fc-xxx" }

cURL example

curl -s -X POST https://agentix.cloud/tasks/task_xxx/run \
  -H "Authorization: Bearer $API_KEY"

POST /tasks/:id/resume auth required

Resume a failed or timed-out task. Reuses the previous worker's session volume so Claude can --resume its conversation from where it left off.

Response 200

{ "workerId": "worker_yyy", "sandboxId": "fc-yyy", "resumed": true }

POST /tasks/:id/subtasks auth required

Create a child task under this task. Workers use this via MCP to break their work into tracked subtasks.

Request body

{
  "title": "Write unit tests for rate limiter",
  "description": "...",
  "createdBy": "worker:worker_xxx"
}

Response 201

{ "id": "task_yyy", "parentTaskId": "task_xxx", ... }

Workers

Ephemeral cloud instances that execute tasks. Each worker clones your repo, does the work, commits to a branch, and shuts down. Statuses: starting → running → completed / failed.

GET /workers?teamId=TEAM_ID auth required

List workers for a team. Filter by status to find running workers or review completed ones.

Query param	Description
teamId	required
status	optional `starting` `running` `completed` `failed`

cURL example

curl -s "https://agentix.cloud/workers?teamId=team_xxx&status=running" \
  -H "Authorization: Bearer $API_KEY"

GET /workers/:id auth required

Get a single worker including its associated task and recent events.

Response 200

{
  "id": "worker_xxx",
  "taskId": "task_xxx",
  "role": "backend-engineer",
  "status": "running",
  "startedAt": "2026-01-01T00:00:00.000Z",
  "completedAt": null,
  "task": { "id": "task_xxx", "title": "...", ... },
  "events": [...]
}

cURL example

curl -s https://agentix.cloud/workers/worker_xxx \
  -H "Authorization: Bearer $API_KEY"

Events

Append-only audit log. Events are emitted by the system (task status changes, worker spawns) and by workers (progress messages, completions). Never updated or deleted.

GET /events?teamId=TEAM_ID auth required

Get the activity feed for a team, ordered by timestamp descending.

Query param	Description
teamId	required
taskId	optional Filter to a specific task
type	optional Filter by event type (see below)
limit	optional Max records (default 50)
cursor	optional ISO timestamp — returns events before this time

Event types: task_created status_change worker_spawned progress task_completed task_failed message

cURL example

curl -s "https://agentix.cloud/events?teamId=team_xxx&limit=20" \
  -H "Authorization: Bearer $API_KEY"

POST /events auth required

Emit an event. Called by workers via the MCP coordination server to report progress.

Request body

{
  "teamId": "team_xxx",
  "taskId": "task_xxx",
  "workerId": "worker_xxx",
  "type": "progress",
  "actor": "worker:worker_xxx",
  "data": { "message": "Starting subtask 2 of 4" }
}

cURL example

curl -s -X POST https://agentix.cloud/events \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"teamId":"team_xxx","taskId":"task_xxx","type":"progress","actor":"worker:worker_xxx","data":{"message":"Step 2 done"}}'

Usage

Query compute usage billed to your customer account.

GET /usage auth required

Get usage records with optional filtering. Returns totals and individual records.

Query param	Description
teamId	optional Filter to a specific team
type	optional `worker_spawn` or `compute_minutes`
from	optional ISO date (inclusive)
to	optional ISO date (inclusive)

Response 200

{
  "totals": {
    "worker_spawn": 42,
    "compute_minutes": 168
  },
  "records": [...]
}

cURL example

curl -s "https://agentix.cloud/usage?teamId=team_xxx&from=2026-01-01" \
  -H "Authorization: Bearer $API_KEY"

Webhooks

Internal callbacks called by cloud workers when they finish a task. Workers authenticate with a per-task service key issued at spawn time — not your customer API key.

POST /webhooks/worker-complete service key

Called by a worker when it finishes. Sets task status to done or failed, records the summary, and marks the worker as completed.

Field	Type	Description
worker_id	string	required
task_id	string	required
status	"completed" \| "failed"	required
summary	string	required What was done (shown in dashboard)
git_pushed	boolean	optional
git_branch	string	optional e.g. `worker/task_xxx`

Request body

{
  "worker_id": "worker_xxx",
  "task_id": "task_xxx",
  "status": "completed",
  "summary": "Added rate limiting. All tests pass.",
  "git_pushed": true,
  "git_branch": "worker/task_xxx"
}

Response 200

{ "ok": true }

Error Codes

All errors return JSON with an error field describing the problem.

Code	Meaning
400	Bad request — missing required field or invalid value
401	Missing or invalid API key
403	Authenticated but not authorized — you don’t own this resource
404	Resource not found
409	Conflict — e.g. task already `in_progress`
410	Registration token expired or already claimed — restart
429	Rate limited — too many registration attempts
500	Internal server error — retry after a moment

Error response shape
{ "error": "Task is already in_progress" }