API v1

Overview

Akordo exposes a versioned HTTP API under /api/v1 for scripts and external integrations. It is the same API the Akordo apps use.

• Authentication with API keys or OAuth 2.0
• A machine-readable OpenAPI document at /api/v1/openapi.json
• An additive stability policy: fields and endpoints are not removed or renamed within v1

API access depends on your plan. See Account settings.

Base URL

Use your Akordo origin plus /api/v1, for example https://akordo.app/api/v1.

Authentication

API keys

Create a key in Settings and send it on every request:

X-API-Key: ak_...

or

Authorization: Bearer ak_...

Keys expire after at most 90 days. A key cannot list, create, or revoke API keys; that requires a signed-in browser session.

OAuth 2.0

Interactive clients use the authorization code flow with PKCE against Akordo's built-in OAuth endpoints:

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

Refresh tokens and the device authorization grant are supported. For API v1, request the api:access scope and pass the complete API base URL, such as https://akordo.app/api/v1, as the resource parameter. The resource is required, and a token issued for MCP cannot be used on API v1 or the other way round.

Use the resulting access token as a bearer token:

Authorization: Bearer at_...

If a request carries both headers, the bearer token is checked first and the API key is used as a fallback.

Quick examples

# Who am I?
curl -H "X-API-Key: ak_your_key_here" https://akordo.app/api/v1/me

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

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

# Create a song (set AKORDO_API_KEY to your key first)
curl -X POST -H "X-API-Key: ${AKORDO_API_KEY:?Set AKORDO_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"title":"Summer Jam","notes":"[G]Sun is [C]out [D]"}' \
  https://akordo.app/api/v1/songs

What the API covers

The OpenAPI document is the authoritative list. Resource areas include:

• Account: /me, profile, avatar, email change, preferences, plan summary
• Songs: list, create, read, update, soft delete, restore, versions, editor payload, sharing and invites
• Arrangements: create, read, update, soft delete, restore, versions, notes, MIDI preset, markup annotations
• Setlists: list, create, read, update, songs and order, section markers, labels, readiness and durations, settings, sharing, assignments, completion and performance history, copy, transfer
• Groups: create, rename, delete, members, invites, membership
• Labels, and instruments with soft delete and restore
• Media: audio attachments and storage quota
• Repertoire: queries, saved views, reports, custom fields, external resources, song history and confidence
• Imports: preview, commit, status, rollback, and source files
• Feedback: support threads and messages
• Invites: pending invites, accept, decline

Pagination

The main collection endpoints use cursor pagination: songs, songs with arrangements, setlists, groups, a song's arrangements, and an arrangement's notes. Other list endpoints, such as labels, instruments, deleted songs, versions, performances, and annotations, return a plain JSON array. The OpenAPI document shows which is which.

Paginated endpoints accept:

• limit from 1 to 100, default 50
• cursor from the previous response

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

A null next_cursor means you have reached the end.

Errors

Errors return a consistent envelope:

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

Common codes are unauthorized, forbidden, not_found, validation_error, conflict, rate_limited, storage_quota_exceeded, and internal_error.

Rate limits

Requests are limited per client address and per credential. The defaults are 600 requests per client and 300 per credential in a 60-second window, and the deployment edge may be stricter. A limited request returns 429 Too Many Requests with a Retry-After header. Wait that long before retrying.

Deletion semantics

Deleting a song, arrangement, or instrument is a soft delete with a restore endpoint. Soft-deleted songs and arrangements are removed permanently after 30 days. Deleting a setlist is permanent.

Security notes

• Keep keys secret and rotate them when exposed
• Prefer OAuth for anything a person signs in to
• Store tokens only in secure platform storage
• Always use HTTPS

Next steps

• Account settings to create keys
• AI assistants for the MCP server built on the same data