Skip to content

docs: content & OpenAPI cleanup #171

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
recoupableorg wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: content & OpenAPI cleanup #171

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion api-reference/image/generation.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Generate Image'
title: 'Generate Image (Legacy)'
openapi: "/api-reference/openapi/content.json GET /api/image/generate"
---
138 changes: 80 additions & 58 deletions api-reference/openapi/content.json
View file
Open in desktop

Large diffs are not rendered by default.

82 changes: 43 additions & 39 deletions api-reference/openapi/releases.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -139,11 +139,15 @@
}
},
"patch": {
"summary": "Update scheduled task",
"summary": "Update Task",
"description": "Update an existing scheduled task. Only the id field is required; any additional fields you include will be updated on the task. The response shape matches the GET endpoint (an array containing the updated task).",
"security": [
{ "apiKeyAuth": [] },
{ "bearerAuth": [] }
{
"apiKeyAuth": []
},
{
"bearerAuth": []
}
],
"requestBody": {
"description": "JSON object with `id` and optional fields to merge onto the task.",
Expand Down Expand Up @@ -192,7 +196,7 @@
}
},
"400": {
"description": "Bad request — missing `id`, empty strings where a field is provided, or other validation failure from the request body. The body reports the first Zod issue via `missing_fields` and `error`.",
"description": "Bad request \u2014 missing `id`, empty strings where a field is provided, or other validation failure from the request body. The body reports the first Zod issue via `missing_fields` and `error`.",
"content": {
"application/json": {
"schema": {
Expand Down Expand Up @@ -496,13 +500,13 @@
}
}
},
"400": {
"description": "Bad request - invalid artist ID path parameter",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PinArtistErrorResponse"
}
"400": {
"description": "Bad request - invalid artist ID path parameter",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PinArtistErrorResponse"
}
}
}
},
Expand Down Expand Up @@ -546,29 +550,29 @@
}
],
"responses": {
"200": {
"description": "Artist unpinned.",
"content": {
"application/json": {
"schema": {
"200": {
"description": "Artist unpinned.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PinArtistResponse"
}
}
}
},
"400": {
"description": "Bad request - invalid artist ID path parameter",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PinArtistErrorResponse"
}
}
}
}
},
"401": {
"description": "Unauthorized - missing or invalid authentication"
},
},
"400": {
"description": "Bad request - invalid artist ID path parameter",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PinArtistErrorResponse"
}
}
}
},
"401": {
"description": "Unauthorized - missing or invalid authentication"
},
"403": {
"description": "Forbidden - the authenticated account cannot access this artist",
"content": {
Expand Down Expand Up @@ -1338,7 +1342,7 @@
}
},
"401": {
"description": "Unauthorized — invalid or missing API key / Bearer token",
"description": "Unauthorized \u2014 invalid or missing API key / Bearer token",
"content": {
"application/json": {
"schema": {
Expand All @@ -1352,7 +1356,7 @@
},
"/api/songs/analyze": {
"post": {
"description": "Analyze music using a state-of-the-art Audio Language Model that listens directly to the audio waveform. Unlike text-based AI, this model processes the actual sound — identifying harmony, structure, timbre, lyrics, and cultural context through deep music understanding. Supports audio up to 20 minutes (MP3, WAV, FLAC). Two modes: (1) **Presets** — pass a `preset` name like `catalog_metadata`, `mood_tags`, or `full_report` for structured, optimized output. (2) **Custom prompt** — pass a `prompt` for free-form questions. The `full_report` preset runs all 13 presets in parallel and returns a comprehensive music intelligence report. Use `GET /api/songs/analyze/presets` to list available presets.",
"description": "Analyze music using a state-of-the-art Audio Language Model that listens directly to the audio waveform. Unlike text-based AI, this model processes the actual sound \u2014 identifying harmony, structure, timbre, lyrics, and cultural context through deep music understanding. Supports audio up to 20 minutes (MP3, WAV, FLAC). Two modes: (1) **Presets** \u2014 pass a `preset` name like `catalog_metadata`, `mood_tags`, or `full_report` for structured, optimized output. (2) **Custom prompt** \u2014 pass a `prompt` for free-form questions. The `full_report` preset runs all 13 presets in parallel and returns a comprehensive music intelligence report. Use `GET /api/songs/analyze/presets` to list available presets.",
"security": [
{
"apiKeyAuth": []
Expand Down Expand Up @@ -1384,7 +1388,7 @@
}
},
"400": {
"description": "Bad request — missing or invalid fields",
"description": "Bad request \u2014 missing or invalid fields",
"content": {
"application/json": {
"schema": {
Expand All @@ -1394,7 +1398,7 @@
}
},
"401": {
"description": "Unauthorized — invalid or missing API key / Bearer token",
"description": "Unauthorized \u2014 invalid or missing API key / Bearer token",
"content": {
"application/json": {
"schema": {
Expand All @@ -1404,7 +1408,7 @@
}
},
"500": {
"description": "Server error — upstream model unavailable or inference failed",
"description": "Server error \u2014 upstream model unavailable or inference failed",
"content": {
"application/json": {
"schema": {
Expand Down Expand Up @@ -2722,7 +2726,7 @@
"audio_url": {
"type": "string",
"format": "uri",
"description": "Public URL to an audio file (MP3, WAV, or FLAC — up to 20 minutes)",
"description": "Public URL to an audio file (MP3, WAV, or FLAC \u2014 up to 20 minutes)",
"example": "https://example.com/song.mp3"
},
"max_new_tokens": {
Expand All @@ -2738,7 +2742,7 @@
"minimum": 0,
"maximum": 2,
"default": 1,
"description": "Controls output creativity — higher values produce more varied responses",
"description": "Controls output creativity \u2014 higher values produce more varied responses",
"example": 0.7
},
"top_p": {
Expand Down Expand Up @@ -3381,7 +3385,7 @@
},
"profileUrls": {
"type": "object",
"description": "Map of uppercase platform identifier to social profile URL. Each entry replaces the existing social for that platform; platforms not included are preserved. Recognized keys: SPOTIFY, INSTAGRAM, TIKTOK, TWITTER, YOUTUBE, APPLE, FACEBOOK, THREADS. Keys are matched case-sensitively — lowercase keys will create duplicate socials instead of replacing the existing entry.",
"description": "Map of uppercase platform identifier to social profile URL. Each entry replaces the existing social for that platform; platforms not included are preserved. Recognized keys: SPOTIFY, INSTAGRAM, TIKTOK, TWITTER, YOUTUBE, APPLE, FACEBOOK, THREADS. Keys are matched case-sensitively \u2014 lowercase keys will create duplicate socials instead of replacing the existing entry.",
"additionalProperties": {
"type": "string"
},
Expand Down
10 changes: 5 additions & 5 deletions api-reference/openapi/research.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -195,7 +195,7 @@
}
},
"delete": {
"description": "Delete a chat room by ID. This operation also removes related room records (memory emails, memories) before deleting the room itself.",
"description": "Delete a chat room by ID. This operation also removes related room records (memory emails, messages) before deleting the room itself.",
"requestBody": {
"description": "Chat deletion parameters",
"required": true,
Expand Down Expand Up @@ -332,7 +332,7 @@
},
"/api/chats/{id}/messages": {
"get": {
"description": "Retrieve all messages (memories) for a specific chat room in chronological order.",
"description": "Retrieve all messages for a specific chat room in chronological order.",
"parameters": [
{
"name": "id",
Expand Down Expand Up @@ -3030,7 +3030,7 @@
"id": {
"type": "string",
"format": "uuid",
"description": "UUID of the memory message"
"description": "UUID of the message"
},
"room_id": {
"type": "string",
Expand All @@ -3039,12 +3039,12 @@
},
"content": {
"type": "object",
"description": "Structured message payload stored for the memory"
"description": "Structured message payload"
},
"updated_at": {
"type": "string",
"format": "date-time",
"description": "ISO timestamp of the memory update"
"description": "ISO timestamp of the message update"
}
}
},
Expand Down
2 changes: 1 addition & 1 deletion api-reference/research/search.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Search'
title: 'Artist Search'
openapi: "/api-reference/openapi/research.json GET /api/research"
---
2 changes: 1 addition & 1 deletion api-reference/spotify/search.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Search'
title: 'Spotify Search'
openapi: "/api-reference/openapi/social.json GET /api/spotify/search"
---
2 changes: 1 addition & 1 deletion api-reference/transcribe/audio.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
---
title: 'Transcribe Audio'
title: 'Transcribe Audio (Legacy)'
openapi: "/api-reference/openapi/content.json POST /api/transcribe"
---
Loading