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, discovery, and business endpoints in the public V1 contract. Its info.version is the version of the API gateway deployment that serves it.

Read the running gateway version

GET /health reports the version of the API gateway deployment you are calling, in data.version. No authentication is required. It is the same value as the served OpenAPI info.version and the version shown on the OpenAPI reference. 

curl https://api.musimap.com/health
{
  "status": 200,
  "message": "Service is up and running",
  "data": { "service": "api-gateway", "status": "healthy", "version": "<running version>" }
}

The major API version you pin to stays /v1; the gateway version changes with each deployment.

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.

Next steps