{ "openapi": "3.1.0", "info": { "title": "AudioDN API", "version": "1.0.0", "summary": "Audio delivery infrastructure: upload, transcode, secure delivery, and playback.", "description": "AudioDN provides a REST API and embeddable web components for managing and delivering audio at scale.\n\nAuthentication: bearer token via the `Authorization` header. Use a server-side API key for full access; mint scoped client-side keys (Player or Uploader) for browsers and mobile apps.\n\nAll endpoints are prefixed with `/v1/`.", "contact": { "name": "Audio Delivery Network", "email": "support@audiodeliverynetwork.com", "url": "https://audiodeliverynetwork.com" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://api.audiodelivery.net", "description": "Production" } ], "tags": [ { "name": "Organizations" }, { "name": "Collections" }, { "name": "Tracks" }, { "name": "Cover Images" }, { "name": "Upload Sessions" }, { "name": "Play Sessions" }, { "name": "Variants" } ], "security": [{ "BearerAuth": [] }], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Server-side API key. Use scoped client-side keys for browser and mobile contexts." } }, "parameters": { "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, "Offset": { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } }, "schemas": { "OkEnvelope": { "type": "object", "required": ["ok", "api_request_id"], "properties": { "ok": { "type": "boolean", "const": true }, "api_request_id": { "type": "string", "format": "uuid" } } }, "Error": { "type": "object", "required": ["ok", "message"], "properties": { "ok": { "type": "boolean", "const": false }, "message": { "type": "string" }, "api_request_id": { "type": "string", "format": "uuid" } } }, "ImageColor": { "type": "object", "properties": { "hex": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "area": { "type": "number" }, "lightness": { "type": "number" }, "saturation": { "type": "number" } } }, "UploadHandle": { "type": "object", "properties": { "method": { "type": "string", "enum": ["PUT", "POST"] }, "upload_url": { "type": "string", "format": "uri" }, "ttl": { "type": "integer" }, "expires_at": { "type": "string", "format": "date-time" } } }, "Organization": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "image_colors": { "type": "array", "items": { "$ref": "#/components/schemas/ImageColor" } }, "is_theme_overridable": { "type": "boolean" }, "is_cover_overridable": { "type": "boolean" }, "player_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "player_subtitle": { "type": "string" } } }, "Collection": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "creator_id": { "type": "string", "format": "uuid" }, "organization_index": { "type": "string" }, "title": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "image_colors": { "type": "array", "items": { "$ref": "#/components/schemas/ImageColor" } }, "is_cover_overridable": { "type": "boolean" }, "is_theme_overridable": { "type": "boolean" }, "player_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "player_subtitle": { "type": "string" } } }, "Track": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "collection_id": { "type": "string", "format": "uuid" }, "creator_id": { "type": "string", "format": "uuid" }, "file_name": { "type": "string" }, "duration": { "type": "number" }, "organization_index": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "is_cover_overridable": { "type": "boolean" }, "is_theme_overridable": { "type": "boolean" }, "player_title": { "type": "string" }, "player_subtitle": { "type": "string" }, "player_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "status": { "type": "string", "enum": ["initializing", "processing", "fallback_processing", "ready", "incomplete", "failed"] } } }, "Variant": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string", "description": "Variant kind (e.g. transcode, preview, waveform, analysis)." }, "format": { "type": "string" }, "bitrate": { "type": "integer" } } }, "UploadSession": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "creator_id": { "type": "string", "format": "uuid" }, "collection_id": { "type": "string", "format": "uuid" }, "organization_index": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "expires_at": { "type": "string", "format": "date-time" } } }, "PlaySession": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "creator_id": { "type": "string", "format": "uuid" }, "organization_index": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "variants": { "type": "array", "items": { "type": "string" } }, "expires_at": { "type": "string", "format": "date-time" } } } }, "responses": { "Unauthorized": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "BadRequest": { "description": "Invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Resource not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "paths": { "/v1/organization/{organization_id}": { "get": { "tags": ["Organizations"], "summary": "Get organization", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Organization details.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/OkEnvelope" }, { "type": "object", "properties": { "organization_id": { "type": "string", "format": "uuid" }, "organization": { "$ref": "#/components/schemas/Organization" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": ["Organizations"], "summary": "Update organization", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "responses": { "200": { "description": "Updated organization.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/OkEnvelope" }, { "type": "object", "properties": { "organization_id": { "type": "string", "format": "uuid" }, "organization": { "$ref": "#/components/schemas/Organization" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/collection": { "get": { "tags": ["Collections"], "summary": "List collections", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "description": "Collections list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/OkEnvelope" }, { "type": "object", "properties": { "count": { "type": "integer" }, "collections": { "type": "array", "items": { "$ref": "#/components/schemas/Collection" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": ["Collections"], "summary": "Create collection", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["title"], "properties": { "title": { "type": "string" }, "creator_id": { "type": "string", "format": "uuid" }, "organization_index": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "image_colors": { "type": "array", "items": { "$ref": "#/components/schemas/ImageColor" } }, "is_cover_overridable": { "type": "boolean" }, "is_theme_overridable": { "type": "boolean" }, "player_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" }, "player_subtitle": { "type": "string" } } } } } }, "responses": { "200": { "description": "Collection created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/OkEnvelope" }, { "type": "object", "properties": { "collection_id": { "type": "string", "format": "uuid" }, "collection": { "$ref": "#/components/schemas/Collection" }, "collection_cover_upload": { "$ref": "#/components/schemas/UploadHandle" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/collection/{collection_id}": { "get": { "tags": ["Collections"], "summary": "Get collection", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Collection details.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/OkEnvelope" }, { "type": "object", "properties": { "collection_id": { "type": "string", "format": "uuid" }, "collection": { "$ref": "#/components/schemas/Collection" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": ["Collections"], "summary": "Update collection", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" } } } }, "responses": { "200": { "description": "Updated collection.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/OkEnvelope" }, { "type": "object", "properties": { "collection_id": { "type": "string", "format": "uuid" }, "collection": { "$ref": "#/components/schemas/Collection" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": ["Collections"], "summary": "Delete collection", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Collection deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/OkEnvelope" }, { "type": "object", "properties": { "collection_id": { "type": "string", "format": "uuid" }, "deleted_collection": { "$ref": "#/components/schemas/Collection" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/collection/{collection_id}/track": { "get": { "tags": ["Tracks"], "summary": "List tracks in a collection", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "description": "Tracks list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/OkEnvelope" }, { "type": "object", "properties": { "count": { "type": "integer" }, "tracks": { "type": "array", "items": { "$ref": "#/components/schemas/Track" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/collection/{collection_id}/cover": { "post": { "tags": ["Cover Images"], "summary": "Generate a collection cover image upload URL", "parameters": [ { "name": "collection_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Upload handle.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/OkEnvelope" }, { "type": "object", "properties": { "collection_id": { "type": "string", "format": "uuid" }, "collection": { "$ref": "#/components/schemas/Collection" }, "collection_cover_upload": { "$ref": "#/components/schemas/UploadHandle" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/track": { "post": { "tags": ["Tracks"], "summary": "Create a track", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["collection_id", "file_name"], "properties": { "collection_id": { "type": "string", "format": "uuid" }, "creator_id": { "type": "string", "format": "uuid" }, "file_name": { "type": "string" }, "organization_index": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true }, "is_cover_overridable": { "type": "boolean" }, "is_theme_overridable": { "type": "boolean" }, "player_title": { "type": "string" }, "player_subtitle": { "type": "string" }, "player_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$" } } } } } }, "responses": { "200": { "description": "Track created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/OkEnvelope" }, { "type": "object", "properties": { "track_id": { "type": "string", "format": "uuid" }, "track": { "$ref": "#/components/schemas/Track" }, "track_upload": { "$ref": "#/components/schemas/UploadHandle" }, "track_cover_upload": { "$ref": "#/components/schemas/UploadHandle" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/track/{track_id}": { "get": { "tags": ["Tracks"], "summary": "Get track", "parameters": [ { "name": "track_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Track details.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/OkEnvelope" }, { "type": "object", "properties": { "track_id": { "type": "string", "format": "uuid" }, "track": { "$ref": "#/components/schemas/Track" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": ["Tracks"], "summary": "Update track", "parameters": [ { "name": "track_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Track" } } } }, "responses": { "200": { "description": "Updated track.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/OkEnvelope" }, { "type": "object", "properties": { "track_id": { "type": "string", "format": "uuid" }, "track": { "$ref": "#/components/schemas/Track" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": ["Tracks"], "summary": "Delete track", "parameters": [ { "name": "track_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Track deleted.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/OkEnvelope" }, { "type": "object", "properties": { "track_id": { "type": "string", "format": "uuid" }, "deleted_track": { "$ref": "#/components/schemas/Track" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/track/{track_id}/cover": { "post": { "tags": ["Cover Images"], "summary": "Generate a track cover image upload URL", "parameters": [ { "name": "track_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Upload handle.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/OkEnvelope" }, { "type": "object", "properties": { "track_id": { "type": "string", "format": "uuid" }, "track": { "$ref": "#/components/schemas/Track" }, "track_cover_upload": { "$ref": "#/components/schemas/UploadHandle" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/upload_session": { "post": { "tags": ["Upload Sessions"], "summary": "Create upload session", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["collection_id"], "properties": { "collection_id": { "type": "string", "format": "uuid" }, "creator_id": { "type": "string", "format": "uuid" }, "organization_index": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Upload session created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/OkEnvelope" }, { "type": "object", "properties": { "upload_session_id": { "type": "string", "format": "uuid" }, "upload_session": { "$ref": "#/components/schemas/UploadSession" }, "expires_at": { "type": "string", "format": "date-time" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/upload_session/{upload_session_id}": { "get": { "tags": ["Upload Sessions"], "summary": "Get upload session", "parameters": [ { "name": "upload_session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Upload session details.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/OkEnvelope" }, { "type": "object", "properties": { "upload_session_id": { "type": "string", "format": "uuid" }, "upload_session": { "$ref": "#/components/schemas/UploadSession" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/upload/{upload_session_id}/track": { "post": { "tags": ["Upload Sessions"], "summary": "Create a track within an upload session", "parameters": [ { "name": "upload_session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["file_name"], "properties": { "file_name": { "type": "string" }, "organization_index": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true } } } } } }, "responses": { "200": { "description": "Track and upload handle returned.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/OkEnvelope" }, { "type": "object", "properties": { "upload_session_id": { "type": "string", "format": "uuid" }, "track_id": { "type": "string", "format": "uuid" }, "track": { "$ref": "#/components/schemas/Track" }, "upload_session": { "$ref": "#/components/schemas/UploadSession" }, "track_upload": { "$ref": "#/components/schemas/UploadHandle" }, "track_cover_upload": { "$ref": "#/components/schemas/UploadHandle" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/play_session/{scope}": { "post": { "tags": ["Play Sessions"], "summary": "Create play session", "parameters": [ { "name": "scope", "in": "path", "required": true, "schema": { "type": "string", "enum": ["collection", "track", "playlist"] } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "variants": { "type": "array", "items": { "type": "string" } }, "collection_id": { "type": "string", "format": "uuid" }, "track_id": { "type": "string", "format": "uuid" }, "playlist_id": { "type": "string", "format": "uuid" } } } } } }, "responses": { "200": { "description": "Play session created.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/OkEnvelope" }, { "type": "object", "properties": { "play_session_id": { "type": "string", "format": "uuid" }, "play_session": { "$ref": "#/components/schemas/PlaySession" }, "tracks": { "type": "array", "items": { "$ref": "#/components/schemas/Track" } }, "expires_at": { "type": "string", "format": "date-time" } } } ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/play_session/{play_session_id}": { "get": { "tags": ["Play Sessions"], "summary": "Get play session", "parameters": [ { "name": "play_session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Play session details.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/OkEnvelope" }, { "type": "object", "properties": { "play_session_id": { "type": "string", "format": "uuid" }, "play_session": { "$ref": "#/components/schemas/PlaySession" }, "tracks": { "type": "array", "items": { "$ref": "#/components/schemas/Track" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/play/{play_session_id}/{play_track_id}": { "get": { "tags": ["Play Sessions"], "summary": "Get a track within a play session", "parameters": [ { "name": "play_session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "play_track_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Track within the play session, including signed variant URLs.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/OkEnvelope" }, { "type": "object", "properties": { "play_session_id": { "type": "string", "format": "uuid" }, "track_id": { "type": "string", "format": "uuid" }, "play_session": { "$ref": "#/components/schemas/PlaySession" }, "cover_image": { "type": "string", "format": "uri" }, "track": { "$ref": "#/components/schemas/Track" }, "levels": { "type": "object", "additionalProperties": true }, "variants": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "format": "uri" }, "url": { "type": "string", "format": "uri" } } } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/v1/variant": { "get": { "tags": ["Variants"], "summary": "List variants", "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Offset" } ], "responses": { "200": { "description": "Variants list.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/OkEnvelope" }, { "type": "object", "properties": { "count": { "type": "integer" }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/Variant" } } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/v1/variant/{variant_id}": { "get": { "tags": ["Variants"], "summary": "Get variant", "parameters": [ { "name": "variant_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Variant details.", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/OkEnvelope" }, { "type": "object", "properties": { "variant_id": { "type": "string", "format": "uuid" }, "variant": { "$ref": "#/components/schemas/Variant" } } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } } } }