Documentation

API Reference

v0.1.0 — Comprehensive guide for integrating with the Controle Center.

Authentication

The API uses two tiers of Bearer tokens. Both must be sent in the Authorization header.

Master API Key

Master

Full system-wide CRUD access.

Authorized for project registration, cross-project monitoring, and administrative resource manipulation.

Authorization: Bearer $MASTER_KEY

Project API Key

Scoped

Scoped to a single project.

Used by agents to manage their own context. Automatically filters lists to the project owner.

Authorization: Bearer $PROJECT_KEY

Global Parameters

All list endpoints support standard pagination via query parameters.

Parameter	Type	Default	Description
limit	Number	50	Maximum items to return (Hard Max: 200)
offset	Number	0	Number of items to skip
project_id	UUID	None	Filter by project (Master Key only)
force	Boolean	false	Enable cascading delete (Project DELETE only)

Endpoints

Projects

GET

/api/projects

List all projects with health scores.

AuthMaster

POST

/api/projects/register

Create a project and get its first API Key.

AuthMaster

GET

/api/projects/:id

Retrieve detailed project status and associated entities.

AuthMaster

PATCH

/api/projects/:id

Update project metadata or slug.

AuthMaster

POST

/api/projects/:id/rotate-key

Immediately invalidate and replace the project API key.

AuthAny

GET

/api/projects/:id/export

Download all project data as JSON or CSV (using ?format=csv).

AuthAny

DELETE

/api/projects/:id

Permanently remove a project. Use ?force=true for cascade.

AuthMaster

Execution Threads

GET

/api/threads

List logical task groupings.

AuthAny

POST

/api/threads

Define a new thread. Requires projectId for Master Key.

AuthAny

GET

/api/threads/:id

Get thread details and member tasks.

AuthAny

PATCH

/api/threads/:id

Modify thread status or description.

AuthAny

DELETE

/api/threads/:id

Remove a thread (tasks will be detached).

AuthAny

Tasks

GET

/api/tasks

Search and filter units of work.

AuthAny

POST

/api/tasks

Assign new work. Supports threadId and externalId.

AuthAny

GET

/api/tasks/:id

Get full task context, agent output, and notes.

AuthAny

PATCH

/api/tasks/:id

Update status, assignee, or output.

AuthAny

POST

/api/tasks/:id/notes

Append a human or agent note to the task history.

AuthAny

DELETE

/api/tasks/:id

Permanently delete a task record.

AuthAny

Issues

GET

/api/issues

List bugs and technical debt.

AuthAny

POST

/api/issues

Report a new finding. Requires projectId for Master Key.

AuthAny

GET

/api/issues/:id

Get issue details and event log.

AuthAny

PATCH

/api/issues/:id

Modify severity, status, or add resolution.

AuthAny

DELETE

/api/issues/:id

Remove an issue record.

AuthAny

Agents

GET

/api/agents

Global view of all registered worker instances.

AuthMaster

POST

/api/agents/register

AuthProject

PATCH

/api/agents/heartbeat

Signal vitality and current task progress.

AuthProject

DELETE

/api/agents/:id

Retire/Remove an agent instance record.

AuthMaster

Error Responses

Status	Error Code	Description
400	validation_error	Invalid JSON, missing required fields, or type mismatch.
401	unauthorized	Missing or invalid Authorization Bearer token.
403	forbidden	Valid key, but lacks permission for this specific resource.
404	not_found	The resource ID or Slug does not exist.
409	conflict	Identifier (e.g. slug) already exists or resource has dependencies.
429	rate_limited	Maximum request threshold exceeded. Check `Retry-After` header.