> ## Documentation Index
> Fetch the complete documentation index at: https://collabase.ch/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Collabase documentation. Interface labels are quoted in English, as they appear in the product.
> Features marked Enterprise need the Collabase Enterprise Edition licence.

# Automation API

> Read and control automation workspaces, flows and runs with an API token: scopes, pagination, idempotent starts and what the API does not expose.

The Automation API lets an integration list workspaces, manage flows and start and follow runs. It is part of `/api/v1`, so it uses the same tokens, the same envelope and the same errors as the rest of the API.

## Authentication and scopes

Send the token as `Authorization: Bearer cb_...`. A token acts as the person who made it and can never do more than that person.

| Scope | Allows |
| - | - |
| `automation:read` | List workspaces, flows and runs, and read one of each. |
| `automation:write` | Create, rename, delete, publish and switch flows, start runs and retry runs. |

Without a scope the answer is `403 INSUFFICIENT_SCOPE`. An unknown or expired token gets `401`. A person with the viewer role gets `403` on every change, whatever the token's scope.

## Pagination

Lists answer `{ "data": { "items": [...], "nextCursor": "..." } }`. Send `nextCursor` as `cursor` for the next page. `limit` is at most 100.

## Idempotent starts

Send an `Idempotency-Key` header, up to 200 printable characters, when you start a run. A repeat with the same key within 24 hours answers with the run of the first call and starts nothing. A call that arrives while the first is still being handled gets `409`.

## What the API does not expose

Connection values, secret store settings, OAuth apps, members, the Git connection and the AI provider are not reachable through the API.

## Endpoints

> **[List workspaces](https://collabase.ch/docs/api/automation/list-workspaces.md)**
>
> The workspaces the token owner may see.

> **[Start a run](https://collabase.ch/docs/api/automation/start-run.md)**
>
> Start a published flow with a payload.

> **[Call a webhook](https://collabase.ch/docs/api/automation/call-webhook.md)**
>
> Start a flow from another system, with or without waiting for the answer.

> **[Upload a plug](https://collabase.ch/docs/api/automation/upload-plug.md)**
>
> Install your own plug, as the plug command line tool does.

## Addresses without a token

Three addresses work without a token, because another system calls them: [the webhook address](https://collabase.ch/docs/api/automation/call-webhook.md), [its synchronous variant](https://collabase.ch/docs/api/automation/call-webhook-sync.md) and [the address of a waiting run](https://collabase.ch/docs/api/automation/resume-run.md). The flow id or the token in the address is the credential.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.