Developer API

Versioning, OpenAPI, and deprecation

Generate clients from the contract and detect compatible, breaking, and sunset changes.

On this pageTrack the URL contract Read X-API-Version Use authenticated OpenAPI Monitor the changelog Respond to deprecation headers

Track the URL contract

The stable prefix is /api/v1. New optional fields, endpoints, and output enum values may be added within v1; breaking changes move to a new prefix.

POST/api/v1/message404 Not Found

Request

# path typo: /message instead of /messages
curl https://oppermind.com/api/v1/message \
  -H "Authorization: Bearer $OPPERMIND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"oppermind-lato-1","messages":[{"role":"user","content":"Hello"}]}'

Response

X-API-Version: 2026-06-17

{
  "error": {
    "type": "invalid_request",
    "code": "OPMD_ROUTE_404",
    "message": "Unknown API endpoint. See https://oppermind.com/api/v1/docs"
  }
}

Unknown paths under v1 return OPMD_ROUTE_404; breaking changes arrive as a new prefix, never a renamed v1 path.

Try this

✦Write a contract test that asserts every request path starts with /api/v1/ and that unknown fields in a response are ignored rather than failing deserialisation.

What you getThe test passes today and keeps passing when an optional field or enum value is added inside v1; only a new prefix would require a deliberate change.

Read X-API-Version

The dated X-API-Version response header identifies the contract build. Log it with each request so changes can be correlated with behavior.

POST/api/v1/messages200 OK

Request

curl https://oppermind.com/api/v1/messages \
  -H "Authorization: Bearer $OPPERMIND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"oppermind-lato-1","max_tokens":80,"messages":[{"role":"user","content":"One line: what does a bill of lading prove?"}]}' \
  -i

Response

X-API-Version: 2026-06-17X-Request-ID: req_2b8e4d1a6f3c9e7b5a0d1f4c

{
  "id": "req_2b8e4d1a6f3c9e7b5a0d1f4c",
  "model": "oppermind-lato-1",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "It proves the carrier received the goods and sets out the terms of their carriage."
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 18,
    "output_tokens": 19
  }
}

Log the dated build beside the request ID; a change here explains a change in behaviour.

Try this

✦Log res.headers['x-api-version'] next to the request ID for every call your service makes.

What you getThe logs show a dated build identifier such as 2026-06-17 on each request; when it changes, you can tie any behaviour difference to the new contract build.

Use authenticated OpenAPI

GET /api/v1/openapi.json returns the OpenAPI 3.1 description to a valid API key. Use it for generated types, contract tests, Postman, or client scaffolding.

GET/api/v1/openapi.json200 OK

Request

curl https://oppermind.com/api/v1/openapi.json \
  -H "Authorization: Bearer $OPPERMIND_API_KEY" \
  -o openapi.json

Response

X-API-Version: 2026-06-17Cache-Control: private, max-age=300

{
  "openapi": "3.1.0",
  "info": { "title": "Oppermind Developer API", "version": "2026-06-17", … },
  "paths": { "/api/v1/messages": { … }, "/api/v1/images": { … }, "/api/v1/videos": { … }, … },
  "components": {
    "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "opmd_sk_*" } },
    "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", … } },
    "schemas": {
      "MessageRequest": { … }, "MessageResponse": { … },
      "ImageRequest": { … }, "ImageResponse": { … },
      "VideoRequest": { … }, "VideoResult": { … },
      "Error": { … }
    }
  }
}

Feed components.schemas to your type generator; info.version says which build the types came from.

Try this

✦curl https://oppermind.com/api/v1/openapi.json -H 'Authorization: Bearer opmd_sk_…' -o openapi.json then feed openapi.json to your type generator or import it into Postman.

What you getTyped request and response definitions are generated from the live contract, and the same file serves as the fixture for your contract tests.

Monitor the changelog

GET /api/v1/changelog describes compatible changes, breaking-change rules, and deprecations. Use it in release review or CI rather than relying on memory.

GET/api/v1/changelog200 OK

Request

curl https://oppermind.com/api/v1/changelog \
  -H "Authorization: Bearer $OPPERMIND_API_KEY" \
  | jq '.current_version, .deprecations'

Response

X-API-Version: 2026-06-17Cache-Control: private, max-age=300

{
  "api": "Oppermind Developer API",
  "current_version": "2026-06-17",
  "versioning_policy": {
    "scheme": "url-prefix",
    "stable_prefix": "/api/v1/",
    "what_counts_as_breaking": [ … ],
    "what_is_non_breaking": [ … ]
  },
  "deprecation_policy": { "minimum_runway_days": 180, "signalling": [ … ], "enforcement": "…" },
  "deprecations": [],
  "entries": [
    { "version": "2026-06-17", "date": "2026-06-17", "changes": [ … ] },
    { "version": "2026-06-04", "date": "2026-06-04", "changes": [ … ] }
  ]
}

deprecations is empty today; a new entry there should fail the build until someone reads it.

Try this

✦In CI, run: curl https://oppermind.com/api/v1/changelog -H 'Authorization: Bearer opmd_sk_…' | jq '.current_version, .deprecations'

What you getThe job prints the current version and the deprecations list; a new entry there fails the build so someone reads the migration notes before release.

Respond to deprecation headers

Deprecated endpoints emit Deprecation, Sunset, and a migration Link. The published policy provides at least 180 days of runway before the endpoint returns 410 Gone.

POST/api/v1/messages200 OK

Request

# illustrative: what a deprecated endpoint would return
curl https://oppermind.com/api/v1/messages \
  -H "Authorization: Bearer $OPPERMIND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"oppermind-lato-1","max_tokens":60,"messages":[{"role":"user","content":"Hello"}]}' \
  -i

Response

Deprecation: trueSunset: Mon, 01 Mar 2027 00:00:00 GMTLink: <https://www.oppermind.com/api/v1/changelog>; rel="deprecation"; type="text/html"X-API-Version: 2026-06-17

{
  "id": "req_0d5a7f2c9b4e1a8d3c6f0b5e",
  "model": "oppermind-lato-1",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Hello. How can I help today?"
    }
  ],
  "stop_reason": "end_turn",
  "usage": {
    "input_tokens": 8,
    "output_tokens": 9
  }
}

Illustrative only, nothing is deprecated today: Sunset sits at least 180 days out, then 410 Gone.

Try this

✦In your HTTP client, log a warning whenever a response carries a Deprecation header, printing the Sunset date and the Link header beside the endpoint name.

What you getWhen an endpoint you use is deprecated the warning shows Deprecation: true, a Sunset date at least 180 days out and a Link to migration guidance; after Sunset the call returns 410 Gone.

◎

GUIDED LEARNING

Practise this in Oppermind Academy

Follow the related tutorial or course and apply the concept to a real task.

Open learning path