---
title: "Shire Automations API versioning and usage"
description: "API versions, pagination, safe retries, rate limits, and deprecation policy."
canonical: "https://shireautomations.com/api-versioning.md"
last-updated: "2026-10-21"
---

# Shire Automations API versioning and usage

## Versioning and deprecation

The public API uses major versions in its URL paths. Current endpoints use `/api/v1`. Additive fields and optional parameters may be added within a major version. Breaking changes use a new major version.

We will give at least six months' notice before removing a supported API version. When a resource is deprecated, its responses will include the `Deprecation` header and a link to migration details. Once a removal date is set, responses will also include the `Sunset` header.

## Rate limits and retries

The public API allows 60 requests per minute per source IP. Responses include `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset`. A `429` response includes `Retry-After`; wait that long before retrying. Source-IP request counts stay in server memory. Synchronous inputs and results are not stored. Async jobs store input and result for up to 15 minutes, with one-way source-IP, Idempotency-Key, and input hashes until expiry. Async-job capacity is limited to 20 unexpired jobs per source IP and 2,000 across the service.

## Pagination

`GET /api/v1/tools` accepts `limit` from 1 to 100 and an opaque `cursor`. Read `pagination.nextCursor` from each response and send it as the next request's `cursor`. A null cursor means there are no more results.

## Safe retries and asynchronous work

Planning calls calculate results without running business workflows. Synchronous calls do not store request bodies or results. `POST /api/v1/tools/{slug}` accepts an optional `Idempotency-Key` for correlation.

To request asynchronous processing, send `Prefer: respond-async` and an `Idempotency-Key` to `POST /api/v1/tools/{slug}`. The API returns `202 Accepted`, a `Location` header, and a body with `jobId` and `statusUrl`. Poll the status URL until the job is `completed` or `failed`. Jobs expire after 15 minutes; each source IP can have up to 20 unexpired jobs, with 2,000 unexpired jobs across the service. Anyone with the status URL can read the result, so keep the link private. Reusing a key with the same input returns the same job. Use a new key when input changes.

See the [OpenAPI specification](https://shireautomations.com/openapi.json) and [developer resources](https://shireautomations.com/developers).