/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 asAuthorization: Bearer cb_.... A token acts as the person who made it and can never do more than that person.
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. The cursor holds the position of the last item, so items that arrive between two requests never shift a page. A cursor that Collabase does not recognise answers 422. Runs come newest first.
Idempotent starts
Send anIdempotency-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.
Errors
Errors use the envelope{ "error": { "code": "...", "message": "..." } }. Besides the common ones (401, 403, 404, 422), these matter for Studio:
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
The Spaces the token owner may see.
Start a run
Start a published flow with a payload.
Call a webhook
Start a flow from another system, with or without waiting for the answer.
Test a webhook
Save a call as sample data without starting a run.
Receive app events
The fixed address that an app sends its events to.
Upload a plug
Install your own plug, as the plug command line tool does.