Versioning and change policy - SQD Documentation

The Portal API carries no version in its URL. There is no /v1/, and no version header. Every client talks to the same surface at https://portal.sqd.dev, and the endpoints below are the whole of it:

curl -s https://portal.sqd.dev/datasets | head -c 120

That works because the surface grows by addition. New dataset types, new block and transaction fields, and new datasets appear without changing what an existing request means.

What you can rely on

Stable	Not stable
Endpoint paths and HTTP methods	The prose in `error.message`
The error envelope `{"error":{"type","code","message"}}`	The order of datasets in `GET /datasets`
`error.type` as a closed set of four values	The set of datasets, which grows and is occasionally pruned
`error.code` values, which stay meaningful once published	Worker assignments in `GET /datasets/{dataset}/state`
Field names in a selector once accepted

Match on error.code, never on error.message. See Error handling for the full table of types and codes.

Detecting a change

The machine-readable description of the whole API is published at openapi.json. Every operation there has a stable operationId, and the field selectors are enumerated per dataset family. That document is the one to diff in a pipeline, or to regenerate a client from. For a quick answer at a terminal, the Portal also describes itself. Send a field name it does not know and the rejection names the accepted set:

curl -s -X POST https://portal.sqd.dev/datasets/ethereum-mainnet/stream \
  -H 'content-type: application/json' \
  -d '{"type":"evm","fromBlock":1,"toBlock":1,"fields":{"block":{"nope":true}}}'

{"error":{"type":"invalid_request_error","code":"malformed_request",
 "message":"Bad request: unknown field `nope`, expected one of `number`, `hash`, `parentHash`, `timestamp`, ..."}}

The same trick works on type, which answers with every dataset family the Portal serves.

Read that list yourself; do not parse it in a client. It arrives inside error.message, which is prose and is not part of the contract, so it can be reworded at any time. Automated checks belong against openapi.json, which is versioned and structured for exactly this.

Datasets change, the API does not

The surface that moves is the dataset catalogue, not the endpoints. Datasets are added as networks are onboarded, and occasionally retired when a network is deprecated upstream or demand disappears. Retirements are announced in advance on the Announcements page and in the Telegram community, with the affected datasets named and a date. Past examples:

May 2026 gateway deprecations: Eclipse, Goerli and Fantom retired on May 21, with Fuel, Starknet and Solana following on June 1.
August 2026 dataset retirements: 67 datasets retired on August 20, with migration guidance per dataset.

To check whether a dataset is still served, call GET /datasets/{dataset}/metadata. A retired name answers 404 with error.code of unknown_dataset:

curl -s https://portal.sqd.dev/datasets/no-such-dataset/metadata

{"error":{"type":"invalid_request_error","code":"unknown_dataset","message":"Unknown dataset: no-such-dataset"}}

Watch the Announcements page rather than polling for removals. An automated consumer that treats unknown_dataset as fatal will fail on the day of a retirement it could have been warned about.

SDK versioning

The SDKs are versioned independently of the Portal, as npm packages following semantic versioning. Breaking changes land in a major release with a migration guide, and the Portal continues to serve older SDK versions: the wire format they depend on is the same additive surface described above.

Rate limits and retries

The public Portal is shared capacity. When it is at capacity it answers rate_limit_error with an overloaded code and a mandatory Retry-After header. Error handling covers the retry rules, which headers are exposed through CORS, and how x-request-id ties a report back to a single request. Authenticated and dedicated portals take an API key in the x-api-key header. The paths and payloads are identical either way. See Pricing for the access options.

​What you can rely on

​Detecting a change

​Datasets change, the API does not

​SDK versioning

​Rate limits and retries

What you can rely on

Detecting a change

Datasets change, the API does not

SDK versioning

Rate limits and retries