Getting started

This walks you through your first task over the HTTP API: you authenticate, confirm who you are, create a task, read it back, move it to another stage, and see the record of what you did. Each step names what it needs before it.

Throughout, replace https://cadence.example.com with the address of your Cadence instance, and OPS with your space's key.

Before you start

You need:

An account on a Cadence instance, signed in to the web interface.
Member access to a space that has a workflow with more than one stage. Your role decides what you can do; creating and moving tasks needs member. See Authentication.

If no workflow in your space has more than one stage yet, it has to be set up first, and that needs admin: a new workflow starts with a single empty stage group and no stages, and adding stages needs admin. See Workflows and stages for how workflows and stages are created. As a member, you rely on an admin having done this before you begin here.

1. Get an API token

In the web interface, open /settings/api_tokens/new and create a token. The full smc_… value is shown once, at creation — copy it now, because it is not shown again.

Keep it in an environment variable so the commands below can use it:

export CADENCE_TOKEN="smc_your_token_here"

2. Confirm who you are

Check that the token works and see your identity:

curl https://cadence.example.com/api/v1/whoami \
  -H "Authorization: Bearer $CADENCE_TOKEN"

{ "user": { "id": 4021, "email": "you@example.com" } }

If this returns 401, the token is missing or wrong — see when a token is missing or wrong.

Signing in with the command-line client

If you will work from a terminal, the command-line client is a shorter path than exporting a token on every shell. It assumes the cadence client is already installed and on your PATH. If it is not, open the user menu in the web interface (the avatar at the right of the top navigation) and choose Download CLI. That item appears only on an instance that offers the client for download. The page it opens lists the file for each kind of machine and the commands that put it on your PATH. Over MCP, cli_releases_get returns the same download links. If the item is not there, get the client from whoever operates your instance. Sign in once with the same smc_ token — it is verified against the server before it is saved, then held as a profile in ~/.cadence/config.json:

cadence login --url https://cadence.example.com

Confirm who you are:

cadence whoami

you@example.com (id 4021)

From then on the client uses that saved login. The rest of this walkthrough stays on the HTTP API: creating, reading, and moving a task is done over the API or in the web interface, not from the client. The client signs you in and lets you inspect leases and read and write task attachments — see the command-line client for its full command set.

3. Create a task

A create call must carry an Idempotency-Key header, so that retrying it cannot create a second task. Choose any unique value for the key.

curl -X POST https://cadence.example.com/api/v1/spaces/OPS/tasks \
  -H "Authorization: Bearer $CADENCE_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-first-task" \
  -d '{ "title": "My first task", "priority": "P2" }'

The task comes back with its KEY-N id and the stage it landed on — a new task starts on the workflow's default stage:

{
  "task": {
    "key": "OPS-42",
    "space": "OPS",
    "title": "My first task",
    "priority": "P2",
    "stage": "Backlog",
    "workflow": { "slug": "delivery", "name": "Delivery" },
    "gate_status": "open"
  }
}

Note the key — you address the task by it from here on. The examples below use OPS-42; use your own.

4. Read it back

curl https://cadence.example.com/api/v1/tasks/OPS-42 \
  -H "Authorization: Bearer $CADENCE_TOKEN"

This returns the full task. A key that does not exist returns 404 and task_not_found.

5. Move it to another stage

Move the task to another stage on its workflow by name. Use a stage that exists on your workflow:

curl -X POST https://cadence.example.com/api/v1/tasks/OPS-42/transition \
  -H "Authorization: Bearer $CADENCE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "stage": "In progress" }'

If the stage does not exist on the workflow, the move is refused with unknown_stage and no stage named "In progress" on this workflow. If the stage has a rule that gates entry — a required check, say — the move is refused and the message says which; see Stage rules.

6. See what happened

The task's timeline records each change. Read it from the task's page in the web interface, or over MCP with the activities_list tool (pass task_key), which returns the entries newest-first. See Tasks.

Where to go next

To understand what a workflow, stage, and task are before configuring your own, read Workflows, stages, and tasks.
To have a pool work tasks for you, follow Staff a stage with a pool.
To gate a stage so work is checked before it moves on, follow Gate a stage with checks.

From a terminal, the command-line client signs you in and lets you inspect the leases in your space and read and write task attachments.

On this page