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

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_...

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

There are currently no enforced rate limits on /api/v1/* data endpoints. This may change in the future — if rate limiting is introduced, it will be documented here and in the OpenAPI spec.

Exception: OAuth dynamic client registration (POST /oauth/register) is rate-limited. If you send too many registration requests in a short window, you'll receive a 429 Too Many Requests response. Wait and retry after a delay.

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.