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

Copy a song

Send POST /api/v1/songs/SONG_ID/copy with a JSON object:

{"title":"Summer Jam — rehearsal copy"}

Use {} to default the title to Copy of <source title>. Add owner_group_id to create the copy in a group; omitted or null creates it in your personal library. A successful request returns HTTP 201 with the new song. The same copy permissions and plan limits apply as in the app.

For MCP, discover songs_copy and invoke it through akordo_write, passing song_id and the same optional fields.

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, copy, read, update, soft delete, restore, versions, editor payload, sharing and invites
• Arrangements: create, read, update, soft delete, restore, versions, notes, MIDI preset, markup annotations, personal capo preferences, and backing-track selection
• Setlists: list, create, read, update, songs and order, section markers, labels, readiness and durations, settings, sharing, assignments, current Team event, completion and performance history, copy, transfer
• Groups: create, rename, delete, members, invites, membership
• Labels, and instruments with soft delete and restore
• Media: audio attachments, recording key and rhythm corrections, storage quota, and transfer/status endpoints for MCP-created upload sessions
• 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

Musical keys and personal capo

Vocal tunings store the shared performing-key transposition. A setlist item selects an arrangement and optionally a vocal tuning; null means Main, the arrangement's original key.

Use /arrangements/ARRANGEMENT_ID/my-capo for the authenticated account's capo preference, optionally scoped to a vocal tuning. Do not put capo in shared tuning inputs. Read-only collaborators can save their own capo. Follow the endpoint's revision requirements to avoid overwriting a newer preference.

Current Team event and event times

GET /setlists/current-event returns the automatically selected event, eligible candidates, and expires_at and evaluated_at. Team assignment is required; sharing access alone does not qualify. A declined assignment is excluded.

Event clock times are venue-local values serialized with a trailing Z; do not convert them as UTC timestamps or send a numeric offset. The separate event_timezone field is an IANA zone used for scheduling. In contrast, the current-event response's expires_at and evaluated_at are real UTC instants. Changing the event zone preserves the entered clock times.

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