API (v1)

Overview

Akordo exposes a versioned HTTP API under /api/v1 for first-party clients and external integrations.

Design goals for v1:

• Stable, additive contract with minimal breaking changes.
• Authentication through OAuth 2.0 and API keys.
• Machine-readable OpenAPI contract at /api/v1/openapi.json.

The OpenAPI document at GET /api/v1/openapi.json describes the /api/v1/* data endpoints. OAuth endpoints (/oauth/*) are not included in this spec — see the Authentication section below for those.

Base URL and versioning

Use your Akordo deployment origin plus /api/v1.

Examples:

• https://akordo.app/api/v1
• https://beta.akordo.app/api/v1

Stability policy

/api/v1 is additive-first:

• Existing fields and endpoints are not removed or renamed within v1.
• New fields and endpoints may be added.
• Breaking changes ship in a new major path version (for example, /api/v2).

Authentication

OAuth 2.0

Clients that support browser-based auth should use authorization code + PKCE with Akordo's built-in OAuth endpoints:

• GET /oauth/authorize
• POST /oauth/token

API-v1 grants must request all three parts of the API authority exactly:

• scope: api:access
• audience: akordo-api (selected by the server for the API resource)
• resource: the complete API-v1 URL for the deployment, such as https://akordo.app/api/v1

The resource parameter is required on the authorization request. MCP grants (mcp:tools, the MCP audience, or the /api/mcp resource), a missing resource, and another deployment's API URL cannot be used on API v1.

Use bearer tokens in API calls:

Authorization: Bearer at_xxx

API key (external integrations recommended)

For scripts, backend jobs, and tools that do not need user-interactive sign-in:

• X-API-Key: ak_...
• or Authorization: Bearer ak_...

Keys carry explicit api:access and/or mcp:tools scopes and expire after at most 90 days. A key cannot list, create, or revoke API keys; credential management requires a recent interactive browser session or an approved, short-lived first-party elevation. Store keys in a secret manager and revoke them when an integration is retired.

If both Authorization and X-API-Key are present, bearer is evaluated first and X-API-Key can be used as fallback.

Quick examples

Authenticate and fetch your songs with curl:

# Check your identity
curl -H "X-API-Key: ak_your_key_here" https://akordo.app/api/v1/me

# List your songs
curl -H "X-API-Key: ak_your_key_here" https://akordo.app/api/v1/songs

# Get a specific song
curl -H "X-API-Key: ak_your_key_here" https://akordo.app/api/v1/songs/SONG_ID

OpenAPI

Fetch the v1 OpenAPI document at:

• GET /api/v1/openapi.json

Use this document to generate typed clients, validate requests/responses, and keep integration tests aligned with the current v1 contract.

Current v1 read endpoints

• GET /api/v1/me
• GET /api/v1/songs
• GET /api/v1/songs/{song_id}
• GET /api/v1/songs/{song_id}/arrangements
• GET /api/v1/setlists
• GET /api/v1/setlists/{setlist_id}

Rate limiting

/api/v1/* is rate-limited by both client address and API-key/OAuth credential. The default application limits are 600 requests per client and 300 per credential in a 60-second window; deployment-edge limits may be stricter. A limited request returns 429 Too Many Requests with a Retry-After header. Wait for that interval before retrying.

OAuth dynamic client registration (POST /oauth/register) has a separate, tighter abuse limit and uses the same 429/Retry-After behavior.

Pagination

List endpoints use cursor pagination.

Query parameters:

• limit (1-100, default 50)
• cursor (opaque token from previous response)

Response shape:

{
  "data": [],
  "page": {
    "next_cursor": "opaque-token-or-null"
  }
}

When next_cursor is null, you have reached the end of the result set.

Error envelope

Errors return a consistent JSON envelope:

{
  "error": {
    "code": "validation_error",
    "message": "limit must be between 1 and 100"
  }
}

Common error codes:

• unauthorized
• forbidden
• not_found
• validation_error
• internal_error

Security notes

• Keep API keys secret and rotate them when exposed.
• Prefer OAuth for user-scoped interactive sessions.
• Only store tokens in secure platform storage.
• Use HTTPS in production.