SimpleDock
Log in

Developers

Versioning & deprecation

What you can build against, what can change underneath you, and how much warning you get. Agents should not integrate against a surface that can move without notice, so this page is the commitment.

How the API is versioned

The version lives in the URL path. The current version is v1, served at /api/v1. URL path (/api/v1). The version changes only for a breaking change.

The unauthenticated endpoints under /api/v1/public follow the same version and the same policy.

Changes we make without a new version

Treat the API as open for extension. Your client must tolerate these without breaking — parse defensively, ignore fields you do not recognize:

  • New endpoints and new optional request parameters
  • New fields on an existing response object
  • New enum values on a field already documented as extensible
  • New optional headers

Changes that require a new version

None of these will ever happen inside a published version:

  • Removing or renaming an endpoint, field, or enum value
  • Making an optional request parameter required
  • Changing a field's type or the meaning of an existing value
  • Tightening validation so a previously accepted request is rejected

How deprecation is signalled

A version is never retired without at least 180 days’ notice. The notice arrives in the responses themselves, not only in a changelog you would have to be watching:

  • `Deprecation` response header (RFC 9745) carrying the date deprecation took effect
  • `Sunset` response header (RFC 8594) carrying the date the version stops responding
  • `Link: rel="deprecation"` pointing at the policy, and `rel="successor-version"` at the replacement
  • `deprecated: true` on the affected operations in the OpenAPI document

Deprecationfollows RFC 9745 — a structured-field date in Unix seconds, so Deprecation: @1782950399. Sunset follows RFC 8594 and carries an HTTP-date, so Sunset: Wed, 01 Jul 2026 23:59:59 GMT. Per RFC 9745 the sunset date is never earlier than the deprecation date.

After the sunset date the version responds 410 Gone with the standard error envelope pointing at its successor. It does not silently change behavior.

Rate limits

Every API response carries its own limit state, so a client can pace itself rather than discovering the ceiling by hitting it:

RateLimit-Policy: "public";q=60;w=60
RateLimit: "public";r=57;t=42

q is the quota, w the window in seconds, r what you have left, and t the seconds until it resets. A 429 adds Retry-After.

Unauthenticated endpoints allow 60 requests per 60 seconds per IP. Authenticated requests allow 120 per 60 seconds per API key. Both are best-effort per instance, not a durable quota — treat the headers as the source of truth.

For agents

The machine-readable version of this page is in /agent-instructions.md, and the current policy is also returned as JSON by /api/v1/public/status under versioning and rateLimits. Deprecated operations are also marked deprecated: true in the OpenAPI document.

Questions

Email [email protected]. If you are building something that depends on a guarantee this page does not make, ask — we would rather write it down than have you guess. Start at the developer docs.