Status & versioning

API version discovery, OpenAPI location, ops probes, and public status.

Before you integrate, you need to know which API version to call, where the machine-readable contract lives, and how to check coarse availability. This guide covers the customer-facing discovery and status endpoints on https://api.musimap.com.

Three surfaces on one host

  • /oauth/* — OAuth 2.0 and OpenID Connect protocol endpoints. Unversioned because they follow RFC/OIDC standards directly. Use these to obtain and manage tokens.
  • /v1/* — the canonical, stable business Web API (catalogue, ingestion, tagging, identity, and more as they ship). Pin production integrations to /v1.
  • Discovery and status — unversioned helpers: /versions, /status, and /openapi/v1.json. Flat JSON responses, no authentication required.

Discover the API version

V1 ships a single stable major version. Call business endpoints under /v1/ (for example GET /v1/me to validate token context).

List available versions programmatically: 

curl https://api.musimap.com/versions

Example response:

{
  "current": "v1",
  "latest": "v1",
  "versions": [
    {
      "version": "v1",
      "status": "stable",
      "base_path": "/v1",
      "openapi_url": "/openapi/v1.json"
    }
  ],
  "latest_alias_available": false
}

Pin integrations to an explicit major version path such as /v1. Do not assume a floating /latest/* alias is available.

OpenAPI specification

The machine-readable contract for the public surface is served at: 

https://api.musimap.com/openapi/v1.json

It documents OAuth, identity, meta, and business endpoints as they graduate to the public contract. Internal backend routes and partner-only endpoints (such as token introspection) are omitted.

Check coarse public status

For integration health checks, use GET /status. It returns a public-safe operational message and always responds with HTTP 200 (operational or degraded in the JSON body). 

curl https://api.musimap.com/status

When everything is healthy:

{
  "status": "operational",
  "message": "The MusiMap API is operational."
}

If the API is partially disrupted, the body uses status: "degraded" with a plain-language message. Retry token validation and business calls after a short backoff.

For incident history and maintenance windows, see the developers status page.

Validate your integration

A practical pre-flight sequence for client applications:

  1. GET /versions — confirm you are targeting /v1.
  2. GET /openapi/v1.json — load or diff the contract your client expects (also browsable on OpenAPI reference).
  3. POST /oauth/token — obtain an access token (see Authentication).
  4. GET /v1/me — confirm token context (scopes, organisation, catalog).
  5. GET /status — optional coarse availability check before retries during an incident.

Operational probes (not for normal integrations)

MusiMap also exposes infrastructure monitoring endpoints such as /live and /ready for internal operations. They are not part of the customer integration contract. Do not poll them from application code. Use /status and /versions instead.

Next steps