{"components":{"responses":{"ConflictError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}},"description":"Revision conflict"},"ForbiddenError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}},"description":"Insufficient permissions"},"InternalError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}},"description":"Server failure"},"NotFoundError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}},"description":"Resource not found"},"UnauthorizedError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}},"description":"Authentication failed"},"ValidationError":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorEnvelope"}}},"description":"Validation failure"}},"schemas":{"ApiErrorEnvelope":{"properties":{"error":{"properties":{"code":{"enum":["unauthorized","forbidden","not_found","conflict","validation_error","internal_error"],"type":"string"},"message":{"type":"string"}},"required":["code","message"],"type":"object"}},"required":["error"],"type":"object"},"ApiV1User":{"properties":{"display_name":{"type":["string","null"]},"email":{"format":"email","type":"string"},"id":{"format":"uuid","type":"string"}},"required":["id","email"],"type":"object"},"ArrangementTuningInput":{"additionalProperties":false,"properties":{"capo":{"type":"integer"},"display_order":{"type":"integer"},"id":{"format":"uuid","type":["string","null"]},"name":{"type":"string"},"transpose":{"type":"integer"}},"required":["name","transpose","capo","display_order"],"type":"object"},"ArrangementsListResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/SongArrangementDto"},"type":"array"},"page":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page"],"type":"object"},"CreateArrangementBody":{"additionalProperties":false,"properties":{"active_tuning_id":{"format":"uuid","type":["string","null"]},"additional_notes":{"type":["string","null"]},"bpm":{"type":["integer","null"]},"chord_pro_content":{"type":["string","null"]},"default_key":{"type":["string","null"]},"name":{"type":"string"},"recording_links":{"items":{"type":"string"},"type":["array","null"]},"time_signature":{"type":["string","null"]},"tunings":{"items":{"$ref":"#/components/schemas/ArrangementTuningInput"},"type":"array"}},"required":["name"],"type":"object"},"CreateSongBody":{"additionalProperties":false,"properties":{"artist":{"type":["string","null"]},"genre":{"type":["string","null"]},"notes":{"type":["string","null"]},"owner_group_id":{"format":"uuid","type":["string","null"]},"title":{"type":"string"}},"required":["title"],"type":"object"},"DashboardResponse":{"properties":{"pending_invites":{"items":{"$ref":"#/components/schemas/PendingInviteDto"},"type":"array"},"recent_views":{"items":{"$ref":"#/components/schemas/RecentViewDto"},"type":"array"}},"required":["pending_invites","recent_views"],"type":"object"},"GroupDto":{"additionalProperties":true,"type":"object"},"GroupsListResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/GroupDto"},"type":"array"},"page":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page"],"type":"object"},"InviteAcceptResponse":{"properties":{"content_id":{"type":"string"},"kind":{"enum":["group","song","setlist"],"type":"string"}},"required":["kind","content_id"],"type":"object"},"InviteTokenRequest":{"properties":{"kind":{"enum":["group","song","setlist"],"type":"string"},"token":{"type":"string"}},"required":["kind","token"],"type":"object"},"PageInfo":{"properties":{"next_cursor":{"type":["string","null"]}},"type":"object"},"PendingInviteDto":{"additionalProperties":true,"type":"object"},"RecentViewDto":{"additionalProperties":true,"type":"object"},"RecentViewTarget":{"additionalProperties":true,"type":"object"},"SetlistDto":{"additionalProperties":true,"type":"object"},"SetlistsListResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/SetlistDto"},"type":"array"},"page":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page"],"type":"object"},"SongArrangementDto":{"additionalProperties":true,"type":"object"},"SongDto":{"additionalProperties":true,"type":"object"},"SongEditorData":{"additionalProperties":true,"type":"object"},"SongsListResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/SongDto"},"type":"array"},"page":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page"],"type":"object"},"SongsWithArrangementsListResponse":{"properties":{"data":{"items":{"$ref":"#/components/schemas/SongEditorData"},"type":"array"},"page":{"$ref":"#/components/schemas/PageInfo"}},"required":["data","page"],"type":"object"},"UpdateArrangementBody":{"additionalProperties":false,"properties":{"active_tuning_id":{"description":"Send an empty string to clear the active tuning.","oneOf":[{"format":"uuid","type":"string"},{"enum":[""],"type":"string"},{"type":"null"}]},"additional_notes":{"type":["string","null"]},"bpm":{"type":["integer","null"]},"chord_pro_content":{"type":["string","null"]},"default_key":{"type":["string","null"]},"expected_updated_at":{"format":"date-time","type":["string","null"]},"name":{"type":"string"},"recording_links":{"items":{"type":"string"},"type":["array","null"]},"save_mode":{"enum":["explicit","auto"],"type":"string"},"time_signature":{"type":["string","null"]},"tunings":{"items":{"$ref":"#/components/schemas/ArrangementTuningInput"},"type":["array","null"]}},"required":["name"],"type":"object"},"UpdateSetlistItemNotesBody":{"additionalProperties":false,"properties":{"notes":{"type":["string","null"]}},"type":"object"},"UpdateSongBody":{"additionalProperties":false,"properties":{"allow_reshare":{"type":["boolean","null"]},"artist":{"type":["string","null"]},"genre":{"type":["string","null"]},"notes":{"type":["string","null"]},"title":{"type":"string"}},"required":["title"],"type":"object"}},"securitySchemes":{"apiKeyAuth":{"in":"header","name":"X-API-Key","type":"apiKey"},"oauth2":{"flows":{"authorizationCode":{"authorizationUrl":"https://akordo.app/oauth/authorize","scopes":{"mcp:tools":"Read access to Akordo API v1"},"tokenUrl":"https://akordo.app/oauth/token"}},"type":"oauth2"}}},"info":{"description":"Versioned REST-like API for Akordo clients and external integrations.","title":"Akordo Public API","version":"1.0.0"},"openapi":"3.1.0","paths":{"/api/v1/dashboard":{"get":{"parameters":[{"in":"query","name":"limit","required":false,"schema":{"default":30,"maximum":50,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DashboardResponse"}}},"description":"Dashboard data"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"422":{"$ref":"#/components/responses/ValidationError"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"oauth2":["mcp:tools"]},{"apiKeyAuth":[]}],"summary":"Load pending invites and recent views in one payload"}},"/api/v1/groups":{"get":{"parameters":[{"in":"query","name":"limit","required":false,"schema":{"default":50,"maximum":100,"minimum":1,"type":"integer"}},{"in":"query","name":"cursor","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GroupsListResponse"}}},"description":"Group page"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"422":{"$ref":"#/components/responses/ValidationError"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"oauth2":["mcp:tools"]},{"apiKeyAuth":[]}],"summary":"List groups"}},"/api/v1/invites/accept":{"post":{"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteTokenRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteAcceptResponse"}}},"description":"Invite accepted"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"422":{"$ref":"#/components/responses/ValidationError"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"oauth2":["mcp:tools"]},{"apiKeyAuth":[]}],"summary":"Accept an invite token"}},"/api/v1/invites/decline":{"post":{"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InviteTokenRequest"}}},"required":true},"responses":{"204":{"description":"Invite declined"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"422":{"$ref":"#/components/responses/ValidationError"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"oauth2":["mcp:tools"]},{"apiKeyAuth":[]}],"summary":"Decline an invite token"}},"/api/v1/invites/pending":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/PendingInviteDto"},"type":"array"}}},"description":"Pending invites list"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"oauth2":["mcp:tools"]},{"apiKeyAuth":[]}],"summary":"List pending invites for the current user"}},"/api/v1/me":{"get":{"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiV1User"}}},"description":"Authenticated user"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"oauth2":["mcp:tools"]},{"apiKeyAuth":[]}],"summary":"Get current authenticated user"}},"/api/v1/openapi.json":{"get":{"responses":{"200":{"description":"OpenAPI JSON document"}},"summary":"Get OpenAPI spec for API v1"}},"/api/v1/recent-views":{"get":{"parameters":[{"in":"query","name":"limit","required":false,"schema":{"default":30,"maximum":50,"minimum":1,"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/RecentViewDto"},"type":"array"}}},"description":"Recent views list"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"422":{"$ref":"#/components/responses/ValidationError"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"oauth2":["mcp:tools"]},{"apiKeyAuth":[]}],"summary":"List recent views"},"post":{"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecentViewTarget"}}},"required":true},"responses":{"204":{"description":"Recent view tracked"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"oauth2":["mcp:tools"]},{"apiKeyAuth":[]}],"summary":"Track a recent view"}},"/api/v1/setlists":{"get":{"parameters":[{"in":"query","name":"limit","required":false,"schema":{"default":50,"maximum":100,"minimum":1,"type":"integer"}},{"in":"query","name":"cursor","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetlistsListResponse"}}},"description":"Setlist page"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"422":{"$ref":"#/components/responses/ValidationError"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"oauth2":["mcp:tools"]},{"apiKeyAuth":[]}],"summary":"List setlists"}},"/api/v1/setlists/{setlist_id}":{"get":{"parameters":[{"in":"path","name":"setlist_id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetlistDto"}}},"description":"Setlist"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundError"},"422":{"$ref":"#/components/responses/ValidationError"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"oauth2":["mcp:tools"]},{"apiKeyAuth":[]}],"summary":"Get a setlist by ID"}},"/api/v1/setlists/{setlist_id}/songs/{song_id}/notes":{"patch":{"parameters":[{"in":"path","name":"setlist_id","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"song_id","required":true,"schema":{"description":"Canonical UUID or 22-character base64url song ID.","oneOf":[{"format":"uuid","type":"string"},{"pattern":"^[A-Za-z0-9_-]{22}$","type":"string"}]}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSetlistItemNotesBody"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetlistDto"}}},"description":"Updated setlist"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundError"},"422":{"$ref":"#/components/responses/ValidationError"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"oauth2":["mcp:tools"]},{"apiKeyAuth":[]}],"summary":"Update notes for a setlist item"}},"/api/v1/songs":{"get":{"parameters":[{"in":"query","name":"limit","required":false,"schema":{"default":50,"maximum":100,"minimum":1,"type":"integer"}},{"in":"query","name":"cursor","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SongsListResponse"}}},"description":"Song page"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"422":{"$ref":"#/components/responses/ValidationError"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"oauth2":["mcp:tools"]},{"apiKeyAuth":[]}],"summary":"List songs"},"post":{"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSongBody"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SongDto"}}},"description":"Created song"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"422":{"$ref":"#/components/responses/ValidationError"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"oauth2":["mcp:tools"]},{"apiKeyAuth":[]}],"summary":"Create a new song"}},"/api/v1/songs-with-arrangements":{"get":{"parameters":[{"in":"query","name":"limit","required":false,"schema":{"default":50,"maximum":100,"minimum":1,"type":"integer"}},{"in":"query","name":"cursor","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SongsWithArrangementsListResponse"}}},"description":"Song editor data page"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"422":{"$ref":"#/components/responses/ValidationError"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"oauth2":["mcp:tools"]},{"apiKeyAuth":[]}],"summary":"List songs with arrangements, view prefs, and recording link titles"}},"/api/v1/songs/{song_id}":{"get":{"parameters":[{"in":"path","name":"song_id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SongDto"}}},"description":"Song"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundError"},"422":{"$ref":"#/components/responses/ValidationError"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"oauth2":["mcp:tools"]},{"apiKeyAuth":[]}],"summary":"Get a song by ID"},"patch":{"parameters":[{"in":"path","name":"song_id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSongBody"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SongDto"}}},"description":"Updated song"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundError"},"409":{"$ref":"#/components/responses/ConflictError"},"422":{"$ref":"#/components/responses/ValidationError"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"oauth2":["mcp:tools"]},{"apiKeyAuth":[]}],"summary":"Update song metadata"}},"/api/v1/songs/{song_id}/arrangements":{"get":{"parameters":[{"in":"path","name":"song_id","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"query","name":"limit","required":false,"schema":{"default":50,"maximum":100,"minimum":1,"type":"integer"}},{"in":"query","name":"cursor","required":false,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ArrangementsListResponse"}}},"description":"Arrangement page"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundError"},"422":{"$ref":"#/components/responses/ValidationError"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"oauth2":["mcp:tools"]},{"apiKeyAuth":[]}],"summary":"List arrangements for a song"},"post":{"parameters":[{"in":"path","name":"song_id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateArrangementBody"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SongArrangementDto"}}},"description":"Created arrangement"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundError"},"409":{"$ref":"#/components/responses/ConflictError"},"422":{"$ref":"#/components/responses/ValidationError"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"oauth2":["mcp:tools"]},{"apiKeyAuth":[]}],"summary":"Create an arrangement for a song"}},"/api/v1/songs/{song_id}/arrangements/{arrangement_id}":{"patch":{"parameters":[{"in":"path","name":"song_id","required":true,"schema":{"format":"uuid","type":"string"}},{"in":"path","name":"arrangement_id","required":true,"schema":{"format":"uuid","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateArrangementBody"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SongArrangementDto"}}},"description":"Updated arrangement"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundError"},"409":{"$ref":"#/components/responses/ConflictError"},"422":{"$ref":"#/components/responses/ValidationError"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"oauth2":["mcp:tools"]},{"apiKeyAuth":[]}],"summary":"Update a song arrangement"}},"/api/v1/songs/{song_id}/editor":{"get":{"parameters":[{"in":"path","name":"song_id","required":true,"schema":{"format":"uuid","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SongEditorData"}}},"description":"Song editor data"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundError"},"422":{"$ref":"#/components/responses/ValidationError"},"500":{"$ref":"#/components/responses/InternalError"}},"security":[{"oauth2":["mcp:tools"]},{"apiKeyAuth":[]}],"summary":"Get a song with arrangements and editor data"}}},"servers":[{"url":"https://akordo.app"}]}