Cyanite Documentation
Cyanite is an AI-powered music analysis and tagging platform. Four products are available through one REST API:
- Tagging describes every track with genre, mood, instruments, BPM, key and more, delivered as a set of model outputs.
- Search finds tracks in your catalogue by a text prompt, by one or several of your tracks or by external tracks, narrowed down with metadata filters.
- AI Music Detection tells you whether a track was likely generated by a Gen AI music model, and by which one.
- Segmentation, an add-on to Tagging, splits every track into its musical sections and tells you where each one starts and ends.
The Cyanite REST API is the successor to the Cyanite GraphQL API. Public signup for API access is not currently available, and the REST API is only available to enterprise customers. Do you have a business need for this API? Contact our sales team (sales@cyanite.ai)
Get started
Quick Start
Upload your first track, receive the webhook and fetch its results, end to end, with code in TypeScript, PHP and Python.
Manage your library
Every track you upload becomes a Library Track. List, find, update and
delete your tracks, and use externalId and customTags to match them
to your catalogue.
How it works
Analysis in Cyanite is asynchronous. Every integration follows the same three steps:
- Upload a track with
POST /v1/library-tracks. It becomes a Library Track in your account. Learn how · Manage your library. - Get notified. Cyanite analyzes the track and calls your webhook with an
analysisJob/finishedevent when the results are ready. Learn how. - Use the results. Fetch the track's tags,
AI Music Detection result and
segments as model outputs with
GET /v1/library-tracks/{id}/models, or find it with Search.
What you can do
Tagging
Every uploaded track is tagged automatically. Retrieve its tags as model outputs, such as genres, moods, instruments, BPM and key, over the whole track and over time.
Search
Search by Prompt, by Track, by Tracks or by External Tracks. Narrow the results by BPM, genre, mood and more with metadata filters. (Public alpha)
AI Music Detection
Find out whether a track was likely generated by a Gen AI music model. A product of its own, available with or without Tagging.
Segmentation
Split a track into its musical sections to pitch, search and cue a coherent part of it. An add-on to Tagging.
Build a reliable integration
Webhooks
What notifications contain, how delivery, retries and signatures work, and what a production-ready handler needs.
Limits
The difference between rate limits (429) and quota limits (403),
which requests count and how to react.
Base URL and authentication
All endpoints live under one base URL:
https://rest-api.cyanite.ai/v1
Authenticate every request with your API key in the x-api-key header. To
check that your key works, fetch your
account:
curl https://rest-api.cyanite.ai/v1/me/account \
-H "x-api-key: $CYANITE_API_KEY"
Don't have an API key yet? Contact Cyanite to get access. Let us know your webhook URL at the same time, and we'll configure it for your account.
Errors are returned as JSON problem details with a type, title, status
and a human-readable detail that explains what went wrong. A 429 means
you've hit a rate limit: wait for the number of seconds in the retry-after
header, then retry. A 403 with a Quota… title means you've hit a quota limit:
the quota is used up, and retrying won't help. See
Understanding Limits.
How these docs are organized
The documentation is organized by what you need right now: learning the basics, completing a task, understanding a feature, or looking up a detail.
Quick Start
Your first upload, webhook and result, end to end.
REST API Quick Start
Start a webhook handler, upload a track and receive its analysis results with the Cyanite REST API.
Guides
Step-by-step instructions for a specific task.
Library Management
Manage your own catalog in Cyanite
Tagging
Retrieve the tags of an analyzed track as model outputs and use its genres, moods, BPM, key and segments in your application.
Search
Find tracks in your Library by a prompt, by one or several of your tracks or by a Spotify or YouTube track, and narrow the results with metadata filters.
AI Music Detection
Find out whether a track was likely generated by a Gen AI music model such as Suno or Udio, how the detection works and how far to trust a result.
Segmentation
Split a track into its musical sections, how the segmentation works and what to use it for.
Concepts
How the products work and how to interpret their results.
Understanding Model Outputs
What model outputs are, how Tagging, AI Music Detection and Segmentation deliver their results as model outputs, how versions work, and how to read scores, tags, segments and confidence.
Understanding Search
How Cyanite finds tracks in your Library by meaning, which search to use when, how scores work, and how metadata filters narrow down a search.
Understanding Webhooks
What Cyanite webhook notifications contain, how signatures, retries and duplicates work, and what a production-ready webhook handler needs.
Understanding Limits
The difference between rate limits and quota limits in the Cyanite REST API, which requests count towards each, how the API signals them, how to react, and what polling costs compared to webhooks.
API Reference
Every endpoint with its parameters, request and response schemas: the API Reference.