Skip to main content
The REST API gives scripts, CI jobs, and agents the same project data and actions as the dashboard. Every operation is in the OpenAPI 3.1 contract at https://api.squasher.ai/openapi.json.

​
Send your first request

The response lists the projects that the key can use. Most other paths start with /v1/projects/{project_id}.

​
Base URLs

  • https://api.squasher.ai is the REST API. GET / returns links to these docs, the OpenAPI contract, and the MCP server.
  • https://ingest.squasher.ai receives telemetry from SDKs, log drains, and OpenTelemetry. See the Ingestion API.

​
Authenticate

Send a credential on every request, in one of these headers: An API key can do only what its scopes allow. The read scope reads project data, write changes it, and narrower scopes such as errors:read or monitors:write limit a key to one resource. See API keys for the full list.
The Setup page creates ingest keys only. An ingest key has the events:ingest scope, so it can send telemetry but cannot read it. To read data, use an OAuth token, or create a key with read scopes through the API keys endpoint.
An OAuth token acts as the signed-in user, with that user’s organization role. The MCP server and the CLI get one when you sign in. Other clients can use the OAuth 2.0 authorization code flow with PKCE: register at https://mcp.squasher.ai/register, then use https://mcp.squasher.ai/authorize and https://mcp.squasher.ai/token. The access token lasts one hour.

​
Handle errors

A failed request returns an HTTP status and a JSON body. Most errors have one error field:
Some operations add fields. Safe SQL queries return a stable code in error, with message and hint. A rate-limited request returns type, code, message, retry_after, and doc_url. Branch on the HTTP status first, then on the code when there is one. Every response has an X-Request-ID header. Include it when you report a problem.

​
Rate limits

Responses carry RateLimit-Limit and RateLimit-Policy headers. A rate-limited response has status 429, a RateLimit header, and Retry-After: 60. Wait that long before you retry.

​
Paginate lists

A list operation uses one of two patterns. Its resource page and the OpenAPI contract say which.
  • Cursor. Send limit, and leave out cursor on the first request. Pass the next_cursor from each response unchanged, until it is null. Alert connector deliveries work this way.
  • Offset. Send limit and offset, and add limit to offset for the next page. Logs and traces work this way.
Keep the same filters and time window on every page.

​
Versioning

Every public path starts with /v1. Squasher adds operations, optional fields, response fields, and enum values within v1. Ignore response fields that you do not use, and check an enum value before you branch on it.

​
Find an operation

  • Find the API for a task maps each task to its operations, CLI command, and MCP availability.
  • Query guide and safe SQL tells an agent which query answers a question, and runs read-only SQL.
  • The Resources section in the sidebar has one page for each resource.

​
Next steps

Find the API for a task

Map a task to its operations.

Query guide and safe SQL

Pick the right query, or run read-only SQL.

Connect the MCP server

Call the same operations from an AI assistant.

API keys

Create keys and choose scopes.