API reference

All endpoints are relative to https://cadence.alen.world/api/v1 and require a Pro or Enterprise API key unless noted. Read REST conventions first for the envelope, error shapes and rate limits.

Health#

Liveness check. Returns the API version and server time. Useful as an uptime monitor target.

Users#

Get the current identity#

Returns the profile of the user who owns the API key: id, name, email, avatarUrl, role, department, systemRole, teamId and agent.

Call this first when setting up an integration — it confirms the key works and tells you which team and identity your writes will be attributed to.

Projects#

List projects#

Every project in the team, each with its project manager, phase statuses and tags.

Create a project#

namestringRequired

The project name.

descriptionstring

Free text. Used by AI task refinement when a template is applied.

startDatedate

YYYY-MM-DD.

deadlinedate

YYYY-MM-DD.

projectManagerIduuid

A profile in your team. Defaults to the key's owner. If it references a connected agent, an agent run is queued — which requires a paid plan.

templateIduuid

Template to record against the project.

Returns 201 with the created project.

Get a project#

The full object: project manager, team members, every phase with its tasks and assignees, and tags. This is the one call to make when you need a project's whole tree — fetching phases and tasks separately costs more requests for the same data.

Update a project#

Accepts name, description, status, startDate, deadline and projectManagerId. Only the fields you send are changed.

Setting projectManagerId to null or "" clears it. Setting it to an agent queues a run for that agent.

Delete a project#

Deletes the project and everything under it. Returns 204.

List a project's phases#

Phases in order, each with the ids and statuses of its tasks.

List a project's team#

Profiles on the project team, including their role, department and whether each is an agent.

Phases#

Get a phase#

The phase with its parent project and its full list of gate criteria.

Update a phase#

Accepts name, description, status, startDate and deadline.

List a phase's tasks#

Every task in the phase, with assignees.

Tasks#

Create a task#

phaseIduuidRequired

The phase to create the task in. Must belong to your team.

titlestringRequired

What has to be done.

descriptionstring

The detail.

prioritylow | medium | high | critical

Defaults to medium.

assigneeIduuid

A profile in your team. Assigning a connected agent queues a run and requires a paid plan.

deadlinedate

YYYY-MM-DD.

estimatedHoursnumber

Effort estimate.

Returns 201 with the created task and its assignee.

Get a task#

The task with its assignee, its phase, that phase's project, and its required skills.

Update a task#

Accepts title, description, status, priority, assigneeId, deadline and estimatedHours.

Valid statuses: not-started, in-progress, blocked, review, completed, cancelled. These are validated — anything else returns 400. Send assigneeId as null or "" to unassign.

Delete a task#

Returns 204.

Search tasks#

Search across the whole team, with every filter optional and combined with AND.

querystring

Case-insensitive substring match on the task title.

statusstring

Exact status match.

prioritystring

Exact priority match.

assigneeIduuid

Tasks assigned to this profile.

projectIduuid

Tasks anywhere in this project.

phaseIduuid

Tasks in this phase.

Returns up to 100 tasks, each with its assignee, phase and project. There is no pagination — narrow the filters if you are hitting the ceiling.

curl -X POST https://cadence.alen.world/api/v1/tasks/search \
  -H "Authorization: Bearer $CADENCE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "blocked", "priority": "critical" }'

Attachments#

Attach a link to a task#

Records an attachment that points at a file hosted elsewhere. Use this to surface a document from your DMS, drive or wiki on the task, without uploading it.

filenamestringRequired

Display name.

urlstringRequired

Must be a valid absolute URL.

typestringRequired

MIME type, e.g. application/pdf.

sizenumberRequired

Size in bytes. Must be zero or greater.

Returns 201. Uploading actual files is done through the interface.

Comments#

List comments#

Both query parameters are required. entity_type is one of task, phase, project or tag. Returns comments oldest first, each with its author.

Create a comment#

entityTypetask | phase | project | tagRequired

What is being commented on.

entityIduuidRequired

The id of that entity.

contentstringRequired

The comment body.

The comment is attributed to the user who owns the API key. Returns 201.

Templates#

List templates#

Every template in the team, with its phases and the tasks inside them, ordered by name. Read-only — templates are authored in the interface.

Webhooks#

Full detail, including signature verification, is on the webhooks page.

List endpoints#

Registered endpoints with their url, subscribed events and isActive flag. Secrets are never returned here.

Create an endpoint#

urlstringRequired

Absolute URL to deliver to.

eventsstring[]Required

At least one of task.created, task.updated, task.deleted, phase.status_changed, project.created, project.updated, comment.created. Any unrecognised value rejects the whole request.

Returns 201 including the generated secret — the only time it is ever returned. Store it; you need it to verify signatures.

Update an endpoint#

Accepts url, events and isActive. Set isActive to false to pause deliveries without losing the endpoint or its secret.

Delete an endpoint#

Returns 204.

Agents#

Agents require a paid plan; creating, updating and deleting them additionally requires an admin identity. See AI agents.

List agents#

Create an agent#

namestringRequired

Display name. This is what appears in assignee pickers.

descriptionstring

What the agent is for.

mcpUrlstringRequired

The agent's MCP endpoint. Must be a valid URL.

mcpAuthTokenstring

Sent as a bearer token when cadence. connects to that endpoint.

Creates the agent and a team profile for it, so it can be assigned work like a person. Returns 201.

Get, update and delete an agent#

PATCH accepts name, description, mcpUrl, mcpAuthToken and status (active or paused). Deleting an agent also removes its team profile.

List an agent's runs#

Runs newest first. limit defaults to 50 and is capped at 200.

Test an agent's connection#

Connects to the agent's MCP endpoint and issues a trivial call. Returns { "data": { "ok": true } } on success, or 400 with the underlying connection error.

Retry a run#

Re-queues a failed run.