Gard Music Distributor
https://back.gard-api.org/api/v1/music-distributorPublic surface is /api/v1/music-distributor: submit releases (POST /moderation/), manage catalog (GET /releases/…, GET /releases/{release_ref}/status), and resolve stores / territories / genres via GET /catalog/reference-data or granular GET /catalog/platforms — full paths in the list below.
Release status workflow
status on moderation responses and workflow_status in webhooks use these values:
submitted — sent
2. under_review — in review
3. sent_to_stores — approved
4. live — released
5. rejected — needs editsGET …/releases/{release_ref}/status at any time. Use the rel_… id from GET /releases/all — that's the easiest way. You can also pass the numeric release_id from the same list. The mdr_… submission id (from POST /moderation/) is accepted too, but only after the release has been approved and linked to a catalog row — before that it returns 404.
status and message always reflect the public workflow stage — the same values you see in GET /moderation/. You will never see internal technical states like draft or processing in these fields.
Cancelling or removing a release depends on its current status:
- submitted → DELETE …/releases/{release_ref} — cancels the upload and removes it from your catalog.
- under_review → POST …/releases/{release_ref}/revoke — withdraws the release from platform review.
- sent_to_stores or live → POST /delete-requests/ — submits a takedown request to the Gard team (not instant; processed manually). Calling the other endpoints at this stage returns 400 with a hint.
Pitching a release to editorial playlists is available at any stage up to and including live.Authentication
Use X-API-Key with a key from Dashboard → API Keys (gard_…).
https://back.gard-api.orgcurl https://back.gard-api.org/api/v1/music-distributor/catalog/reference-data \ -H "X-API-Key: gard_…"
Media requirements (Music Distributor)
Enforced on POST /api/v1/music-distributor/moderation/ — invalid cover, audio, video, or booklet returns 422 with a clear message.
- Formats — JPEG or PNG only.
- Square — Width must equal height.
- Resolution — Between 1400×1400 and 6000×6000 px.
- DPI — ≥ 72.
- File size — ≤ 20 MB.
- Colour — RGB (no CMYK-only uploads).
- Formats — WAV, FLAC, or MP3 on upload; server may convert to WAV for delivery.
- Duration — Each track ≥ 4 seconds (validated server-side when ffprobe/wave available).
- Size — ≤ 1 GB per file.
- Naming — Use ASCII-safe filenames; order of files matches order of `tracks_meta` entries.
- Container — .mov or .mp4.
- Resolution — 1920×1080 or 3840×2160 when validated.
- Size — ≤ 6 GB.
- Format — PDF only (valid %PDF- header).
- Size — ≤ 10 MB.
- Supported fields — cover_url, audio_files_urls, video_url, booklet_url.
- Format — Public HTTP(S) URLs only. Max 50 MB per URL. Max 30 audio URLs per request (`audio_files_urls`).
- Mutual exclusion — Provide either binary file OR URL for each field — never both.
- Cleanup — URL files are downloaded server-side, processed, and deleted after distributor upload.
Catalog codes (reference)
Each row is code and name. Use these codes in POST /api/v1/music-distributor/moderation/ for platforms, countries, genre_id, sub_genre_id, and meta_lang. Platform, country, language, and root genre tables below are a bundled snapshot; subgenres are loaded from the live catalog on the server for this page.
| code | Name |
|---|---|
| 7digital | 7digital |
| acrcloud | ACRCloud |
| amazon_music | Amazon Music |
| anghami | Anghami |
| apple_music | Apple Music |
| audiblemagic | AudibleMagic |
| awa | AWA |
| base_nda | BASE_NDA |
| beeline_kz | BeeLine KZ |
| beeline_t2_ringbacktone | Beeline, t2 (RingBackTone) |
| clicknclear | ClicknClear |
| cron_telecom | Cron Telecom |
| deezer | Deezer |
| flo | FLO |
| fonmix | FonMix |
| gomusic | GoMusic |
| iheart | iHeart |
| jaxsta | Jaxsta |
| jiosaavn | JioSaavn |
| kkbox | KKBOX |
| likee | Likee |
| line_music_rythm | LINE MUSIC / Rythm |
| lyricfind | LyricFind |
| megafon_ringbacktone | MegaFon (RingBackTone) |
| mixcloud | Mixcloud |
| mobi_music | mobi music |
| mobi_music_kz | Mobi Music KZ |
| mts_ringbacktone | MTS (RingBackTone) |
| musixmatch | MusixMatch |
| netease | Netease |
| other_distribution | Other distribution |
| pandora | Pandora |
| peloton | Peloton |
| presto_music | Presto Music |
| pretzel | Pretzel |
| rao_russian_authors_society | RAO (Russian Authors' Society) |
| ringbacktone_partner | RingBackTone-Partner |
| smule | Smule |
| soundcloud | SoundCloud |
| soundexchange | SoundExchange |
| spotify | Spotify |
| spotify_video | Spotify Video |
| tencent | Tencent |
| tidal | TIDAL |
| tiktok | TikTok |
| trebel | TREBEL |
| vk_music | VK Music |
| vk_video | VK Video |
| vois_russian_organization_for_intellectual_property | VOIS (Russian Organization for Intellectual Property) |
| yandex_music | Yandex Music |
| yandex_video | Yandex Video |
| youtube_sound_recording | YouTube (Sound Recording) |
| youtube_copyright | YouTube Copyright |
| youtube_music | YouTube Music |
| zvuk_wink_music | Zvuk / Wink Music |
| code | Name |
|---|---|
| af | Afghanistan |
| ax | Aland Islands |
| al | Albania |
| dz | Algeria |
| as | American Samoa |
| ad | Andorra |
| ao | Angola |
| ai | Anguilla |
| aq | Antarctica |
| ag | Antigua And Barbuda |
| ar | Argentina |
| am | Armenia |
| aw | Aruba |
| au | Australia |
| at | Austria |
| az | Azerbaijan |
| bs | Bahamas |
| bh | Bahrain |
| bd | Bangladesh |
| bb | Barbados |
| by | Belarus |
| be | Belgium |
| bz | Belize |
| bj | Benin |
| bm | Bermuda |
| bt | Bhutan |
| bo | Bolivia |
| bq | Bonaire |
| ba | Bosnia And Herzegowina |
| bw | Botswana |
| bv | Bouvet Island |
| br | Brazil |
| io | British Indian Ocean Territory |
| vg | British Virgin Islands |
| bn | Brunei Darussalam |
| bg | Bulgaria |
| bf | Burkina Faso |
| bi | Burundi |
| kh | Cambodia |
| cm | Cameroon |
| ca | Canada |
| cv | Cape Verde |
| ky | Cayman Islands |
| cf | Central African Republic |
| td | Chad |
| cl | Chile |
| cx | Christmas Island |
| cis | CIS |
| cc | Cocos (Keeling) Islands |
| co | Colombia |
| km | Comoros |
| ck | Cook Islands |
| cr | Costa Rica |
| ci | Cote D`Ivoire |
| hr | Croatia |
| cu | Cuba |
| cy | Cyprus |
| cz | Czech Republic |
| kp | Democratic People's Republic of Korea |
| cd | Democratic Republic of Congo |
| dk | Denmark |
| dj | Djibouti |
| dm | Dominica |
| do | Dominican Republic |
| tl | East Timor |
| ec | Ecuador |
| eg | Egypt |
| sv | El Salvador |
| gq | Equatorial Guinea |
| er | Eritrea |
| ee | Estonia |
| et | Ethiopia |
| fk | Falkland Islands (Malvinas) |
| fo | Faroe Islands |
| fm | Federal States of Micronesia |
| fj | Fiji |
| fi | Finland |
| fr | France |
| gf | French Guiana |
| pf | French Polynesia |
| tf | French Southern Territories |
| ga | Gabon |
| gm | Gambia |
| ge | Georgia |
| de | Germany |
| gh | Ghana |
| gi | Gibraltar |
| gr | Greece |
| gl | Greenland |
| gd | Grenada |
| gp | Guadeloupe |
| gu | Guam |
| gt | Guatemala |
| gg | Guernsey |
| gn | Guinea |
| gw | Guinea-Bissau |
| gy | Guyana |
| ht | Haiti |
| hm | Heard And Mc Donald Islands |
| va | Holy See (Vatican City State) |
| hn | Honduras |
| hk | Hong Kong |
| hu | Hungary |
| is | Iceland |
| in | India |
| id | Indonesia |
| ir | Iran |
| iq | Iraq |
| ie | Ireland |
| im | Isle of Man |
| il | Israel |
| it | Italy |
| jm | Jamaica |
| jp | Japan |
| je | Jersey |
| jo | Jordan |
| kz | Kazakhstan |
| ke | Kenya |
| ki | Kiribati |
| xk | Kosovo |
| kw | Kuwait |
| kg | Kyrgyzstan |
| la | Laos |
| lv | Latvia |
| lb | Lebanon |
| ls | Lesotho |
| lr | Liberia |
| ly | Libyan Arab Jamahiriya |
| li | Liechtenstein |
| lt | Lithuania |
| lu | Luxembourg |
| mo | Macau |
| mk | Macedonia |
| mg | Madagascar |
| mw | Malawi |
| my | Malaysia |
| mv | Maldives |
| ml | Mali |
| mt | Malta |
| mh | Marshall Islands |
| mq | Martinique |
| mr | Mauritania |
| mu | Mauritius |
| yt | Mayotte |
| mx | Mexico |
| md | Moldova |
| mc | Monaco |
| mn | Mongolia |
| me | Montenegro |
| ms | Montserrat |
| ma | Morocco |
| mz | Mozambique |
| mm | Myanmar |
| na | Namibia |
| nr | Nauru |
| np | Nepal |
| nl | Netherlands |
| an | Netherlands Antilles |
| nc | New Caledonia |
| nz | New Zealand |
| ni | Nicaragua |
| ne | Niger |
| ng | Nigeria |
| nu | Niue |
| nf | Norfolk Island |
| mp | Northern Mariana Islands |
| no | Norway |
| om | Oman |
| pk | Pakistan |
| pw | Palau |
| ps | Palestine |
| pa | Panama |
| pg | Papua New Guinea |
| py | Paraguay |
| pe | Peru |
| ph | Philippines |
| pn | Pitcairn |
| pl | Poland |
| pt | Portugal |
| cn | PRC |
| pr | Puerto Rico |
| qa | Qatar |
| cg | Republic of Congo |
| kr | Republic of Korea |
| re | Reunion |
| ro | Romania |
| ru | Russian Federation |
| rw | Rwanda |
| kn | Saint Kitts And Nevis |
| lc | Saint Lucia |
| vc | Saint Vincent And The Grenadines |
| ws | Samoa |
| sm | San Marino |
| st | Sao Tome And Principe |
| sa | Saudi Arabia |
| sn | Senegal |
| rs | Serbia |
| sc | Seychelles |
| sl | Sierra Leone |
| sg | Singapore |
| sk | Slovakia |
| si | Slovenia |
| sb | Solomon Islands |
| so | Somalia |
| za | South Africa |
| gs | South Georgia And South S.S. |
| ss | South Sudan |
| es | Spain |
| lk | Sri Lanka |
| sh | St. Helena |
| pm | St. Pierre And Miquelon |
| sd | Sudan |
| sr | Suriname |
| sj | Svalbard And Jan Mayen Islands |
| sz | Swaziland |
| se | Sweden |
| ch | Switzerland |
| sy | Syrian Arab Republic |
| tw | Taiwan |
| tj | Tajikistan |
| tz | Tanzania |
| th | Thailand |
| tg | Togo |
| tk | Tokelau |
| to | Tonga |
| tt | Trinidad And Tobago |
| tn | Tunisia |
| tr | Turkey |
| tm | Turkmenistan |
| tc | Turks And Caicos Islands |
| tv | Tuvalu |
| um | U.S. Minor Islands |
| ug | Uganda |
| ua | Ukraine |
| ae | United Arab Emirates |
| gb | United Kingdom |
| us | United States |
| vi | United States Virgin Islands |
| uy | Uruguay |
| uz | Uzbekistan |
| vu | Vanuatu |
| ve | Venezuela |
| vn | Viet Nam |
| wf | Wallis And Futuna Islands |
| eh | Western Sahara |
| ye | Yemen |
| zm | Zambia |
| zw | Zimbabwe |
| code | Name |
|---|---|
| ae | Avestan |
| az | Azeri |
| en | English |
| ar | Arabic |
| hy | Armenian |
| af | Afrikaans |
| be | Belarusian |
| bn | Bengali |
| bg | Bulgarian |
| hu | Hungarian |
| vi | Vietnamese |
| ht | Haitian |
| el | Greek |
| ka | Georgian |
| da | Danish |
| zu | Zulu |
| he | Hebrew |
| id | Indonesian |
| ga | Irish |
| is | Icelandic |
| es | Spanish |
| it | Italian |
| kk | Kazakh |
| ca | Catalan |
| ky | Kyrgyz |
| zh | Chinese |
| ko | Korean |
| lo | Lao |
| la | Latin |
| lv | Latvian |
| lt | Lithuanian |
| ms | Malay |
| de | German |
| nl | Dutch |
| no | Norwegian |
| pa | Punjabi |
| fa | Persian |
| pl | Polish |
| pt | Portuguese |
| ro | Romanian |
| ru | Russian |
| sa | Sanskrit |
| sk | Slovak |
| sl | Slovenian |
| tl | Tagalog |
| tg | Tajik |
| th | Thai |
| ta | Tamil |
| tt | Tatar |
| te | Telugu |
| tr | Turkish |
| tk | Turkmen |
| uz | Uzbek |
| uk | Ukrainian |
| ur | Urdu |
| fi | Finnish |
| fr | French |
| hi | Hindi |
| hr | Croatian |
| ce | CE |
| cs | Czech |
| cv | CV |
| sv | Swedish |
| et | Estonian |
| ja | Japanese |
| code | Name |
|---|---|
| alternative | Alternative |
| anime | Anime |
| arabic | Arabic |
| armenian | Armenian |
| blues | Blues |
| brazilian | Brazilian |
| children_s_music | Children's Music |
| chinese | Chinese |
| christian_gospel | Christian & Gospel |
| classical | Classical |
| comedy | Comedy |
| country | Country |
| cuban | Cuban |
| dance | Dance |
| disney | Disney |
| easy_listening | Easy Listening |
| electronic | Electronic |
| enka | Enka |
| fitness_workout | Fitness & Workout |
| folk | Folk |
| french_pop | French Pop |
| german_folk | German Folk |
| german_pop | German Pop |
| hip_hop_rap | Hip Hop/Rap |
| holiday | Holiday |
| indian | Indian |
| inspirational | Inspirational |
| instrumental | Instrumental |
| j_pop | J-Pop |
| jazz | Jazz |
| karaoke | Karaoke |
| kayokyoku | Kayokyoku |
| korean | Korean |
| latin | Latin |
| marching_bands | Marching Bands |
| new_age | New Age |
| pop | Pop |
| r_b_soul | R&B/Soul |
| reggae | Reggae |
| rock | Rock |
| russian | Russian |
| singer_songwriter | Singer/Songwriter |
| soundtrack | Soundtrack |
| spoken_word | Spoken Word |
| vocal | Vocal |
| world | World |
Subgenres for every root genre are loaded from the live catalog (server-side). Pick a genre, then copy all subgenre codes at once.
| code | Name |
|---|---|
| adult_alternative | Adult Alternative |
| alternative_metal | Alternative Metal |
| alternative_rock | Alternative Rock |
| chinese_alt | Chinese Alt |
| college_rock | College Rock |
| egyptian_tarab | Egyptian Tarab |
| emo | EMO |
| emo_rap | Emo rap |
| goth_rock | Goth Rock |
| grunge | Grunge |
| hardcore_punk | Hardcore punk |
| indie_egyptian | Indie Egyptian |
| indie_levant | Indie Levant |
| indie_maghreb | Indie Maghreb |
| indie_pop | Indie Pop |
| indie_rock | Indie Rock |
| iraqi_tarab | Iraqi Tarab |
| khaleeji_tarab | Khaleeji Tarab |
| korean_indie | Korean Indie |
| metalcore | Metalcore |
| new_wave | New Wave |
| pop_punk | Pop Punk |
| post_hardcore | Post-hardcore |
| punk | Punk |
| rap_metal | Rap metal |
Use the copy button to copy all subgenre codes for the selected root genre at once.
Endpoints
GET: query parameters as one object (no JSON body on the wire). Multipart routes: logical fields — send as form-data, values shown as JSON for clarity.
/api/v1/music-distributor/moderation/Submit a full release (multipart). The response includes a status field for the submission.
| Field | Type | Required | Description |
|---|---|---|---|
| release_name | string | yes | Release / album title. |
| artist_name | string | yes | Primary artist display name. |
| release_date | string (YYYY-MM-DD) | yes | Worldwide release date. |
| genre_id | string | integer | yes | Root genre code (e.g. electronic) or legacy numeric id — see GET /catalog/reference-data → genres_root or the static tables below. |
| sub_genre_id | string | integer | no | Subgenre code under the resolved root genre (see subgenres_by_parent_code in reference-data / docs bundle) or legacy numeric id. |
| album_type | string | no | Default Single. Gard credits (charged on successful submit, tied to your API key account): Single 500, EP 700, Album or Compilation 850. Options: Single · EP · Album · Compilation |
| label | string | no | Label / imprint as shown on stores (P-line). ≤200 characters. |
| meta_lang | string | no | Metadata language: ISO-style code (e.g. en, ru) or a language name / slug resolvable from the languages list. Options: Code or name token; see static languages table. |
| sub_title | string | no | Album subtitle / version. |
| album_annotation | string | no | Short description / liner notes. |
| upc | string | no | Optional; max 14 digits. Leave empty for auto-assignment. |
| copyright | string | no | Optional. Your rights share on the composition, percent 0–100 (default 100). |
| platforms | string (JSON array) | no | Each entry: platform code (e.g. spotify) or legacy numeric id. Omit or empty → server may select all. |
| countries | string (JSON array) | no | Each entry: territory code (ISO us, ru, …) or legacy numeric id. Use [] for worldwide. See static countries table. |
| artist_roles | string (JSON array) | yes | Album-level credits: JSON array of { name, role, order? }. Required — include at least one composer and one songwriter using real given + family names (same rule as the distributor web UI). |
| tracks_meta | string (JSON array) | no | One object per audio file in order. Fields include: name, version, isrc, track_po_code, author_rights, related_rights, explicit_content, is_cover, is_remix, is_instrumental, is_focus_track, is_live, is_drugs, preview_start, meta_lang, lyrics, persons (array of { name, role, order? }) — roles: artist, composer, songwriter (required) |
| sales_start_date | date string | no | Optional sales start. |
| preorder_date | date string | no | Optional pre-order date. |
| spotify_startsale_date | date string | no | Optional per-store date. |
| tiktok_startsale_date | date string | no | Optional. |
| yandex_startsale_date | date string | no | Optional. |
| oma_startsale_date | date string | no | Optional. |
| youtubered_upload_date | date string | no | Optional YouTube Music date. |
| itunes_cleared_for_stream | string bool | no | default true Options: true · false |
| itunes_not_cleared_for_sale | string bool | no | default false |
| is_single_maxi | string bool | no | default false |
| is_mixtape | string bool | no | default false |
| is_audio_book | string bool | no | default false |
| is_low_itunes_track_price | string bool | no | default false |
| itunes_has_mfit | string bool | no | default false |
| tiktok_ev | string bool | no | TikTok early video flag. default false |
| callback_url | string (URL) | no | Optional your HTTPS URL (any path). Same multipart POST as the release. Gard sends JSON with X-Gard-Signature: sha256=… (HMAC-SHA256 of the raw body). Verify using the webhook signing secret for the gard_… key (GET /api/v1/keys/{id}/webhook-signing-secret) or deployment GARD_WEBHOOK_HMAC_SECRET / SECRET_KEY for JWT-only submits. HTTP 2xx. |
| cover | file | yes | Cover image file (see media rules). |
| audio_files | file[] | yes | At least one audio file; field name can be repeated (multipart). |
| video | file | no | Optional video file. |
| booklet | file | no | Optional PDF booklet. |
| cover_url | string (URL) | no | Alternative to cover: public HTTP(S) URL to cover image. Max 50 MB. Use either cover or cover_url, not both. |
| audio_files_urls | string (JSON array) | no | Alternative to audio_files: JSON array of public HTTP(S) URLs. Must match tracks_meta count. Max 30 URLs, 50 MB each. Use either audio_files or audio_files_urls, not both. |
| video_url | string (URL) | no | Alternative to video: public HTTP(S) URL to video file. Max 50 MB. Use either video or video_url, not both. |
| booklet_url | string (URL) | no | Alternative to booklet: public HTTP(S) URL to PDF. Max 50 MB. Use either booklet or booklet_url, not both. |
{
"release_name": "My Single",
"artist_name": "Stage Name",
"release_date": "2026-04-21",
"genre_id": "electronic",
"sub_genre_id": "ambient",
"album_type": "Single",
"label": "My Imprint",
"meta_lang": "en",
"platforms": ["spotify", "youtube_music", "apple_music"],
"countries": [],
"artist_roles": [
{ "name": "Stage Name", "role": "artist", "order": 1 },
{ "name": "Jane Q. Composer", "role": "composer", "order": 1 },
{ "name": "Jane Q. Composer", "role": "songwriter", "order": 1 }
],
"tracks_meta": [
{
"name": "Track A",
"meta_lang": "en",
"persons": [
{ "name": "Stage Name", "role": "artist", "order": 1 },
{ "name": "Jane Q. Composer", "role": "composer", "order": 1 },
{ "name": "Jane Q. Composer", "role": "songwriter", "order": 1 }
]
}
],
"copyright": "100",
"itunes_cleared_for_stream": "true",
// BINARY upload (traditional):
// "callback_url": "https://your-app.example/hooks/gard-moderation",
"cover": "<binary JPEG/PNG file>",
"audio_files": ["<binary WAV/FLAC/MP3>", "<optional second file>"]
// OR URL-based upload (alternative — files downloaded server-side):
// "cover_url": "https://example.com/cover.jpg",
// "audio_files_urls": ["https://example.com/track1.wav", "https://example.com/track2.mp3"],
// "video_url": "https://example.com/video.mov",
// "booklet_url": "https://example.com/booklet.pdf",
// NOTE: Use binary OR URL for each field — never both. URL files are deleted after upload.
}{
"code": 200,
"msg": "Release submitted",
"moderation_request_id": 42,
"id": "mdr_01jqxyz",
"release_id": null,
"status": "submitted",
"release_name": "My Single",
"has_cover": true,
"audio_count": 2,
"has_video": false,
"has_booklet": false
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
# Cover & audio can be sent as binary parts (shown below) OR as public HTTP(S) URLs
# (use 'cover_url=…' / 'audio_files_urls=[…]'). Send EITHER binary OR URL per field — never both.
# 'artist_roles' must contain at least one 'composer' AND one 'songwriter' (same person OK).
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/moderation/" \
-H "X-API-Key: $GARD_API_KEY" \
-F release_name="My Single" \
-F artist_name="Stage Name" \
-F release_date="2026-04-21" \
-F genre_id=electronic \
-F sub_genre_id=ambient \
-F meta_lang="en" \
-F copyright="100" \
-F platforms='["spotify","youtube_music","apple_music"]' \
-F countries='[]' \
-F artist_roles='[{"name":"Stage Name","role":"artist","order":1},{"name":"Jane Q. Composer","role":"composer","order":1},{"name":"Jane Q. Composer","role":"songwriter","order":1}]' \
-F tracks_meta='[{"name":"Track A","meta_lang":"en","persons":[{"name":"Stage Name","role":"artist","order":1},{"name":"Jane Q. Composer","role":"composer","order":1},{"name":"Jane Q. Composer","role":"songwriter","order":1}]}]' \
-F callback_url='https://your-app.example/hooks/gard-moderation' \
-F cover=@./cover.jpg \
-F audio_files=@./track1.wav
# URL-based alternative — drop the binary -F lines and use:
# -F cover_url=https://example.com/cover.jpg \
# -F audio_files_urls='["https://example.com/track1.wav"]'platforms, countries, artist_roles, tracks_meta, …) must be valid JSON strings. Credits: Single 500 · EP 700 · Album/Compilation 850 (402 if balance too low). Track count limits: Single = 1 track, EP / Mini-Album = 2–6, Album / Compilation = 7–30 (>30 → 422). tracks_meta must have exactly one entry per audio file. callback_url: webhooks include X-Gard-Signature — verify with GET /api/v1/keys/{id}/webhook-signing-secret (see docs/music-distributor.md)./api/v1/music-distributor/moderation/List submissions: { code, msg, submissions: [...] }. Each row: status + human message (vendor-neutral).
{}{
"code": 200,
"msg": "ok",
"submissions": [
{
"moderation_request_id": 42,
"id": "mdr_01jqxyz",
"release_id": 128,
"status": "submitted",
"message": "Release submitted",
"release_name": "My Single",
"artist_name": "Stage Name",
"created_at": "2026-04-21T10:00:00Z"
}
]
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
curl -sS "https://back.gard-api.org/api/v1/music-distributor/moderation/" \ -H "X-API-Key: $GARD_API_KEY"
/api/v1/music-distributor/catalog/reference-dataOne JSON snapshot: platforms, countries, languages, genres_root (each {code, name}), subgenres_by_parent_code (root genre code → subgenres), and optional live_supplement (platform groups, lines, price categories). Send X-API-Key: gard_…. You can cache this response in your integration.
{}{
"platforms": [{ "code": "spotify", "name": "Spotify" }],
"countries": [{ "code": "ru", "name": "Russian Federation" }],
"languages": [{ "code": "en", "name": "English" }],
"genres_root": [{ "code": "electronic", "name": "Electronic" }],
"subgenres_by_parent_code": {
"electronic": [
{ "code": "ambient", "name": "Ambient" },
{ "code": "bass", "name": "Bass" }
]
},
"live_supplement": {
"platform_groups": [],
"lines": [],
"price_categories": []
}
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
curl -sS "https://back.gard-api.org/api/v1/music-distributor/catalog/reference-data" \ -H "X-API-Key: $GARD_API_KEY"
/api/v1/music-distributor/catalog/platformsList DSP platforms as {id, name, platform_name} from the live catalog cache. Prefer GET /catalog/reference-data for {code, name} rows aligned with POST /moderation/ (platforms field). Same auth as other catalog routes.
{}[{ "id": 1, "name": "Spotify", "platform_name": "Spotify" }]/api/v1/music-distributor/catalog/platform-groupsPlatform groupings from cache (for UI filters). reference-data may also include live_supplement.platform_groups.
{}[]
/api/v1/music-distributor/releases/allList releases in your catalog. Optional search, offset, limit. Each row includes release_id (numeric catalog id for GET …/releases/{release_ref}/status), id / public_id (rel_…), status / message (public workflow — same vocabulary as GET /moderation/), plus metadata. admin users may see extra read-only fields (internal_catalog_status, upstream_album_id).
{
"search": "summer",
"offset": 0,
"limit": 50
}[
{
"id": "rel_01abc",
"public_id": "rel_01abc",
"release_id": 123,
"name": "Summer EP",
"type": "EP",
"status": "under_review",
"message": "Under moderation review",
"upc": "886447833821",
"artist_name": "Stage Name",
"label": "Indie",
"genre_name": "Electronic",
"sale_platforms": [],
"has_cover": true,
"comment": null,
"release_date": "2026-06-01",
"last_synced_at": "2026-04-21T11:00:00",
"created_at": "2026-04-20T09:00:00"
}
]Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
curl -sS "https://back.gard-api.org/api/v1/music-distributor/releases/all?search=label&offset=0&limit=50" \ -H "X-API-Key: $GARD_API_KEY"
/api/v1/music-distributor/releases/{release_ref}Get one release. {release_ref} may be: numeric release_id, catalog rel_…, or moderation submission mdr_… (same resolution rules as GET …/status). status / message are the public workflow. Raw distributor fields (upstream_status_data, upstream_album_id, internal_catalog_status) are returned only for admin.
{}{
"id": 123,
"public_id": "rel_01abc",
"name": "Summer EP",
"type": "EP",
"status": "under_review",
"message": "Under moderation review",
"metadata": null,
"upc": "886447833821",
"artist_name": "Stage Name",
"label": "Indie",
"genre_name": "Electronic",
"sale_platforms": [],
"has_cover": true,
"comment": null,
"release_date": "2026-06-01",
"last_synced_at": "2026-04-21T11:00:00",
"tracks": [
{ "track_id": "track_01abc", "position": 1, "title": "Intro", "isrc": "QZ-ES5-26-00001" }
]
}/api/v1/music-distributor/releases/{release_ref}/statusLive distributor snapshot for the release. Path {release_ref} accepts: (1) numeric catalog release_id (md_releases.id, also returned as id in this response and in GET /releases/all as release_id), (2) catalog rel_…, (3) moderation mdr_… (your POST /moderation/ id; resolves to the linked catalog row, then calls the distributor with the stored upstream album id).
{}{
"id": 123,
"public_id": "rel_01abc",
"status": "submitted",
"message": "Release submitted",
"name": "My Single",
"artist_name": "Stage Name",
"album_type": "Single",
"moderation_request_id": 42,
"submission_id": "mdr_01jqxyz",
"upc": "886447833821",
"release_date": "2026-06-01",
"label": "Indie",
"genre_name": "Electronic",
"sale_platforms": [],
"has_cover": true,
"comment": null,
"last_synced_at": "2026-04-21T11:30:00",
"tracks": [
{ "track_id": "track_01abc", "position": 1, "title": "Intro", "isrc": "QZ-ES5-26-00001" },
{ "track_id": "track_01def", "position": 2, "title": "Outro", "isrc": "QZ-ES5-26-00002" }
]
}status / message match GET /moderation/ and webhooks. tracks includes track_id (track_…) per row — same as GET …/tracks; use in POST /analytics/releases. Before delivery track_id may be null. tracks_isrc kept for backward compatibility. Admin-only: internal_catalog_status, upstream_album_id. GET and POST …/sync return the same JSON./api/v1/music-distributor/releases/{release_ref}/syncRe-fetch status and metadata (same as GET …/status). {release_ref} accepts numeric id, rel_…, or mdr_….
{}{
"id": 123,
"public_id": "rel_01abc",
"status": "under_review",
"message": "Under moderation review",
"name": "Summer EP",
"artist_name": "Stage Name",
"album_type": "EP",
"moderation_request_id": 42,
"submission_id": "mdr_01jqxyz",
"upc": "886447833821",
"release_date": "2026-06-01",
"label": "Indie",
"genre_name": "Electronic",
"sale_platforms": [],
"has_cover": true,
"comment": null,
"last_synced_at": "2026-04-21T11:31:00"
}/api/v1/music-distributor/releases/{release_ref}/coverBinary cover art. {release_ref}: numeric id, rel_…, or mdr_….
{}{
"note": "Response body is raw image bytes (JPEG or PNG), not JSON. Content-Type is typically image/jpeg or image/png.",
"example_content_type": "image/jpeg",
"example_content_length": 245678
}/api/v1/music-distributor/releases/persons/search?query=…Search people in the distributor directory (for credits).
{
"query": "Artist"
}{
"code": 200,
"results": [
{ "id": 55, "content_name": "Artist Name", "match_score": 0.98 }
]
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
curl -sS "https://back.gard-api.org/api/v1/music-distributor/releases/persons/search?query=Artist" \ -H "X-API-Key: $GARD_API_KEY"
/api/v1/music-distributor/releases/personsBody: { content_name: string }. Create a person entry.
{
"content_name": "New Artist"
}{
"code": 200,
"person": { "id": 901, "content_name": "New Artist" }
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/releases/persons" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"content_name":"New Artist"}'/api/v1/music-distributor/releases/{release_ref}/video-clipsAlbum video clips list.
{}{
"code": 200,
"clips": [
{ "id": 1, "title": "Official video", "url": "https://cdn.example.com/clip1.mp4", "track_id": null }
]
}/api/v1/music-distributor/releases/{release_ref}/track-video-clipsPer-track video clips.
{}{
"code": 200,
"clips": [
{ "id": 2, "track_id": 1, "title": "Vertical clip", "url": "https://cdn.example.com/t1_clip.mp4" }
]
}/api/v1/music-distributor/releases/{release_ref}/personsAlbum person links.
{}{
"code": 200,
"persons": [
{ "person_id": 55, "role": "artist", "order": 1, "name": "Stage Name" }
]
}/api/v1/music-distributor/releases/{release_ref}/personsAdd album person (body per backend).
{
"person_id": 55,
"order": 1,
"role": "artist"
}{
"code": 200,
"link": { "release_id": 123, "person_id": 55, "role": "artist", "order": 1 }
}/api/v1/music-distributor/releases/{release_ref}/track-personsTrack person links.
{}{
"code": 200,
"track_persons": [
{ "track_id": 1, "person_id": 55, "role": "artist", "order": 1 }
]
}/api/v1/music-distributor/releases/{release_ref}/track-personsAdd track person.
{
"track_id": 1,
"person_id": 55,
"order": 1,
"role": "featured_artist"
}{
"code": 200,
"link": { "track_id": 1, "person_id": 55, "role": "featured_artist", "order": 1 }
}/api/v1/music-distributor/releases/{release_ref}/sort-tracksReorder tracks (body per backend).
{
"track_ids": [3, 1, 2]
}{
"code": 200,
"msg": "order updated"
}/api/v1/music-distributor/releases/{release_ref}/platform-linksDSP storefront links. Returns sale_platforms as { platform_name, link } for all available platforms: Wink, MTS, Yandex Music, Spotify, VK Music, Zvuk.
{}{
"id": 123,
"public_id": "rel_01abc",
"name": "Summer EP",
"upc": "886447833821",
"platforms": [
{ "platform_name": "Wink", "link": "https://music.wink.ru/release/xxxxxxxxxxx" },
{ "platform_name": "Yandex Music", "link": "https://music.yandex.ru/album/xxxxxxxxxxx" },
{ "platform_name": "Spotify", "link": "https://open.spotify.com/album/xxxxxxxxxxx" },
{ "platform_name": "MTS", "link": "https://music.mts.ru/album/xxxxxxxxxxx" },
{ "platform_name": "VK Music", "link": "https://music.vk.com/link/xxxxxxxxxxx" },
{ "platform_name": "Zvuk", "link": "https://zvuk.com/release/xxxxxxxxxxx" }
]
}/api/v1/music-distributor/releases/{release_ref}/revokeDistributor platform moderation withdraw or catalog drop: if the live upstream snapshot maps to internal under_review (staff/platform review, can_revoke + comment_time, codes 1/5, moderation / onedit), calls upstream revoke and sets the catalog row to draft. If not, only removes your Gard catalog row (same as DELETE …/releases/{release_ref} — no upstream revoke). 400 if the release is already live — use POST /delete-requests/ instead.
{}{
"status": "revoked",
"release_id": 128,
"upstream_album_id": 95501
}{"status":"deleted","release_id":128,"upstream_album_id":95501} (catalog row removed only). 400 when workflow is live./api/v1/music-distributor/delete-requests/Takedown queue for releases already live on DSPs. Only accepted when the catalog row’s public status is live (same rules as GET /releases/{release_ref}); otherwise 400 with the current status — use POST …/revoke or DELETE …/releases/{release_ref} for pre-live catalog/moderation handling. The request is processed by the Gard team — poll GET /delete-requests/.
| Field | Type | Required | Description |
|---|---|---|---|
| release_id | string | yes | Opaque public_id of the release. |
| release_name | string | no | For display. |
| artist_name | string | no | For display. |
| upc | string | no | Optional. |
| isrc | string | no | Optional. |
| reason | string | no | Takedown reason. |
{
"release_id": "rel_01abc",
"release_name": "Summer EP",
"artist_name": "Stage Name",
"upc": "886447833821",
"reason": "Artist requested takedown"
}{
"code": 200,
"id": 501,
"status": "pending"
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/delete-requests/" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"release_id":"rel_xxxxxxxx","reason":"Artist request"}'/api/v1/music-distributor/delete-requests/List all takedown requests you have submitted. Status: pending → completed → rejected.
{}{
"code": 200,
"requests": [
{
"id": 501,
"release_id": "rel_01abc",
"status": "pending",
"reason": "Artist requested takedown",
"created_at": "2026-04-20T09:00:00Z"
}
]
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
curl -sS "https://back.gard-api.org/api/v1/music-distributor/delete-requests/" \ -H "X-API-Key: $GARD_API_KEY"
/api/v1/music-distributor/panel/scopeDashboard: artists + releases in your scope. Each release includes release_id (numeric catalog id), status / message (public workflow), and optional admin-only debug fields.
{}{
"artists": ["Stage Name"],
"releases": [
{
"id": "rel_01abc",
"public_id": "rel_01abc",
"release_id": 123,
"name": "Summer EP",
"artist_name": "Stage Name",
"status": "under_review",
"message": "Under moderation review",
"upc": "886447833821",
"release_date": "2026-06-01"
}
]
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
curl -sS "https://back.gard-api.org/api/v1/music-distributor/panel/scope" \ -H "X-API-Key: $GARD_API_KEY"
/api/v1/music-distributor/panel/activity-logAggregated activity. Query: artist, action, limit, offset.
{
"artist": "Stage Name",
"action": "submit",
"limit": 20,
"offset": 0
}{
"code": 200,
"events": [
{
"id": 1001,
"action": "submit",
"entity_type": "release",
"entity_id": "rel_01abc",
"created_at": "2026-04-21T08:00:00Z"
}
],
"total": 42
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
curl -sS "https://back.gard-api.org/api/v1/music-distributor/panel/activity-log?limit=20&offset=0" \ -H "X-API-Key: $GARD_API_KEY"
/api/v1/music-distributor/panel/reports/streaming.csvCSV export of your releases (400 if none).
{}{
"note": "Response body is text/csv, not JSON. HTTP 400 if there is no data to export.",
"example_csv_first_lines": "upc,title,streams\n886447833821,Summer EP,125000\n"
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
curl -sS -o report.csv "https://back.gard-api.org/api/v1/music-distributor/panel/reports/streaming.csv" \ -H "X-API-Key: $GARD_API_KEY"
/api/v1/music-distributor/pitch/Editorial pitch while the release is not yet live in the public workflow (same status resolution as GET /moderation/). Multipart + payload_json string. 400 once live.
| Field | Type | Required | Description |
|---|---|---|---|
| moderation_request_id | integer | yes | Id of the moderation submission this pitch is tied to (from your product / support workflow). |
| payload_json | string (JSON in form) | yes | release_description, artist_bio_achievements, pitch_platforms[] |
| artist_photo | file | no | Optional; max 15 MB; jpg/png/webp. |
{
"_wire_format": "multipart/form-data",
"moderation_request_id": "42",
"payload_json": "<one form field: JSON.stringify of the object below>",
"payload": {
"release_description": "…",
"artist_bio_achievements": "…",
"pitch_platforms": ["spotify", "apple_music"]
},
"artist_photo": "<optional binary>"
}{
"code": 200,
"id": 77,
"status": "received"
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/pitch/" \
-H "X-API-Key: $GARD_API_KEY" \
-F moderation_request_id=1 \
-F payload_json='{"release_description":"…","artist_bio_achievements":"…","pitch_platforms":["spotify"]}'pitch_platforms: yandex_music, vk_music, zvooq, amazon_music, spotify, apple_music — allowed until public live (including sent_to_stores / delivery phases)./api/v1/music-distributor/pitch/List your pitch requests (all statuses: pending, in_progress, completed, rejected).
{}{
"code": 200,
"msg": "OK",
"pitches": [
{
"id": 78,
"moderation_request_id": 42,
"status": "completed",
"pitch_platforms": ["spotify", "apple_music"],
"created_at": "2026-04-19T12:00:00Z",
"updated_at": "2026-04-21T09:30:00Z",
"reviewer_notes": null
},
{
"id": 77,
"moderation_request_id": 41,
"status": "pending",
"pitch_platforms": ["yandex_music"],
"created_at": "2026-04-18T10:00:00Z",
"updated_at": "2026-04-18T10:00:00Z",
"reviewer_notes": null
}
]
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
curl -sS "https://back.gard-api.org/api/v1/music-distributor/pitch/" \ -H "X-API-Key: $GARD_API_KEY"
pitches from this object (not a bare JSON array). Staff actions in the Gard panel set completed, rejected, or in_progress; those rows remain visible here./api/v1/music-distributor/payout/settingsPayout method + details.
{}{
"code": 200,
"method": "paypal",
"details": { "paypal_email": "[email protected]" }
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
curl -sS "https://back.gard-api.org/api/v1/music-distributor/payout/settings" \ -H "X-API-Key: $GARD_API_KEY"
/api/v1/music-distributor/payout/settingsSet payout. JSON: { method: paypal|bank_account|card_swift|card_ru, details?: { … } }.
{
"method": "paypal",
"details": { "paypal_email": "[email protected]" }
}{
"code": 200,
"msg": "settings saved"
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
curl -sS -X PUT "https://back.gard-api.org/api/v1/music-distributor/payout/settings" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"method":"paypal","details":{"paypal_email":"[email protected]"}}'/api/v1/music-distributor/payout/withdrawalsList withdrawals (query limit).
{
"limit": 50
}{
"code": 200,
"withdrawals": [
{
"id": 9001,
"amount_cents": 5000,
"currency": "USD",
"status": "completed",
"created_at": "2026-04-01T00:00:00Z"
}
]
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
curl -sS "https://back.gard-api.org/api/v1/music-distributor/payout/withdrawals?limit=50" \ -H "X-API-Key: $GARD_API_KEY"
/api/v1/music-distributor/payout/withdrawals/requestRequest a withdrawal. JSON: { amount_cents, currency } — min 100 cents.
{
"amount_cents": 5000,
"currency": "USD"
}{
"code": 200,
"withdrawal_id": 9002,
"status": "pending"
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/payout/withdrawals/request" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"amount_cents":5000,"currency":"USD"}'/api/v1/music-distributor/analytics/releases★ Recommended. Batch analytics for up to 100 releases (rel_… and/or mdr_… — mix allowed) in one request. Returns per-release totals, per-platform streams, and per-track (ISRC) breakdowns for the chosen period. Served from the daily report (md_analytics_stream_facts) — no live upstream call.
| Field | Type | Required | Description |
|---|---|---|---|
| releases | string[] | yes | 1–100 release ids. Each may be a release public id (rel_…) or a moderation/submission public id (mdr_…). Mixed lists are allowed; duplicates are de-duplicated. Ids you do not own are returned with found:false (never another tenant's data). |
| period.preset | string | no | Reporting window. One of: last_1d, last_7d, last_28d, last_30d, last_90d, custom. Default: last_28d. There is no 'today' — analytics are only available for previous days; last_* windows end on the latest fully-ingested day (today − 2). Options: last_1d | last_7d | last_28d | last_30d | last_90d | custom |
| period.from / period.to | string (YYYY-MM-DD) | no | Required only when preset = custom. Inclusive date range. |
| include.platforms | boolean | no | Per-platform stream/paid breakdown (release + per track). Default: true. |
| include.countries | boolean | no | Per-country breakdown (release + per track). Default: true. |
| include.tracks | boolean | no | Per-track rows with track_id, isrc, title, streams and paid streams (and per-track by_platform/by_country when those toggles are on). Always true — omit include or set false; the API still returns tracks. |
| include.devices / include.os / include.age / include.gender | boolean | no | Optional secondary demographic/technical breakdowns (yes/no). Default: false — turn on only what you need to keep responses small. |
| include.timeseries | boolean | no | Per-day stream/paid series for each release. Default: false. |
// Last 28 days, default breakdowns (platforms + countries + tracks):
{
"releases": ["rel_ExampleId123", "mdr_ExampleSubmission9"],
"period": { "preset": "last_28d" }
}
// One day, with demographic breakdowns turned on:
{
"releases": ["rel_ExampleId123"],
"period": { "preset": "last_1d" },
"include": {
"platforms": true,
"countries": true,
"tracks": true,
"devices": true,
"age": true,
"gender": true,
"timeseries": false
}
}
// Custom date range:
{
"releases": ["rel_ExampleId123", "rel_ExampleId456"],
"period": { "preset": "custom", "from": "2026-05-01", "to": "2026-05-29" },
"include": { "platforms": true, "countries": false, "tracks": true }
}{
"period": { "preset": "last_28d", "from": "2026-05-02", "to": "2026-05-29" },
"include": { "platforms": true, "countries": true, "tracks": true, "devices": false, "os": false, "age": false, "gender": false, "timeseries": false },
"requested": 2,
"found": 1,
"releases": [
{
"ref": "rel_ExampleId123",
"found": true,
"release": {
"public_id": "rel_ExampleId123",
"name": "Sunset Stories",
"artist": "Aurora Nightingale",
"upc": "5060000000001"
},
"totals": { "streams": 18452, "pay_streams": 9120 },
"by_platform": [
{ "name": "VKontakte", "streams": 15230, "pay_streams": 7610 },
{ "name": "Spotify", "streams": 1180, "pay_streams": 720 },
{ "name": "Yandex Music", "streams": 760, "pay_streams": 410 },
{ "name": "Apple Music", "streams": 540, "pay_streams": 300 },
{ "name": "Zvuk", "streams": 300, "pay_streams": 150 },
{ "name": "MTS Music", "streams": 180, "pay_streams": 70 },
{ "name": "Deezer", "streams": 120, "pay_streams": 30 },
{ "name": "YouTube Music", "streams": 80, "pay_streams": 20 },
{ "name": "Amazon Music", "streams": 42, "pay_streams": 10 },
{ "name": "Tidal", "streams": 20, "pay_streams": 0 }
],
"by_country": [
{ "name": "Russia", "streams": 16110, "pay_streams": 8020 },
{ "name": "Belarus", "streams": 720, "pay_streams": 360 },
{ "name": "Kazakhstan", "streams": 540, "pay_streams": 250 }
],
"tracks": [
{
"track_id": "track_ExampleTrackA",
"isrc": "QZ-ABC-26-00001",
"title": "Sunset Stories",
"streams": 12010,
"pay_streams": 6300,
"by_platform": [
{ "name": "VKontakte", "streams": 9900, "pay_streams": 5200 },
{ "name": "Spotify", "streams": 820, "pay_streams": 510 }
],
"by_country": [
{ "name": "Russia", "streams": 10800, "pay_streams": 5600 },
{ "name": "Belarus", "streams": 410, "pay_streams": 220 }
]
},
{
"track_id": "track_ExampleTrackB",
"isrc": "QZ-ABC-26-00002",
"title": "Afterglow",
"streams": 6442,
"pay_streams": 2820,
"by_platform": [
{ "name": "VKontakte", "streams": 5330, "pay_streams": 2410 }
],
"by_country": [
{ "name": "Russia", "streams": 5310, "pay_streams": 2420 }
]
}
]
},
{
"ref": "mdr_ExampleSubmission9",
"found": false,
"error": "not_found_or_forbidden"
}
]
}ref is ownership-checked independently — refs you don't own (or that don't exist) come back as {found:false, error:"not_found_or_forbidden"} instead of leaking data. Period: use preset (last_1d / last_7d / last_28d / last_30d / last_90d) or custom with from+to — there is no today (analytics exist only for previous days). last_* windows end at the latest fully-ingested day (today − 2, because analytics are collected nightly at 00:00 for the day-before-previous). Secondary breakdowns (devices, os, age, gender, timeseries) are off by default — switch on only what you need. Release roll-ups aggregate every track of the release by UPC; per-track rows are keyed by ISRC. All platforms present in the daily report are returned automatically (no fixed list). Use the rel_… id from GET /releases/all or the mdr_… id from your submission. For single-release convenience there is also GET /analytics/release/{ref} and GET /analytics/track/{track_ref}./api/v1/music-distributor/analytics/summary/filtersAnalytics filter metadata (catalog-scoped).
{}{
"code": 200,
"date_ranges": ["last_7d", "last_28d", "last_90d"],
"metrics": ["streams", "listeners"],
"albums": [{ "catalog_album_id": "ca_1", "title": "Summer EP" }]
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
curl -sS "https://back.gard-api.org/api/v1/music-distributor/analytics/summary/filters" \ -H "X-API-Key: $GARD_API_KEY"
true = snapshot, facts = per-album aggregation). Full contract: docs/music-distributor.md (Analytics)./api/v1/music-distributor/analytics/summary/tableCross-store table (all DSPs combined in this upstream view). Minimal POST body; Gard adds date range and Cabinet custom_filters from your catalog.
// Whole catalog (default 31-day window):
{
"filters": {}
}
// One release:
{
"filters": { "release_public_ids": ["rel_ExampleId123"] }
}
// By artist + custom date range:
{
"filters": { "artist_names": ["Aurora Nightingale"] },
"from": "2026-04-01",
"to": "2026-04-30"
}{
"pages": 1,
"page": 0,
"columns": ["cover", "track", "artist", "album", "country", "streams", "pay_streams"],
"data": [
{
"track": "Sample Track Name",
"artist": "Aurora Nightingale",
"album": "Sunset Stories",
"album_id": 38588899,
"country": "ru",
"streams": 49,
"pay_streams": 47
}
],
"order": {}
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
# Whole catalog (default 31-day window):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/summary/table" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{}}'
# One release (use rel_… id from GET /releases/all):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/summary/table" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"release_public_ids":["rel_ExampleId123"]}}'
# By artist + custom date range:
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/summary/table" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"artist_names":["Aurora Nightingale"]},"from":"2026-04-01","to":"2026-04-30"}'{"filters":{}} is enough (Gard sets from/to when omitted). All analytics POST endpoints share the same filter shape — same keys work for summary/*, spotify/*, yandex/*, applemusic/*, vkclips/*, umavk/*, mts/*, zvooq/*. Narrow by: filters.release_public_ids: ["rel_…"] — use the rel_… id from GET /releases/all (not mdr_…). Also: filters.album_ids: [38588899], filters.artist_names: ["Aurora Nightingale"]. Combine to take the union. Pass from/to (ISO dates) for any custom range — Gard aggregates per-day facts from its own Postgres (no live upstream call). Legacy back-compat: top-level gard_release_public_id / gard_analytics_album_ids / gard_artist_names. Unknown id → 400 (no silent widening). No data yet → 503 with Retry-After: 30 — Gard schedules a background fill so the next call lands. Response: table payloads use pages, data./api/v1/music-distributor/analytics/spotify/tableSpotify analytics table (JSON body). Same minimal POST contract as summary analytics.
// Whole catalog:
{
"filters": {}
}
// One release:
{
"filters": { "release_public_ids": ["rel_ExampleId123"] }
}
// Custom date range:
{
"filters": {},
"from": "2026-04-01",
"to": "2026-04-30"
}{
"pages": 1,
"page": 0,
"columns": ["track", "isrc", "streams"],
"data": [{ "track": "Track A", "isrc": "USXXX2400001", "streams": 80000 }],
"order": {}
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
# Whole catalog:
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/spotify/table" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{}}'
# One release:
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/spotify/table" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"release_public_ids":["rel_ExampleId123"]}}'/api/v1/music-distributor/analytics/applemusic/tableApple Music analytics table.
// Whole catalog:
{
"filters": {}
}
// One release:
{
"filters": { "release_public_ids": ["rel_ExampleId123"] }
}{
"pages": 1,
"page": 0,
"columns": ["album", "plays"],
"data": [{ "album": "Summer EP", "plays": 60000 }],
"order": {}
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
# Whole catalog:
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/applemusic/table" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{}}'
# One release:
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/applemusic/table" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"release_public_ids":["rel_ExampleId123"]}}'/api/v1/music-distributor/analytics/spotify/filtersSpotify analytics filter metadata (catalog-scoped). Same prerequisite as other analytics routes.
{}{
"filters": { "date_range": ["last_7d", "last_28d"] },
"dimensions": ["track", "album"],
"metrics": ["streams"]
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
curl -sS "https://back.gard-api.org/api/v1/music-distributor/analytics/spotify/filters" \ -H "X-API-Key: $GARD_API_KEY"
/api/v1/music-distributor/analytics/spotify/graphSpotify — daily time-series graph.
// Whole catalog:
{
"filters": {}
}
// One release + custom range:
{
"filters": { "release_public_ids": ["rel_ExampleId123"] },
"from": "2026-04-01",
"to": "2026-04-30"
}
// By artist:
{
"filters": { "artist_names": ["Aurora Nightingale"] }
}{
"lines": ["all_streams", "all_paidstreams", "all_lyrics", "all_canvas", "all_uniq"],
"data": [
{
"name": "2026-05-11",
"all_streams": 965,
"all_paidstreams": 406,
"all_lyrics": 0,
"all_canvas": 0,
"all_uniq": 582
}
]
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
# Whole catalog (no filters):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/spotify/graph" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{}}'
# One release (use rel_… id from GET /releases/all):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/spotify/graph" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"release_public_ids":["rel_ExampleId123"]}}'
# By artist + custom date range:
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/spotify/graph" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"artist_names":["Aurora Nightingale"]},"from":"2026-04-01","to":"2026-04-30"}'lines (metric keys) and data (points; name is usually an ISO date). Keys vary by DSP./api/v1/music-distributor/analytics/spotify/barSpotify — bar chart payload (proxied).
// Whole catalog:
{
"filters": {}
}
// One release:
{
"filters": { "release_public_ids": ["rel_ExampleId123"] }
}{
"bars": [{ "label": "US", "value": 40000 }]
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
# Whole catalog (no filters):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/spotify/bar" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{}}'
# One release (use rel_… id from GET /releases/all):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/spotify/bar" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"release_public_ids":["rel_ExampleId123"]}}'
# By artist + custom date range:
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/spotify/bar" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"artist_names":["Aurora Nightingale"]},"from":"2026-04-01","to":"2026-04-30"}'/api/v1/music-distributor/analytics/summary/graph/mainCross-store summary — main trend graph.
// Whole catalog:
{
"filters": {}
}
// One release + custom range:
{
"filters": { "release_public_ids": ["rel_ExampleId123"] },
"from": "2026-04-01",
"to": "2026-04-30"
}{
"lines": ["all_streams", "all_paidstreams"],
"data": [{ "name": "2026-05-11", "all_streams": 12000, "all_paidstreams": 4100 }]
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
# Whole catalog (no filters):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/summary/graph/main" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{}}'
# One release (use rel_… id from GET /releases/all):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/summary/graph/main" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"release_public_ids":["rel_ExampleId123"]}}'
# By artist + custom date range:
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/summary/graph/main" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"artist_names":["Aurora Nightingale"]},"from":"2026-04-01","to":"2026-04-30"}'/api/v1/music-distributor/analytics/summary/graph/totalCross-store summary — totals graph.
// Whole catalog:
{
"filters": {}
}
// By artist:
{
"filters": { "artist_names": ["Aurora Nightingale"] }
}{
"lines": ["all_streams"],
"data": [{ "name": "2026-05-11", "all_streams": 250000 }]
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
# Whole catalog (no filters):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/summary/graph/total" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{}}'
# One release (use rel_… id from GET /releases/all):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/summary/graph/total" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"release_public_ids":["rel_ExampleId123"]}}'
# By artist + custom date range:
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/summary/graph/total" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"artist_names":["Aurora Nightingale"]},"from":"2026-04-01","to":"2026-04-30"}'/api/v1/music-distributor/analytics/summary/graph/countryCross-store summary — breakdown by country.
// Whole catalog:
{
"filters": {}
}
// One release:
{
"filters": { "release_public_ids": ["rel_ExampleId123"] }
}{
"lines": ["all_streams"],
"data": [{ "name": "US", "all_streams": 80000 }]
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
# Whole catalog (no filters):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/summary/graph/country" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{}}'
# One release (use rel_… id from GET /releases/all):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/summary/graph/country" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"release_public_ids":["rel_ExampleId123"]}}'
# By artist + custom date range:
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/summary/graph/country" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"artist_names":["Aurora Nightingale"]},"from":"2026-04-01","to":"2026-04-30"}'/api/v1/music-distributor/analytics/summary/graph/osCross-store summary — breakdown by OS.
// Whole catalog:
{
"filters": {}
}
// One release:
{
"filters": { "release_public_ids": ["rel_ExampleId123"] }
}{
"lines": ["all_streams"],
"data": [{ "name": "iOS", "all_streams": 50000 }]
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
# Whole catalog (no filters):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/summary/graph/os" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{}}'
# One release (use rel_… id from GET /releases/all):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/summary/graph/os" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"release_public_ids":["rel_ExampleId123"]}}'
# By artist + custom date range:
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/summary/graph/os" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"artist_names":["Aurora Nightingale"]},"from":"2026-04-01","to":"2026-04-30"}'/api/v1/music-distributor/analytics/summary/graph/device_typeCross-store summary — breakdown by device type.
// Whole catalog:
{
"filters": {}
}
// One release:
{
"filters": { "release_public_ids": ["rel_ExampleId123"] }
}{
"lines": ["all_streams"],
"data": [{ "name": "mobile", "all_streams": 90000 }]
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
# Whole catalog (no filters):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/summary/graph/device_type" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{}}'
# One release (use rel_… id from GET /releases/all):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/summary/graph/device_type" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"release_public_ids":["rel_ExampleId123"]}}'
# By artist + custom date range:
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/summary/graph/device_type" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"artist_names":["Aurora Nightingale"]},"from":"2026-04-01","to":"2026-04-30"}'/api/v1/music-distributor/analytics/summary/graph/ageCross-store summary — age buckets (whole-catalog only, not per-release).
// Whole catalog only (per-release not supported for age/gender):
{
"filters": {}
}{
"lines": ["all_streams"],
"data": [{ "name": "18-24", "all_streams": 30000 }]
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
# Whole catalog (no filters):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/summary/graph/age" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{}}'
# One release (use rel_… id from GET /releases/all):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/summary/graph/age" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"release_public_ids":["rel_ExampleId123"]}}'
# By artist + custom date range:
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/summary/graph/age" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"artist_names":["Aurora Nightingale"]},"from":"2026-04-01","to":"2026-04-30"}'/api/v1/music-distributor/analytics/summary/graph/genderCross-store summary — gender breakdown (whole-catalog only, not per-release).
// Whole catalog only (per-release not supported for age/gender):
{
"filters": {}
}{
"lines": ["all_streams"],
"data": [{ "name": "female", "all_streams": 70000 }]
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
# Whole catalog (no filters):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/summary/graph/gender" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{}}'
# One release (use rel_… id from GET /releases/all):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/summary/graph/gender" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"release_public_ids":["rel_ExampleId123"]}}'
# By artist + custom date range:
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/summary/graph/gender" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"artist_names":["Aurora Nightingale"]},"from":"2026-04-01","to":"2026-04-30"}'/api/v1/music-distributor/analytics/summary/statsCross-store summary — per-platform totals for the caller's catalog or a release/artist subset.
{
"filters": {
"release_public_ids": ["rel_…"]
},
"from": "2026-04-20",
"to": "2026-05-15"
}{
"data": [
{ "name": "yandex", "streams": 128 },
{ "name": "umavk", "streams": 436 },
{ "name": "spotify", "streams": 0 }
],
"lines": ["streams"]
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
# Whole catalog (no filters):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/summary/stats" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{}}'
# One release (use rel_… id from GET /releases/all):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/summary/stats" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"release_public_ids":["rel_ExampleId123"]}}'
# By artist + custom date range:
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/summary/stats" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"artist_names":["Aurora Nightingale"]},"from":"2026-04-01","to":"2026-04-30"}'filters.release_public_ids — use the rel_… id from GET /releases/all (not mdr_…). Also: filters.album_ids (raw upstream ids), filters.artist_names (case-insensitive). Omit all for whole-catalog. Pass from/to for any custom range — aggregation runs against Gard's daily per-album fact table. Legacy: top-level gard_release_public_id / gard_analytics_album_ids / gard_artist_names. Unknown id → 400. No data yet → 503 with Retry-After: 30 — Gard schedules a background fill./api/v1/music-distributor/analytics/applemusic/filtersApple Music analytics filter metadata.
{}{
"filters": { "date_range": ["last_7d", "last_28d"] },
"dimensions": ["album", "track"],
"metrics": ["plays", "listeners"]
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
curl -sS "https://back.gard-api.org/api/v1/music-distributor/analytics/applemusic/filters" \ -H "X-API-Key: $GARD_API_KEY"
/api/v1/music-distributor/analytics/applemusic/graphApple Music — graph series.
// Whole catalog:
{
"filters": {}
}
// One release:
{
"filters": { "release_public_ids": ["rel_ExampleId123"] }
}{
"lines": ["all_plays"],
"data": [{ "name": "2026-05-11", "all_plays": 1200 }]
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
# Whole catalog (no filters):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/applemusic/graph" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{}}'
# One release (use rel_… id from GET /releases/all):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/applemusic/graph" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"release_public_ids":["rel_ExampleId123"]}}'
# By artist + custom date range:
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/applemusic/graph" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"artist_names":["Aurora Nightingale"]},"from":"2026-04-01","to":"2026-04-30"}'/api/v1/music-distributor/analytics/applemusic/graph/totalApple Music — totals graph.
// Whole catalog:
{
"filters": {}
}
// One release:
{
"filters": { "release_public_ids": ["rel_ExampleId123"] }
}{
"lines": ["all_plays"],
"data": [{ "name": "2026-05-11", "all_plays": 60000 }]
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
# Whole catalog (no filters):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/applemusic/graph/total" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{}}'
# One release (use rel_… id from GET /releases/all):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/applemusic/graph/total" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"release_public_ids":["rel_ExampleId123"]}}'
# By artist + custom date range:
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/applemusic/graph/total" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"artist_names":["Aurora Nightingale"]},"from":"2026-04-01","to":"2026-04-30"}'/api/v1/music-distributor/analytics/applemusic/barApple Music — bar chart.
// Whole catalog:
{
"filters": {}
}
// One release:
{
"filters": { "release_public_ids": ["rel_ExampleId123"] }
}{
"bars": [{ "label": "Worldwide", "value": 60000 }]
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
# Whole catalog (no filters):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/applemusic/bar" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{}}'
# One release (use rel_… id from GET /releases/all):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/applemusic/bar" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"release_public_ids":["rel_ExampleId123"]}}'
# By artist + custom date range:
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/applemusic/bar" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"artist_names":["Aurora Nightingale"]},"from":"2026-04-01","to":"2026-04-30"}'/api/v1/music-distributor/analytics/vkclips/filtersVK Clips analytics filter metadata.
{}{
"filters": { "date_range": ["last_7d", "last_28d"] },
"metrics": ["views"]
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
curl -sS "https://back.gard-api.org/api/v1/music-distributor/analytics/vkclips/filters" \ -H "X-API-Key: $GARD_API_KEY"
/api/v1/music-distributor/analytics/vkclips/tableVK Clips analytics table.
// Whole catalog:
{
"filters": {}
}
// One release:
{
"filters": { "release_public_ids": ["rel_ExampleId123"] }
}{
"pages": 1,
"page": 0,
"columns": ["clip", "views"],
"data": [],
"order": {}
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
# Whole catalog (no filters):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/vkclips/table" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{}}'
# One release (use rel_… id from GET /releases/all):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/vkclips/table" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"release_public_ids":["rel_ExampleId123"]}}'
# By artist + custom date range:
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/vkclips/table" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"artist_names":["Aurora Nightingale"]},"from":"2026-04-01","to":"2026-04-30"}'/api/v1/music-distributor/analytics/vkclips/graphVK Clips — graph.
// Whole catalog:
{
"filters": {}
}
// One release:
{
"filters": { "release_public_ids": ["rel_ExampleId123"] }
}{
"lines": ["all_streams"],
"data": []
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
# Whole catalog (no filters):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/vkclips/graph" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{}}'
# One release (use rel_… id from GET /releases/all):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/vkclips/graph" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"release_public_ids":["rel_ExampleId123"]}}'
# By artist + custom date range:
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/vkclips/graph" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"artist_names":["Aurora Nightingale"]},"from":"2026-04-01","to":"2026-04-30"}'/api/v1/music-distributor/analytics/vkclips/graph/totalVK Clips — totals graph.
// Whole catalog:
{
"filters": {}
}
// One release:
{
"filters": { "release_public_ids": ["rel_ExampleId123"] }
}{
"totals": { "views": 15000 }
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
# Whole catalog (no filters):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/vkclips/graph/total" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{}}'
# One release (use rel_… id from GET /releases/all):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/vkclips/graph/total" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"release_public_ids":["rel_ExampleId123"]}}'
# By artist + custom date range:
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/vkclips/graph/total" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"artist_names":["Aurora Nightingale"]},"from":"2026-04-01","to":"2026-04-30"}'/api/v1/music-distributor/analytics/yandex/tableYandex Music — analytics table.
// Whole catalog:
{
"filters": {}
}
// One release + custom range:
{
"filters": { "release_public_ids": ["rel_ExampleId123"] },
"from": "2026-04-01",
"to": "2026-04-30"
}{
"pages": 1,
"page": 0,
"columns": ["track", "streams", "royalty_streams"],
"data": [{ "track": "Track A", "streams": 800, "royalty_streams": 600 }],
"order": {}
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
# Whole catalog (no filters):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/yandex/table" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{}}'
# One release (use rel_… id from GET /releases/all):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/yandex/table" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"release_public_ids":["rel_ExampleId123"]}}'
# By artist + custom date range:
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/yandex/table" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"artist_names":["Aurora Nightingale"]},"from":"2026-04-01","to":"2026-04-30"}'/api/v1/music-distributor/analytics/yandex/graphYandex Music — daily graph.
// Whole catalog:
{
"filters": {}
}
// By artist:
{
"filters": { "artist_names": ["Aurora Nightingale"] }
}{
"lines": ["all_streams", "all_paidstreams"],
"data": [{ "name": "2026-05-11", "all_streams": 120, "all_paidstreams": 90 }]
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
# Whole catalog (no filters):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/yandex/graph" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{}}'
# One release (use rel_… id from GET /releases/all):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/yandex/graph" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"release_public_ids":["rel_ExampleId123"]}}'
# By artist + custom date range:
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/yandex/graph" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"artist_names":["Aurora Nightingale"]},"from":"2026-04-01","to":"2026-04-30"}'/api/v1/music-distributor/analytics/umavk/tableUMA / VK music — analytics table.
// Whole catalog:
{
"filters": {}
}
// One release:
{
"filters": { "release_public_ids": ["rel_ExampleId123"] }
}{
"pages": 1,
"page": 0,
"columns": ["track", "streams"],
"data": [],
"order": {}
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
# Whole catalog (no filters):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/umavk/table" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{}}'
# One release (use rel_… id from GET /releases/all):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/umavk/table" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"release_public_ids":["rel_ExampleId123"]}}'
# By artist + custom date range:
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/umavk/table" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"artist_names":["Aurora Nightingale"]},"from":"2026-04-01","to":"2026-04-30"}'/api/v1/music-distributor/analytics/umavk/graphUMA / VK music — daily graph.
// Whole catalog:
{
"filters": {}
}
// One release:
{
"filters": { "release_public_ids": ["rel_ExampleId123"] }
}{
"lines": ["all_streams"],
"data": [{ "name": "2026-05-11", "all_streams": 50 }]
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
# Whole catalog (no filters):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/umavk/graph" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{}}'
# One release (use rel_… id from GET /releases/all):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/umavk/graph" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"release_public_ids":["rel_ExampleId123"]}}'
# By artist + custom date range:
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/umavk/graph" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"artist_names":["Aurora Nightingale"]},"from":"2026-04-01","to":"2026-04-30"}'/api/v1/music-distributor/analytics/mts/tableMTS Music — analytics table.
// Whole catalog:
{
"filters": {}
}
// One release:
{
"filters": { "release_public_ids": ["rel_ExampleId123"] }
}{
"pages": 1,
"page": 0,
"columns": ["track", "streams"],
"data": [],
"order": {}
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
# Whole catalog (no filters):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/mts/table" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{}}'
# One release (use rel_… id from GET /releases/all):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/mts/table" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"release_public_ids":["rel_ExampleId123"]}}'
# By artist + custom date range:
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/mts/table" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"artist_names":["Aurora Nightingale"]},"from":"2026-04-01","to":"2026-04-30"}'/api/v1/music-distributor/analytics/mts/graphMTS Music — daily graph.
// Whole catalog:
{
"filters": {}
}
// One release:
{
"filters": { "release_public_ids": ["rel_ExampleId123"] }
}{
"lines": ["all_streams"],
"data": [{ "name": "2026-05-11", "all_streams": 30 }]
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
# Whole catalog (no filters):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/mts/graph" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{}}'
# One release (use rel_… id from GET /releases/all):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/mts/graph" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"release_public_ids":["rel_ExampleId123"]}}'
# By artist + custom date range:
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/mts/graph" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"artist_names":["Aurora Nightingale"]},"from":"2026-04-01","to":"2026-04-30"}'/api/v1/music-distributor/analytics/zvooq/tableZvooq — analytics table.
// Whole catalog:
{
"filters": {}
}
// One release:
{
"filters": { "release_public_ids": ["rel_ExampleId123"] }
}{
"pages": 1,
"page": 0,
"columns": ["track", "streams"],
"data": [],
"order": {}
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
# Whole catalog (no filters):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/zvooq/table" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{}}'
# One release (use rel_… id from GET /releases/all):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/zvooq/table" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"release_public_ids":["rel_ExampleId123"]}}'
# By artist + custom date range:
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/zvooq/table" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"artist_names":["Aurora Nightingale"]},"from":"2026-04-01","to":"2026-04-30"}'/api/v1/music-distributor/analytics/zvooq/graphZvooq — daily graph.
// Whole catalog:
{
"filters": {}
}
// One release:
{
"filters": { "release_public_ids": ["rel_ExampleId123"] }
}{
"lines": ["all_streams"],
"data": [{ "name": "2026-05-11", "all_streams": 20 }]
}Base URL: https://back.gard-api.org. Export GARD_API_KEY in your shell to a key from Dashboard → API Keys (gard_…).
# Whole catalog (no filters):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/zvooq/graph" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{}}'
# One release (use rel_… id from GET /releases/all):
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/zvooq/graph" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"release_public_ids":["rel_ExampleId123"]}}'
# By artist + custom date range:
curl -sS -X POST "https://back.gard-api.org/api/v1/music-distributor/analytics/zvooq/graph" \
-H "X-API-Key: $GARD_API_KEY" \
-H "Content-Type: application/json" \
-d '{"filters":{"artist_names":["Aurora Nightingale"]},"from":"2026-04-01","to":"2026-04-30"}'Moderation webhooks (`callback_url`)
**`callback_url`** — any HTTPS URL you host (path is yours). Same `multipart` as `POST …/moderation/`. Each POST is **`Content-Type: application/json; charset=utf-8`** with **`X-Gard-Signature: sha256=…`** = HMAC-SHA256(secret, raw body). Secret: **`GET /api/v1/keys/{id}/webhook-signing-secret`** for the `gard_…` key used on submit, or server **`GARD_WEBHOOK_HMAC_SECRET`** / **`SECRET_KEY`** if you used JWT only. Reply **2xx**; retries are best-effort.
Two JSON events (same workflow_status vocabulary as GET /moderation/): moderation_status on lifecycle transitions (deduped server-side), and moderation_decision when staff approves or rejects. For sent_to_stores / live, payloads may include a catalog block (UPC, tracks, ISRC). Each POST includes X-Gard-Signature: sha256=… (HMAC over the exact JSON bytes). Full spec: export Markdown or docs/music-distributor.md § Moderation callbacks.
POST https://example.com/your-webhook
Content-Type: application/json; charset=utf-8
X-Gard-Signature: sha256=abc123def456…
{
"event": "moderation_status",
"moderation_request_id": 42,
"submission_id": "mdr_…",
"workflow_status": "under_review",
"message": "In review",
"release_name": "My Single",
"artist_name": "Stage Name",
"release_id": 128
}POST https://example.com/your-webhook
Content-Type: application/json; charset=utf-8
X-Gard-Signature: sha256=abc123def456…
{
"event": "moderation_decision",
"moderation_request_id": 42,
"submission_id": "mdr_…",
"status": "approved",
"workflow_status": "sent_to_stores",
"workflow_message": "Sent to stores",
"release_name": "My Single",
"upstream_album_id": 12345,
"release_id": 128,
"moderator_notes": "…"
}