Endpoints
Base URL: https://cosmic.audio. Request and response bodies are JSON unless stated.
POST/v1/analyses
Upload a recording for analysis, as multipart/form-data.
| Field | Type | Meaning |
|---|
audio | file, required | The recording. Up to 90 MiB for lossless audio and 25 MiB for any other codec. |
profile | auto · full · evidence_only | auto by default. evidence_only reads provenance, watermarks and metadata without the COSMIC model. |
localized_scan | true · false | Also locate generated passages of about 20 seconds or more inside the recording. Off by default; about a third slower. Counts one analysis per started 5 minutes (seconds_per_count in capabilities). |
Send an Idempotency-Key header (8 to 200 characters) to make retries safe: the same key returns the same job for 24 hours instead of starting a new one.
Returns 202 with a job.
POST/v1/analyses/link
Analyse audio from a link instead of an upload.
{"source_url": "https://…", "profile": "auto", "localized_scan": false}
A track on a service listed in remote_sources of capabilities is analysed from a section of about 30 seconds; a TikTok video link is analysed from the sound it uses, never the video's own soundtrack (an original sound, the creator's own audio, is marked source.original). Any other public https link must point at the audio file itself, which is analysed whole, within the upload limits. The link must use a host name, not an IP address, with no port or credentials. A fetch that takes longer than 60 seconds is answered with 504.
Returns 202 with a job.
GET/v1/analyses/{id}
Read a job. Poll every one to two seconds until state is complete, failed or cancelled. Jobs and their results expire 24 hours after they are created.
DELETE/v1/analyses/{id}
Cancel a job and delete its audio. Returns 204.
POST/v1/analyses/{id}/feedback
Tell us whether an ai or not_detected result was right. One answer per analysis while its result is available.
{"accurate": true}
Optional fields: notes (2,000 characters), song_title and artist (200 each), and source_url (2,048). A source link must use HTTP or HTTPS without embedded credentials. You can send an answer with no other fields.
For an analysis created with an API key, send a key belonging to the same account. Returns 204, or 404 when the result is expired, already answered or unavailable to that key.
We review reports to investigate errors and improve accuracy. Feedback does not retain your audio or download source links. Individual reports are kept for up to 12 months; see Privacy.
POST/v1/feedback
Send a bug report, suggestion or other feedback using a valid API key. No plan allowance or credits are spent.
{"message": "The result link was difficult to find."}
message is required (1–2,000 characters). name (60 characters) and a valid reply email (254) are optional. No attachments are accepted. Returns 201 with a feedback id; invalid fields return 422.
Five submissions per hour per account, shared across its keys and signed-in website submissions. Over the limit, 429. The website form uses a bot check instead of an API key. Messages and optional contact details are kept for up to 12 months.
GET/v1/capabilities
What this deployment accepts: max_upload_bytes, max_lossy_upload_bytes, min_duration_seconds, retention_seconds, the profiles, the localized_scan options and the link remote_sources. No key is needed.
The job
| Field | Meaning |
|---|
id | The analysis id. |
state | queued, running, complete, failed or cancelled. |
stage | What is running now, while the job runs. |
status_url | Where to read the job. |
created_at, expires_at | ISO 8601 times, UTC. |
result | The result, once state is complete. |
error | A readable reason, when state is failed. A failed analysis is not charged. |
COSMIC