{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/api-reference/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["api-container","api-content","endpoint","api-examples","tabs","tab","code-group"]},"redocly_category":"API Reference","searchWeight":120,"type":"markdown"},"seo":{"title":"Create a music collection","description":"Complete API reference and documentation for Freddy AI-powered backend system by Aitronos","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"create-a-music-collection","__idx":0},"children":["Create a music collection"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Create a new, empty collection of music tracks owned by the caller. Tracks are added afterwards."]},{"$$mdtype":"Tag","name":"ApiContainer","attributes":{},"children":[{"$$mdtype":"Tag","name":"ApiContent","attributes":{},"children":[{"$$mdtype":"Tag","name":"Endpoint","attributes":{"method":"POST","path":"https://api.aitronos.com/v1/music/{organization_id}/collections"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Creates an empty collection. Use ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/api-reference/music/add-collection-track"},"children":["Add a track to a collection"]}," to populate it."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"path-parameters","__idx":1},"children":["Path parameters"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["organization_id"]}]}," string ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#ef4444 !important","fontWeight":"600 !important","fontStyle":"normal !important"}},"children":["required"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The organization that owns the collection."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"request-body","__idx":2},"children":["Request Body"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}]}," string ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#ef4444 !important","fontWeight":"600 !important","fontStyle":"normal !important"}},"children":["required"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Human-readable collection name. Must be 1–512 characters."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}]}," string ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#9ca3af !important","fontWeight":"500 !important","fontStyle":"normal !important"}},"children":["optional"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Free-text description of the collection."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cover_track_id"]}]}," string ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#9ca3af !important","fontWeight":"500 !important","fontStyle":"normal !important"}},"children":["optional"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A track id (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mtrack_"]},") whose artwork is used as the collection cover."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cover_image_url"]}]}," string ",{"$$mdtype":"Tag","name":"em","attributes":{"style":{"color":"#9ca3af !important","fontWeight":"500 !important","fontStyle":"normal !important"}},"children":["optional"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A direct image URL for the collection cover. Maximum 1024 characters."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"returns","__idx":3},"children":["Returns"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The created collection object."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}]}," string"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Collection id, prefixed ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mcoll_"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["name"]}]}," string"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The collection name."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["description"]}]}," string | null"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The collection description, if any."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cover_track_id"]}]}," string | null"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The cover track id, if set."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cover_image_url"]}]}," string | null"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The cover image URL, if set."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["track_count"]}]}," integer"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Number of tracks in the collection. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["0"]}," for a newly created collection."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["created_at"]}]}," string"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["ISO 8601 creation timestamp."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["updated_at"]}]}," string"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["ISO 8601 last-update timestamp."]}]},{"$$mdtype":"Tag","name":"ApiExamples","attributes":{},"children":[{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"label":"Example","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeGroup","attributes":{"mode":"dropdown"},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","data-title":"cURL","header":{"title":"cURL","controls":{"copy":{}}},"source":"curl -X POST \"https://api.aitronos.com/v1/music/org_abc123/collections\" \\\n  -H \"X-API-Key: $FREDDY_API_KEY\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"name\": \"Focus Sessions\",\n    \"description\": \"Instrumental tracks for deep work\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","data-title":"Python SDK","header":{"title":"Python SDK","controls":{"copy":{}}},"source":"from aitronos import Aitronos  # pip install aitronos-sdk\n\nclient = Aitronos(api_key=\"your-api-key\")\n\ncollection = client.post(\n    \"/v1/music/org_abc123/collections\",\n    json={\n        \"name\": \"Focus Sessions\",\n        \"description\": \"Instrumental tracks for deep work\",\n    },\n)\nprint(collection[\"id\"])\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"python","data-title":"Python","header":{"title":"Python","controls":{"copy":{}}},"source":"import os\nimport requests\n\napi_key = os.environ[\"FREDDY_API_KEY\"]\n\nresponse = requests.post(\n    \"https://api.aitronos.com/v1/music/org_abc123/collections\",\n    headers={\"X-API-Key\": api_key},\n    json={\n        \"name\": \"Focus Sessions\",\n        \"description\": \"Instrumental tracks for deep work\",\n    },\n)\n\nprint(response.json()[\"id\"])\n","lang":"python"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","data-title":"JavaScript","header":{"title":"JavaScript","controls":{"copy":{}}},"source":"const apiKey = process.env.FREDDY_API_KEY;\n\nconst response = await fetch('https://api.aitronos.com/v1/music/org_abc123/collections', {\n  method: 'POST',\n  headers: {\n    'X-API-Key': apiKey,\n    'Content-Type': 'application/json',\n  },\n  body: JSON.stringify({\n    name: 'Focus Sessions',\n    description: 'Instrumental tracks for deep work',\n  }),\n});\n\nconst collection = await response.json();\nconsole.log(collection.id);\n","lang":"javascript"},"children":[]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Response:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"201 Created","header":{"title":"201 Created","controls":{"copy":{}}},"source":"{\n  \"id\": \"mcoll_4a1f9c7e2b8d\",\n  \"name\": \"Focus Sessions\",\n  \"description\": \"Instrumental tracks for deep work\",\n  \"cover_track_id\": null,\n  \"cover_image_url\": null,\n  \"track_count\": 0,\n  \"created_at\": \"2026-06-28T10:30:00Z\",\n  \"updated_at\": \"2026-06-28T10:30:00Z\"\n}\n","lang":"json"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"Errors","disable":false},"children":[{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"401 Unauthorized","header":{"title":"401 Unauthorized","controls":{"copy":{}}},"source":"{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"AUTHENTICATION_REQUIRED\",\n    \"message\": \"Authentication required. Please provide a valid API key.\",\n    \"system_message\": \"Missing or invalid authorization header\",\n    \"type\": \"authentication_error\",\n    \"status\": 401,\n    \"details\": {},\n    \"trace_id\": \"req_abc123xyz\",\n    \"timestamp\": \"2026-06-28T10:30:00Z\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"403 Forbidden","header":{"title":"403 Forbidden","controls":{"copy":{}}},"source":"{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"INSUFFICIENT_PERMISSIONS\",\n    \"message\": \"You do not have permission to perform this action.\",\n    \"system_message\": \"Missing USE_MUSIC_GENERATION capability\",\n    \"type\": \"authorization_error\",\n    \"status\": 403,\n    \"details\": {},\n    \"trace_id\": \"req_def456uvw\",\n    \"timestamp\": \"2026-06-28T10:30:00Z\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","data-title":"422 Unprocessable Entity","header":{"title":"422 Unprocessable Entity","controls":{"copy":{}}},"source":"{\n  \"success\": false,\n  \"error\": {\n    \"code\": \"VALIDATION_ERROR\",\n    \"message\": \"The request payload is invalid.\",\n    \"system_message\": \"name must be between 1 and 512 characters\",\n    \"type\": \"validation_error\",\n    \"status\": 422,\n    \"details\": { \"field\": \"name\" },\n    \"trace_id\": \"req_ghi789xyz\",\n    \"timestamp\": \"2026-06-28T10:30:00Z\"\n  }\n}\n","lang":"json"},"children":[]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-resources","__idx":4},"children":["Related Resources"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/api-reference/music/list-collections"},"children":["List music collections"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/api-reference/music/add-collection-track"},"children":["Add a track to a collection"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/api-reference/music/introduction"},"children":["Music Studio overview"]}]}]}]},"headings":[{"value":"Create a music collection","id":"create-a-music-collection","depth":1},{"value":"Path parameters","id":"path-parameters","depth":2},{"value":"Request Body","id":"request-body","depth":2},{"value":"Returns","id":"returns","depth":2},{"value":"Related Resources","id":"related-resources","depth":2}],"frontmatter":{"title":"Create a music collection","keywords":["create music collection","music collection","new collection","music studio"],"seo":{"title":"Create a music collection"}},"lastModified":"2026-06-28T21:42:45.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/api-reference/music/create-collection","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}