Quickstart

1

Get a read key

Every request goes to https://app.squally.dev/api/v1 plus the path and carries an organization read key as Authorization: Bearer sqly_ro_…. With the key in SQUALLY_API_KEY - the variable the MCP server reads too - the first request lists the organization’s projects:

curl -H "Authorization: Bearer $SQUALLY_API_KEY" https://app.squally.dev/api/v1/projects

A read key is organization-wide (every project), created by an organization admin in Organization › Read keys, and expires after 30, 60, 90, 180 days as chosen at creation. There is no renewal: create a new key and revoke the old one. Project ingest keys (sqly_…) are refused with wrong_key_type.

2

List the organization's projects

List the organization’s projects. The projects of the key’s organization, oldest first. Start here: every other route takes a project id from this list. Cheap.

curl "https://app.squally.dev/api/v1/projects" \
  -H "Authorization: Bearer $SQUALLY_API_KEY"

The answer looks like this (invented data):

{
  "projects": [
    {
      "id": "3f7c2a91-5b8e-4d0a-9c61-2e4b7f0d8a15",
      "name": "storefront-web",
      "createdAt": "2026-06-02T09:14:00.000Z"
    },
    {
      "id": "a8d4e1c7-6f20-4b93-8e5a-1c7d3b9f0e42",
      "name": "admin-console",
      "createdAt": "2026-07-18T13:40:00.000Z"
    }
  ]
}

3

Ask about one project - here, its runs

Runs in a period, newest first - one row per logical run (a sharded CI run is one row; each job of a CI run that sets a job key is its own run, see jobKey), placed in the period and ordered by the start of its first shard (since 1.0.0-beta.13). CI and local runs both, unless source narrows it. Filter by branch, commit SHA prefix, status or source; page with the cursors. Cheap to moderate: bounded by the period’s runs.

curl "https://app.squally.dev/api/v1/projects/$PROJECT/runs" \
  -H "Authorization: Bearer $SQUALLY_API_KEY"

Next: Conventions for errors and retries, and the API reference for every endpoint.