Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.augustus.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The API uses date-based versioning to manage breaking changes. When a breaking change is introduced, a new version is released with a date identifier (e.g. 2026-05-01). Your integration continues working on its current version until you explicitly upgrade. Additive changes (new fields, new enum values, new endpoints) are not versioned and are available immediately. See Forward compatibility for guidance on handling these.

​
api-version header

You can specify which API version to use on a per-request basis with the api-version header: 
curl https://api.augustus.com/v1/payouts \
  -H "Authorization: Bearer $AUGUSTUS_API_KEY" \
  -H "api-version: 2026-05-01"
If the header is omitted, the API uses the version pinned to your account. Every /v1/* response, including error responses, echoes the resolved version back in an api-version response header. Use it to confirm which version your request was actually served against. 
HTTP/1.1 200 OK
api-version: 2026-05-01
correlation-id: 7e1d4f28-3b2a-4c5d-9e8f-1a2b3c4d5e6f

​
Default version

Each merchant account is pinned to a default API version. New accounts are automatically pinned to the latest version at the time of creation. You can override the pinned version on any request by setting the api-version header. This allows you to test individual endpoints against a newer version before committing to a full upgrade.

​
Pinning the SDK

The SDK accepts an apiVersion option that is sent on every request. It can also be set via the AUGUSTUS_API_VERSION environment variable. When unset, the server falls back to the version pinned to your account. 
import Augustus from '@augustusbank/typescript-sdk'

const client = new Augustus({
  apiKey: process.env.AUGUSTUS_API_KEY,
  apiVersion: '2026-05-01',
})

​
Discovering versions

GET /v1/api_versions returns the catalogue of publicly available versions, ordered oldest to newest. The endpoint is public and requires no authentication, so you can call it from anywhere, including from a CI job that asserts your integration is on a supported version. 
curl https://api.augustus.com/v1/api_versions
Each entry includes a name, a released_at timestamp, an is_latest flag, and deprecated_at / sunset_at (both null until the version begins its deprecation cycle). See the API Versions resource in the API Reference for the full response schema.

​
Deprecation policy

  • Deprecated versions are supported for a minimum of 12 months after deprecation notice.
  • Deprecated versions return a Deprecation response header and a Sunset date so you can detect usage of old versions in monitoring.
  • New versions are released no more than quarterly.

​
Webhook versioning

Each event’s payload is serialised at the API version pinned to your account at the time the event is created. That version is carried on the wire in the envelope’s api_version field and on the Event resource. Once an event is created its api_version is fixed: retries and redeliveries always emit the same payload shape, even if you upgrade your pinned version in between. Upgrading your pinned version affects events created after the upgrade. Use the envelope’s api_version to branch on payload shape during a version cut-over.