API Overview
Overview of the Squadbase API — authentication and the Agent execution endpoints.
The Squadbase API lets you run the Agent you built on Squadbase from your own systems and retrieve their results programmatically. All requests are sent to the following base URL:
https://api.squadbase.dev/v0You only ever work with two identifiers: the Agent ID (agentId) and the execution ID (executionId). Internal identifiers are never exposed.
Authentication
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.
Agent execution
Running an Agent via the API is asynchronous (fire-and-poll):
- Trigger an Agent — start a run; returns an
executionIdwithstatus: RUNNING. - Get Execution Status — poll with the
executionIdto track progress. - Get Execution Result — fetch the final output once the run is
COMPLETED.
| Method | Endpoint | Description |
|---|---|---|
POST | /agent/{agentId}/trigger | Trigger an Agent |
GET | /agent/{agentId}/executions/{executionId} | Get Execution Status |
GET | /agent/{agentId}/executions/{executionId}/result | Get Execution Result |
For a conceptual overview and use cases, see Trigger an Agent via API.
Execution object
The trigger and status endpoints return the same execution object.
Prop
Type
The API never returns internal identifiers (project, revision, thread, sandbox, or team IDs). Your only handles are agentId and executionId.
status values — an execution transitions through:
RUNNING · LEASED · CANCEL_REQUESTED · COMPLETED · FAILED · TIMED_OUT · CANCELLED
Errors
All endpoints return errors with a common envelope: { error, errorCode, message, detail }.
| HTTP | Condition |
|---|---|
400 | Request body validation failed (trigger) |
401 | x-api-key missing/invalid, IP not allowed, system key used, or target project not in scope |
422 | Agent not found / deleted, or executionId does not exist or does not belong to the agentId in the path (notFound); or Viewer permission (viewerCannotEdit) |
500 | Internal inconsistency right after sandbox creation, etc. |