API Overview
Overview of the Squadbase API — authentication and the Automation run endpoints.
The Squadbase API lets you run the Automations you built in Squadbase from your own systems, and read their status and results programmatically. Send all requests to the following base URL.
https://api.squadbase.dev/v0Authentication
Every request is authenticated with a user-issued API key passed in the x-api-key header. See Authentication for how to create a key and the authorization rules.
Running an Automation
Running an Automation via the API is asynchronous (fire-and-poll):
- Run an Automation — start a run; returns an
executionIdwithstatus: RUNNING. - Get Execution Status — poll with the
executionIdto track progress. - Get Execution Result — fetch the result once the run is
COMPLETED.
| Method | Endpoint | Description |
|---|---|---|
POST | /automation/{projectId}/{automationName}/trigger | Run an Automation |
GET | /automation/{projectId}/{automationName}/executions/{executionId} | Get Execution Status |
GET | /automation/{projectId}/{automationName}/executions/{executionId}/result | Get Execution Result |
For a conceptual overview and use cases, see Run via the API.
Execution object
The run and status endpoints return the same execution object.
Prop
Type
The API never returns internal identifiers (sandbox, team, and so on). Your only handles are projectId, automationName, and executionId.
status values
| Value | Meaning |
|---|---|
RUNNING | Waiting to start, or running |
LEASED | Running |
CANCEL_REQUESTED | A stop was requested and the run is stopping |
COMPLETED | Succeeded |
FAILED | Failed |
TIMED_OUT | Failed after exceeding the time limit (3 hours) |
CANCELLED | Stopped |
COMPLETED, FAILED, TIMED_OUT, and CANCELLED are final states.
Errors
All endpoints return errors with a common envelope: { error, errorCode, message, detail }.
| HTTP | Condition |
|---|---|
400 | Request body validation failed, or Idempotency-Key is longer than 128 characters (run) |
401 | x-api-key missing/invalid, IP not allowed, system key used, or the project is outside the key's scope |
402 | AI credit balance is 0 (run) |
422 | Automation not found; executionId does not exist or does not belong to the Automation in the path; Viewer permission (viewerCannotEdit); or the same Automation is already running (runAlreadyActive) |
429 | API run rate limit exceeded (run). Wait for the number of seconds in the Retry-After header, then retry |
500 | The run environment could not be started, etc. |
API runs are limited to 60 per hour per team (the limit varies by plan).