# Flow API Reference

Base URL: `https://flow.pixelbrain.cz/v2`

Flow exposes a public v2 API for provisioned workspaces. Use workspace-issued bearer credentials or enterprise OAuth client credentials in the `Authorization: Bearer <token>` header. Mutating JSON requests may include `Idempotency-Key` with 1 to 255 characters; stored 2xx and 4xx responses are replayed for 24 hours with `Idempotency-Replayed: true`. 5xx responses are not stored.

## Headers

- `Authorization: Bearer <token>` for API access.
- `Content-Type: application/json` for JSON requests.
- `Idempotency-Key` on POST, PATCH, PUT, and DELETE JSON operations when retrying safely.
- Rate limit responses include `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`, and `Retry-After`.

## Errors

v2 errors are JSON objects with `error` and optional `message`. Common status codes are 401 unauthorized, 403 forbidden, 404 not found, 409 conflict, 429 rate limit, and 500 internal error.

## Endpoint Groups

- Agents: `/v2/teams/{teamId}/agents`, `/v2/agents/{agent_id}`, revisions, schedules, memory files, evaluation rubrics, and case triggers.
- Runs: `/v2/teams/{teamId}/runs`, `/v2/runs/{run_id}`, `/v2/runs/{run_id}/messages`, stop, and human-request response.
- Queues: `/v2/teams/{teamId}/queues`, `/v2/queues/{queue_id}/cases`, case labels, bulk actions, and queue agents.
- Sandboxes: `/v2/sandboxes`, upload URLs, and sandbox files.
- Artifacts: `/v2/artifacts`, render/export, messages, revisions, connections, refresh, publish, duplicate, answer, and stop.
- Connections: native OAuth, MCP OAuth, Composio finalize, connection CRUD, and public plugin catalog.
- MCP: `POST /v2/mcp` streamable-http JSON-RPC endpoint.
- Webhooks: `/v2/teams/{teamId}/webhooks` and `/v2/teams/{teamId}/webhook-secret`.

Async work returns an accepted or created resource. For runs, poll `GET /v2/runs/{run_id}` until the status is `completed`, `failed`, or `stopped`.