# Workflows

The workflows a project's app defines, and their runs: start, read, cancel and retry.

Source: https://docs.orbits.africa/api/workflows

Workflows are defined in your app's code with `@useorbits/workflows`; these routes list them and their runs, start a run, and cancel or retry one. See [Workflows](https://docs.orbits.africa/features/workflows).

Endpoints:

- `GET /v1/teams/{team}/projects/{project}/workflows`: A project's workflows and recent runs
- `POST /v1/teams/{team}/projects/{project}/workflows/{workflow}/runs`: Run a workflow now
- `GET /v1/teams/{team}/projects/{project}/workflows/runs/{run}`: One run and its steps
- `POST /v1/teams/{team}/projects/{project}/workflows/runs/{run}/cancel`: Cancel a running run
- `POST /v1/teams/{team}/projects/{project}/workflows/runs/{run}/retry`: Retry a failed run from the step that failed

## The workflow run object



- `id` (string, required)
- `workflow` (string, required)
- `state` (string, required): One of `running`, `succeeded`, `failed`, `canceled`.
- `trigger` (string, required): One of `schedule`, `event`, `manual`.
- `trigger_text` (string, required)
- `started_by` (FlagPerson or null, required): Who pressed Run now; null for a schedule or an event.
  - `id` (string, required)
  - `name` (string, required)
  - `email` (string, required)
  - `avatar_url` (string or null, required)
- `started_at` (string, required)
- `finished_at` (string or null, required)
- `seconds` (integer, required): From start to finish, or so far.
- `deployment` (object, required)
  - `id` (string, required)
  - `sha` (string or null, required)
- `input` (object, required): The JSON it started with.
- `output` (object, required): What the workflow returned.
- `error` (array of string, required)
- `attempts` (string, required)
- `next_at` (string or null, required): When the app is called for it next.
- `steps` (array of WorkflowStep, required)
  - `name` (string, required)
  - `kind` (string, required): One of `step`, `sleep`, `wait`.
  - `state` (string, required): One of `running`, `succeeded`, `failed`, `waiting`, `skipped`, `canceled`.
  - `seconds` (integer or null, required): Time spent running over every attempt; null for one not reached.
  - `detail` (string, required)
  - `error` (array of string, required): The last attempt's error: message, then where.
  - `attempts` (integer, required)
  - `retried_by` (FlagPerson or null, required)
    - `id` (string, required)
    - `name` (string, required)
    - `email` (string, required)
    - `avatar_url` (string or null, required)
  - `wake_at` (string or null, required): A sleep's end, or a wait's timeout.
  - `event` (string or null, required): What a wait waits for.
  - `output` (object, required): The step's result; a wait's is the event's data.
## A project's workflows and recent runs

```http
GET /v1/teams/{team}/projects/{project}/workflows
```

The Workflows page. `workflows` are what the production deployment's `@useorbits/workflows` lists, read once it went live: each with its trigger as the page says it ("Every 15 minutes", "When order.paid happens"), its last run, and the share of its finished runs in the last 7 days that succeeded (null without any). `runs` are the 50 newest, each with its steps.

A run's steps are the `step()`, `sleep()` and `waitFor()` calls it reached, in order. A step `running` with an `error` failed an attempt and is waiting for its retry (`next_at`). Steps the workflow took on its last successful run that this run hasn't reached are listed after them: `waiting` while it runs, `skipped` once it failed or was canceled.

**Permissions:** Any team member. A non-member gets 404.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/workflows" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "workflows": [
    {
      "name": "my-app",
      "description": "description",
      "schedule": null,
      "event": null,
      "retries": 1,
      "trigger_text": "trigger-text",
      "last_run": {
        "id": "id",
        "state": "running",
        "at": "2026-11-10T09:30:00Z"
      },
      "success_rate": null
    }
  ],
  "runs": [
    {
      "id": "id",
      "workflow": "sync-stock",
      "state": "running",
      "trigger": "schedule",
      "trigger_text": "Every 15 minutes",
      "started_by": {
        "id": "id",
        "name": "my-app",
        "email": "ada@example.com",
        "avatar_url": "https://my-app.theorbits.app"
      },
      "started_at": "2026-11-10T09:30:00Z",
      "finished_at": "2026-11-10T09:30:00Z",
      "seconds": 1,
      "deployment": {
        "id": "id",
        "sha": null
      },
      "input": null,
      "output": null,
      "error": [
        "error"
      ],
      "attempts": "3 on step 3",
      "next_at": "2026-11-10T09:30:00Z",
      "steps": [
        {
          "name": "update-inventory",
          "kind": "step",
          "state": "running",
          "seconds": null,
          "detail": "Gave up after 3 attempts",
          "error": [
            "error"
          ],
          "attempts": 1,
          "retried_by": {
            "id": null,
            "name": null,
            "email": null,
            "avatar_url": null
          },
          "wake_at": "2026-11-10T09:30:00Z",
          "event": null,
          "output": null
        }
      ]
    }
  ]
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
## Run a workflow now

```http
POST /v1/teams/{team}/projects/{project}/workflows/{workflow}/runs
```

Starts a run on the production deployment with `input` (any JSON, 256 KB at most), as Run now does. The builder picks it up within seconds.

**Permissions:** Owners, admins and members. Viewers get 403. 404 when the production deployment doesn't list the workflow; 409 without a production deployment.

Token: a `full` API token. Send an `Idempotency-Key` header.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `workflow`

Body:

- `input` (object): Any JSON.

Example:

```sh
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/workflows/send-welcome-email/runs" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "input": null
  }'
```

Response `201`:

```json
{
  "id": "id",
  "workflow": "sync-stock",
  "state": "running",
  "trigger": "schedule",
  "trigger_text": "Every 15 minutes",
  "started_by": {
    "id": "id",
    "name": "my-app",
    "email": "ada@example.com",
    "avatar_url": "https://my-app.theorbits.app"
  },
  "started_at": "2026-11-10T09:30:00Z",
  "finished_at": "2026-11-10T09:30:00Z",
  "seconds": 1,
  "deployment": {
    "id": "id",
    "sha": null
  },
  "input": null,
  "output": null,
  "error": [
    "error"
  ],
  "attempts": "3 on step 3",
  "next_at": "2026-11-10T09:30:00Z",
  "steps": [
    {
      "name": "update-inventory",
      "kind": "step",
      "state": "running",
      "seconds": null,
      "detail": "Gave up after 3 attempts",
      "error": [
        "error"
      ],
      "attempts": 1,
      "retried_by": {
        "id": "id",
        "name": "my-app",
        "email": "ada@example.com",
        "avatar_url": "https://my-app.theorbits.app"
      },
      "wake_at": "2026-11-10T09:30:00Z",
      "event": null,
      "output": null
    }
  ]
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `409`: The request conflicts with current state.
- `422`: Validation failed, or the Idempotency-Key was reused with a different body.
## One run and its steps

```http
GET /v1/teams/{team}/projects/{project}/workflows/runs/{run}
```

**Permissions:** Any team member.

Token: any API token (`read` or `full`).

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `run`

Example:

```sh
curl "https://api.theorbits.app/v1/teams/my-team/projects/my-app/workflows/runs/run_01jc8x6e4mq2v7r9y3t5b0zp8w" \
  -H "Authorization: Bearer $ORBITS_TOKEN"
```

Response `200`:

```json
{
  "id": "id",
  "workflow": "sync-stock",
  "state": "running",
  "trigger": "schedule",
  "trigger_text": "Every 15 minutes",
  "started_by": {
    "id": "id",
    "name": "my-app",
    "email": "ada@example.com",
    "avatar_url": "https://my-app.theorbits.app"
  },
  "started_at": "2026-11-10T09:30:00Z",
  "finished_at": "2026-11-10T09:30:00Z",
  "seconds": 1,
  "deployment": {
    "id": "id",
    "sha": null
  },
  "input": null,
  "output": null,
  "error": [
    "error"
  ],
  "attempts": "3 on step 3",
  "next_at": "2026-11-10T09:30:00Z",
  "steps": [
    {
      "name": "update-inventory",
      "kind": "step",
      "state": "running",
      "seconds": null,
      "detail": "Gave up after 3 attempts",
      "error": [
        "error"
      ],
      "attempts": 1,
      "retried_by": {
        "id": "id",
        "name": "my-app",
        "email": "ada@example.com",
        "avatar_url": "https://my-app.theorbits.app"
      },
      "wake_at": "2026-11-10T09:30:00Z",
      "event": null,
      "output": null
    }
  ]
}
```

Errors:

- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
## Cancel a running run

```http
POST /v1/teams/{team}/projects/{project}/workflows/runs/{run}/cancel
```

The app isn't called for it again; a step already running finishes, and its result is dropped. 409 for a run that isn't running.

**Permissions:** Owners, admins and members.

Token: a `full` API token. Send an `Idempotency-Key` header.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `run`

Example:

```sh
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/workflows/runs/run_01jc8x6e4mq2v7r9y3t5b0zp8w/cancel" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
```

Response `200`:

```json
{
  "id": "id",
  "workflow": "sync-stock",
  "state": "running",
  "trigger": "schedule",
  "trigger_text": "Every 15 minutes",
  "started_by": {
    "id": "id",
    "name": "my-app",
    "email": "ada@example.com",
    "avatar_url": "https://my-app.theorbits.app"
  },
  "started_at": "2026-11-10T09:30:00Z",
  "finished_at": "2026-11-10T09:30:00Z",
  "seconds": 1,
  "deployment": {
    "id": "id",
    "sha": null
  },
  "input": null,
  "output": null,
  "error": [
    "error"
  ],
  "attempts": "3 on step 3",
  "next_at": "2026-11-10T09:30:00Z",
  "steps": [
    {
      "name": "update-inventory",
      "kind": "step",
      "state": "running",
      "seconds": null,
      "detail": "Gave up after 3 attempts",
      "error": [
        "error"
      ],
      "attempts": 1,
      "retried_by": {
        "id": "id",
        "name": "my-app",
        "email": "ada@example.com",
        "avatar_url": "https://my-app.theorbits.app"
      },
      "wake_at": "2026-11-10T09:30:00Z",
      "event": null,
      "output": null
    }
  ]
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `409`: The request conflicts with current state.
## Retry a failed run from the step that failed

```http
POST /v1/teams/{team}/projects/{project}/workflows/runs/{run}/retry
```

The steps before the failed one keep their results; the failed one runs again with a fresh set of attempts, and the run goes on from there. 409 for a run that didn't fail.

**Permissions:** Owners, admins and members.

Token: a `full` API token. Send an `Idempotency-Key` header.

Path parameters:

- `team`: Team slug or `team_` id.
- `project`: Project slug or `prj_` id.
- `run`

Example:

```sh
curl -X POST "https://api.theorbits.app/v1/teams/my-team/projects/my-app/workflows/runs/run_01jc8x6e4mq2v7r9y3t5b0zp8w/retry" \
  -H "Authorization: Bearer $ORBITS_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
```

Response `200`:

```json
{
  "id": "id",
  "workflow": "sync-stock",
  "state": "running",
  "trigger": "schedule",
  "trigger_text": "Every 15 minutes",
  "started_by": {
    "id": "id",
    "name": "my-app",
    "email": "ada@example.com",
    "avatar_url": "https://my-app.theorbits.app"
  },
  "started_at": "2026-11-10T09:30:00Z",
  "finished_at": "2026-11-10T09:30:00Z",
  "seconds": 1,
  "deployment": {
    "id": "id",
    "sha": null
  },
  "input": null,
  "output": null,
  "error": [
    "error"
  ],
  "attempts": "3 on step 3",
  "next_at": "2026-11-10T09:30:00Z",
  "steps": [
    {
      "name": "update-inventory",
      "kind": "step",
      "state": "running",
      "seconds": null,
      "detail": "Gave up after 3 attempts",
      "error": [
        "error"
      ],
      "attempts": 1,
      "retried_by": {
        "id": "id",
        "name": "my-app",
        "email": "ada@example.com",
        "avatar_url": "https://my-app.theorbits.app"
      },
      "wake_at": "2026-11-10T09:30:00Z",
      "event": null,
      "output": null
    }
  ]
}
```

Errors:

- `403`: Authenticated but not allowed in this team.
- `404`: Not found, or not visible to the caller (the two are indistinguishable on purpose).
- `409`: The request conflicts with current state.
