insp.ac API

Versioning scheme

All API endpoints are prefixed with a major version number. The current version is /v1. Within a version, the API follows a strict compatibility contract: existing fields, status codes, and behaviors will not change in backward-incompatible ways.

Versioned endpoint

GET https://api.insp.ac/v1/issues
POST https://api.insp.ac/v1/issues
GET https://api.insp.ac/v1/issues/{id}

What counts as a breaking change

The following changes are considered breaking and will only ship under a new major version:

Removing an endpoint or HTTP method.
Removing or renaming a response field.
Changing the type or semantics of an existing field.
Adding a new required request field without a default value.
Changing authentication or authorization behavior.
Changing error codes for existing failure conditions.

Non-breaking changes

The following changes can happen within a version at any time. Build your integration to handle them gracefully:

Adding new optional request fields.
Adding new response fields.
Adding new endpoints.
Adding new enum values to existing fields.
Improving error messages (the error string may change; the code will not).
Changing rate limits.

Tip

Parse response bodies with a permissive approach — ignore unknown fields rather than failing on them. This ensures new fields added to responses do not break your integration.

Deprecation signals

Before removing or replacing an operation, the API announces deprecation through standard HTTP headers and OpenAPI metadata.

Signal	Where	Meaning
`Deprecation header`	HTTP response	The date when the operation was marked deprecated
`Sunset header`	HTTP response	The date after which the operation may be removed
`deprecated: true`	OpenAPI spec	The operation is marked deprecated in the contract
`x-sunset`	OpenAPI spec	Target removal date in the contract metadata

Deprecation headers example

HTTP/1.1 200 OK
Deprecation: Mon, 01 Sep 2025 00:00:00 GMT
Sunset: Mon, 01 Mar 2026 00:00:00 GMT
Content-Type: application/json

Important

Monitor your integration logs for Deprecation and Sunset headers. When you see them, begin planning your migration to the replacement operation well before the sunset date.

Migration strategy

When a new API version is released:

Review the migration guide published with the new version.
Update your SDK to the latest version, which will support both versions during the transition.
Update your API endpoint paths from /v1 to the new version prefix.
Adjust your code for any changed request or response shapes.
Test against the sandbox environment before switching production traffic.
Complete migration before the old version's sunset date.

OpenAPI contract

The OpenAPI specification is the source of truth for all versioning and deprecation metadata. Download the latest contract to see the full current state of the API.

Download the spec

# Canonical contract (OpenAPI 3.1)
curl -O https://api.insp.ac/openapi.json

# SDK-compatible contract (OpenAPI 3.0)
curl -O https://api.insp.ac/openapi-sdk.json