Spaces, teams, and tags

A space is the top-level container for your work: its workflows, stages, pools, rules, and tasks. Teams group a space's workflows, and tags are a controlled vocabulary applied to tasks. This page is the reference for all three.

See Authentication for the role each level needs. Replace https://cadence.example.com with your instance's address.

Spaces

You create and edit a space in the web interface: GET/POST /spaces to list and create, GET/PATCH /spaces/:id to view and update. A space has a name and a key. The key is 2–10 uppercase letters or digits, starting with a letter, and becomes the prefix of every task's KEY-N id.

Once a space has any tasks, its key is locked: an attempt to change it is refused with cannot change once tasks have been created.

Over MCP you can list and archive spaces:

spaces_list returns the spaces you belong to. Needs read.
spaces_archive and spaces_unarchive soft-archive and restore a space. Both need admin, and both are idempotent.

Creating and updating a space is web-only; there is no MCP tool or /api/v1 route for it. An archived space is read-only — every write into it is refused except restoring it — and its automation freezes; its contents are preserved.

Space settings

The web interface groups a space's settings into sections at /spaces/:id/settings/:section: general, teams, task_types, tags, checks, credentials, integrations, and contacts. Each is the assembly point for the surface documented elsewhere in this reference.

Max vCPU

Space → Settings → General carries a Max vCPU field (space[max_vcpus]): a space-wide ceiling on how much processor may run at once across all of this space's pools, measured in vCPU. Like the space's name and key, it is set in the browser by an admin — there is no MCP tool or /api/v1 route for it.

The ceiling is counted in vCPU rather than in a count of leases. A lease is admitted only when its whole size — the agent it runs plus every sidecar alongside it — fits under the free vCPU the space has left. So one large lease and several small ones may sit under the same ceiling.

Leave it blank for no space limit.
Set it to 0 to admit nothing new — no lease in the space dispatches while the ceiling is zero.
A negative number is rejected, with must be greater than or equal to 0.

The field accepts any whole number of vCPU that is zero or greater. Cadence capacity tiers are sold in vCPU — 16, 48, 128, and 256 — so those are the values you will usually set, but the field itself is not restricted to them.

The ceiling governs dispatch: when the space has no free vCPU for a matching lease's whole size, that lease stays pending rather than being dropped, and the space admits each waiting lease in turn as running work finishes and frees vCPU. What the ceiling does to a task, and how you tell a lease is waiting on it, is described in What moves a task without a person.

Changing the value is recorded. Under the field, a Max vCPU — history list shows the last five changes — each as the old value (or no limit) → the new value, with who changed it and when.

Export a space

MCP space_export produces a portable JSON reference of a space's workflows and everything they depend on. Pass space_key and a non-empty workflow_slugs list. Needs read — any member.

{
  "schema_version": "2.0",
  "space": { "key": "OPS", "name": "Operations" },
  "task_types": [ … ],
  "checks": [ … ],
  "images": [ … ],
  "agent_skills": [ … ],
  "workers": [ … ],
  "pools": [ … ],
  "rules": { "assignment": [ … ], "check": [ … ], "sentinel": [ … ], "resolution": [ … ], "property": [ … ] },
  "workflows": [ … ]
}

The export is schema_version 2.0. It names objects by their stable keys — workflow and task-type slugs, check codes, image references, stage and stage-group names — and never by internal database ids. It is a reference document you read to replicate a space's configuration by issuing the normal writes; there is no machine import that applies it back.

Every rule in the export carries a scope that always names its workflow by slug, and may narrow it by stage, task_type, and tag. An unknown slug in workflow_slugs is refused with unknown workflow slug "<slug>", and nothing is exported.

An exported agent worker version carries llm_vendor and effort when they are set, and omits each when it is not. A version exported without llm_vendor was made before vendors were required; to re-create it you must choose a vendor, because a draft without one is refused (see Fleet § Choosing a vendor, model and effort).

Teams

A team groups the workflows in a space. MCP teams_create, teams_update, teams_delete, teams_get, teams_list, teams_archive, teams_unarchive; the web interface (with reorder and workflow-move). Listing and getting need read; the rest need admin.

A team has a name, a slug unique within the space, and a position. Every space has a Default team, and every workflow belongs to a team. Archiving a team is refused while it still has active workflows, with cannot archive a team that still has workflows — move them to another team first. Deleting a team is refused while it has any workflows, with team has workflows — move them to another team first.

Tags

Tags are a per-space vocabulary applied to tasks and referenced by rules. MCP tags_create, tags_update, tags_get, tags_list, tags_delete, tags_merge; GET/POST /api/v1/spaces/:space_key/tags and GET/PATCH .../tags/:id; the web interface. Listing and getting need read; creating, updating, deleting, and merging need admin.

A tag's name is unique within the space, is trimmed of surrounding whitespace, and may be up to 100 characters.

Deleting and merging a tag guard against orphaning a rule, and against silently widening a workflow WIP constraint. A WIP constraint caps how many tasks a set of stages on a workflow may hold, and it can filter what it counts by tag (see WIP constraints). A constraint with an empty tag set counts any label, so quietly detaching a tag from one would widen the cap rather than narrow it — a change no one asked for. So a tag a constraint uses as a label filter is held in place, the same way a tag a rule uses is.

tags_delete deletes a tag that no task, no rule and no constraint uses. If tasks use it but no rule and no constraint does, it returns confirmation_required with a count; retry with confirm: true to detach it from those tasks and delete it. Two kinds of reference block the delete outright, and confirm: true does not override either — the reference must be rewired or removed first:
- If any rule references it, the delete is refused with a message that begins tag is referenced by rules and cannot be deleted: and then lists each referencing rule by type, id, and stage.
- If any WIP constraint uses it as a label filter, the delete is refused with a message that begins tag is used as a label filter by constraints and cannot be deleted: and then lists each constraint as #id (name). This block is checked before the task-count tier, so a constraint-referenced tag is never offered confirmation.
tags_merge moves every task carrying the source tag onto the target tag, then deletes the source. It has no confirm input — naming the target is the acknowledgement, and task links are moved, not lost. It is refused with source and target must be different tags when they are the same, and with source and target must be in the same space across spaces. Two kinds of reference on the source tag block the merge outright; when either does, the whole merge is rolled back and nothing changes:
- When a rule references the source, it is refused with a message that begins source tag is referenced by rules and cannot be merged: and then lists each referencing rule by type, id, and stage.
- When a WIP constraint uses the source as a label filter, it is refused with a message that begins source tag is used as a label filter by constraints and cannot be merged: and then lists each constraint as #id (name).

Deleting and merging are also available in the web interface, under Space settings → Tags (the tags section above). Deleting a tag that tasks carry shows a confirm dialog naming the affected-task count before it detaches the tag and deletes it. A delete or merge blocked by a rule or a constraint shows a Cannot delete (or Cannot merge) dialog listing what references the tag — the referencing rules, or the referencing constraints (#id and name) when a constraint blocks — which must be rewired or removed there first. This dialog has no force control: a rule or constraint block cannot be overridden from the browser, and there is no override over MCP either.