Gard Music Distributor

140+ platforms
https://back.gard-api.org/api/v1/music-distributor

Public 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:

1. submitted — sent 2. under_review — in review 3. sent_to_stores — approved 4. live — released 5. rejected — needs edits
Checking your release status: call GET …/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: - submittedDELETE …/releases/{release_ref} — cancels the upload and removes it from your catalog. - under_reviewPOST …/releases/{release_ref}/revoke — withdraws the release from platform review. - sent_to_stores or livePOST /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_…).

Base URL
https://back.gard-api.org
curl 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.

Cover art (required unless backend relaxes — submit flow expects cover)
  • FormatsJPEG or PNG only.
  • SquareWidth must equal height.
  • ResolutionBetween 1400×1400 and 6000×6000 px.
  • DPI≥ 72.
  • File size≤ 20 MB.
  • ColourRGB (no CMYK-only uploads).
Audio (required: at least one file)
  • FormatsWAV, FLAC, or MP3 on upload; server may convert to WAV for delivery.
  • DurationEach track ≥ 4 seconds (validated server-side when ffprobe/wave available).
  • Size≤ 1 GB per file.
  • NamingUse ASCII-safe filenames; order of files matches order of `tracks_meta` entries.
Video (optional — Apple Music style)
  • Container.mov or .mp4.
  • Resolution1920×1080 or 3840×2160 when validated.
  • Size≤ 6 GB.
Digital booklet (optional)
  • FormatPDF only (valid %PDF- header).
  • Size≤ 10 MB.
URL-based upload (alternative to binary files)
  • Supported fieldscover_url, audio_files_urls, video_url, booklet_url.
  • FormatPublic HTTP(S) URLs only. Max 50 MB per URL. Max 30 audio URLs per request (`audio_files_urls`).
  • Mutual exclusionProvide either binary file OR URL for each field — never both.
  • CleanupURL 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.

Platforms
codeName
7digital7digital
acrcloudACRCloud
amazon_musicAmazon Music
anghamiAnghami
apple_musicApple Music
audiblemagicAudibleMagic
awaAWA
base_ndaBASE_NDA
beeline_kzBeeLine KZ
beeline_t2_ringbacktoneBeeline, t2 (RingBackTone)
clicknclearClicknClear
cron_telecomCron Telecom
deezerDeezer
floFLO
fonmixFonMix
gomusicGoMusic
iheartiHeart
jaxstaJaxsta
jiosaavnJioSaavn
kkboxKKBOX
likeeLikee
line_music_rythmLINE MUSIC / Rythm
lyricfindLyricFind
megafon_ringbacktoneMegaFon (RingBackTone)
mixcloudMixcloud
mobi_musicmobi music
mobi_music_kzMobi Music KZ
mts_ringbacktoneMTS (RingBackTone)
musixmatchMusixMatch
neteaseNetease
other_distributionOther distribution
pandoraPandora
pelotonPeloton
presto_musicPresto Music
pretzelPretzel
rao_russian_authors_societyRAO (Russian Authors' Society)
ringbacktone_partnerRingBackTone-Partner
smuleSmule
soundcloudSoundCloud
soundexchangeSoundExchange
spotifySpotify
spotify_videoSpotify Video
tencentTencent
tidalTIDAL
tiktokTikTok
trebelTREBEL
vk_musicVK Music
vk_videoVK Video
vois_russian_organization_for_intellectual_propertyVOIS (Russian Organization for Intellectual Property)
yandex_musicYandex Music
yandex_videoYandex Video
youtube_sound_recordingYouTube (Sound Recording)
youtube_copyrightYouTube Copyright
youtube_musicYouTube Music
zvuk_wink_musicZvuk / Wink Music
Countries / territories
codeName
afAfghanistan
axAland Islands
alAlbania
dzAlgeria
asAmerican Samoa
adAndorra
aoAngola
aiAnguilla
aqAntarctica
agAntigua And Barbuda
arArgentina
amArmenia
awAruba
auAustralia
atAustria
azAzerbaijan
bsBahamas
bhBahrain
bdBangladesh
bbBarbados
byBelarus
beBelgium
bzBelize
bjBenin
bmBermuda
btBhutan
boBolivia
bqBonaire
baBosnia And Herzegowina
bwBotswana
bvBouvet Island
brBrazil
ioBritish Indian Ocean Territory
vgBritish Virgin Islands
bnBrunei Darussalam
bgBulgaria
bfBurkina Faso
biBurundi
khCambodia
cmCameroon
caCanada
cvCape Verde
kyCayman Islands
cfCentral African Republic
tdChad
clChile
cxChristmas Island
cisCIS
ccCocos (Keeling) Islands
coColombia
kmComoros
ckCook Islands
crCosta Rica
ciCote D`Ivoire
hrCroatia
cuCuba
cyCyprus
czCzech Republic
kpDemocratic People's Republic of Korea
cdDemocratic Republic of Congo
dkDenmark
djDjibouti
dmDominica
doDominican Republic
tlEast Timor
ecEcuador
egEgypt
svEl Salvador
gqEquatorial Guinea
erEritrea
eeEstonia
etEthiopia
fkFalkland Islands (Malvinas)
foFaroe Islands
fmFederal States of Micronesia
fjFiji
fiFinland
frFrance
gfFrench Guiana
pfFrench Polynesia
tfFrench Southern Territories
gaGabon
gmGambia
geGeorgia
deGermany
ghGhana
giGibraltar
grGreece
glGreenland
gdGrenada
gpGuadeloupe
guGuam
gtGuatemala
ggGuernsey
gnGuinea
gwGuinea-Bissau
gyGuyana
htHaiti
hmHeard And Mc Donald Islands
vaHoly See (Vatican City State)
hnHonduras
hkHong Kong
huHungary
isIceland
inIndia
idIndonesia
irIran
iqIraq
ieIreland
imIsle of Man
ilIsrael
itItaly
jmJamaica
jpJapan
jeJersey
joJordan
kzKazakhstan
keKenya
kiKiribati
xkKosovo
kwKuwait
kgKyrgyzstan
laLaos 
lvLatvia
lbLebanon
lsLesotho
lrLiberia
lyLibyan Arab Jamahiriya
liLiechtenstein
ltLithuania
luLuxembourg
moMacau
mkMacedonia
mgMadagascar
mwMalawi
myMalaysia
mvMaldives
mlMali
mtMalta
mhMarshall Islands
mqMartinique
mrMauritania
muMauritius
ytMayotte
mxMexico
mdMoldova
mcMonaco
mnMongolia
meMontenegro
msMontserrat
maMorocco
mzMozambique
mmMyanmar
naNamibia
nrNauru
npNepal
nlNetherlands
anNetherlands Antilles
ncNew Caledonia
nzNew Zealand
niNicaragua
neNiger
ngNigeria
nuNiue
nfNorfolk Island
mpNorthern Mariana Islands
noNorway
omOman
pkPakistan
pwPalau
psPalestine
paPanama
pgPapua New Guinea
pyParaguay
pePeru
phPhilippines
pnPitcairn
plPoland
ptPortugal
cnPRC
prPuerto Rico
qaQatar
cgRepublic of Congo
krRepublic of Korea
reReunion
roRomania
ruRussian Federation
rwRwanda
knSaint Kitts And Nevis
lcSaint Lucia
vcSaint Vincent And The Grenadines
wsSamoa
smSan Marino
stSao Tome And Principe
saSaudi Arabia
snSenegal
rsSerbia
scSeychelles
slSierra Leone
sgSingapore
skSlovakia
siSlovenia
sbSolomon Islands
soSomalia
zaSouth Africa
gsSouth Georgia And South S.S.
ssSouth Sudan
esSpain
lkSri Lanka
shSt. Helena
pmSt. Pierre And Miquelon
sdSudan
srSuriname
sjSvalbard And Jan Mayen Islands
szSwaziland
seSweden
chSwitzerland
sySyrian Arab Republic
twTaiwan
tjTajikistan
tzTanzania
thThailand
tgTogo
tkTokelau
toTonga
ttTrinidad And Tobago
tnTunisia
trTurkey
tmTurkmenistan
tcTurks And Caicos Islands
tvTuvalu
umU.S. Minor Islands
ugUganda
uaUkraine
aeUnited Arab Emirates
gbUnited Kingdom
usUnited States
viUnited States Virgin Islands
uyUruguay
uzUzbekistan
vuVanuatu
veVenezuela
vnViet Nam
wfWallis And Futuna Islands
ehWestern Sahara
yeYemen
zmZambia
zwZimbabwe
Languages (meta_lang)
codeName
aeAvestan
azAzeri
enEnglish
arArabic
hyArmenian
afAfrikaans
beBelarusian
bnBengali
bgBulgarian
huHungarian
viVietnamese
htHaitian
elGreek
kaGeorgian
daDanish
zuZulu
heHebrew
idIndonesian
gaIrish
isIcelandic
esSpanish
itItalian
kkKazakh
caCatalan
kyKyrgyz
zhChinese
koKorean
loLao
laLatin
lvLatvian
ltLithuanian
msMalay
deGerman
nlDutch
noNorwegian
paPunjabi
faPersian
plPolish
ptPortuguese
roRomanian
ruRussian
saSanskrit
skSlovak
slSlovenian
tlTagalog
tgTajik
thThai
taTamil
ttTatar
teTelugu
trTurkish
tkTurkmen
uzUzbek
ukUkrainian
urUrdu
fiFinnish
frFrench
hiHindi
hrCroatian
ceCE
csCzech
cvCV
svSwedish
etEstonian
jaJapanese
Root genres (genre_id)
codeName
alternativeAlternative
animeAnime
arabicArabic
armenianArmenian
bluesBlues
brazilianBrazilian
children_s_musicChildren's Music
chineseChinese
christian_gospelChristian & Gospel
classicalClassical
comedyComedy
countryCountry
cubanCuban
danceDance
disneyDisney
easy_listeningEasy Listening
electronicElectronic
enkaEnka
fitness_workoutFitness & Workout
folkFolk
french_popFrench Pop
german_folkGerman Folk
german_popGerman Pop
hip_hop_rapHip Hop/Rap
holidayHoliday
indianIndian
inspirationalInspirational
instrumentalInstrumental
j_popJ-Pop
jazzJazz
karaokeKaraoke
kayokyokuKayokyoku
koreanKorean
latinLatin
marching_bandsMarching Bands
new_ageNew Age
popPop
r_b_soulR&B/Soul
reggaeReggae
rockRock
russianRussian
singer_songwriterSinger/Songwriter
soundtrackSoundtrack
spoken_wordSpoken Word
vocalVocal
worldWorld
Subgenres

Subgenres for every root genre are loaded from the live catalog (server-side). Pick a genre, then copy all subgenre codes at once.

Loading subgenres…
Subgenres · alternative — Alternative
codeName
adult_alternativeAdult Alternative
alternative_metalAlternative Metal
alternative_rockAlternative Rock
chinese_altChinese Alt
college_rockCollege Rock
egyptian_tarabEgyptian Tarab
emoEMO
emo_rapEmo rap
goth_rockGoth Rock
grungeGrunge
hardcore_punkHardcore punk
indie_egyptianIndie Egyptian
indie_levantIndie Levant
indie_maghrebIndie Maghreb
indie_popIndie Pop
indie_rockIndie Rock
iraqi_tarabIraqi Tarab
khaleeji_tarabKhaleeji Tarab
korean_indieKorean Indie
metalcoreMetalcore
new_waveNew Wave
pop_punkPop Punk
post_hardcorePost-hardcore
punkPunk
rap_metalRap 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.

POST
/api/v1/music-distributor/moderation/

Submit a full release (multipart). The response includes a status field for the submission.

Request body
FieldTypeRequiredDescription
release_namestringyesRelease / album title.
artist_namestringyesPrimary artist display name.
release_datestring (YYYY-MM-DD)yesWorldwide release date.
genre_idstring | integeryesRoot genre code (e.g. electronic) or legacy numeric id — see GET /catalog/reference-datagenres_root or the static tables below.
sub_genre_idstring | integernoSubgenre code under the resolved root genre (see subgenres_by_parent_code in reference-data / docs bundle) or legacy numeric id.
album_typestringnoDefault 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
labelstringnoLabel / imprint as shown on stores (P-line). ≤200 characters.
meta_langstringnoMetadata 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_titlestringnoAlbum subtitle / version.
album_annotationstringnoShort description / liner notes.
upcstringnoOptional; max 14 digits. Leave empty for auto-assignment.
copyrightstringnoOptional. Your rights share on the composition, percent 0–100 (default 100).
platformsstring (JSON array)noEach entry: platform code (e.g. spotify) or legacy numeric id. Omit or empty → server may select all.
countriesstring (JSON array)noEach entry: territory code (ISO us, ru, …) or legacy numeric id. Use [] for worldwide. See static countries table.
artist_rolesstring (JSON array)yesAlbum-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_metastring (JSON array)noOne 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_datedate stringnoOptional sales start.
preorder_datedate stringnoOptional pre-order date.
spotify_startsale_datedate stringnoOptional per-store date.
tiktok_startsale_datedate stringnoOptional.
yandex_startsale_datedate stringnoOptional.
oma_startsale_datedate stringnoOptional.
youtubered_upload_datedate stringnoOptional YouTube Music date.
itunes_cleared_for_streamstring boolnodefault true
Options: true · false
itunes_not_cleared_for_salestring boolnodefault false
is_single_maxistring boolnodefault false
is_mixtapestring boolnodefault false
is_audio_bookstring boolnodefault false
is_low_itunes_track_pricestring boolnodefault false
itunes_has_mfitstring boolnodefault false
tiktok_evstring boolnoTikTok early video flag. default false
callback_urlstring (URL)noOptional 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.
coverfileyesCover image file (see media rules).
audio_filesfile[]yesAt least one audio file; field name can be repeated (multipart).
videofilenoOptional video file.
bookletfilenoOptional PDF booklet.
cover_urlstring (URL)noAlternative to cover: public HTTP(S) URL to cover image. Max 50 MB. Use either cover or cover_url, not both.
audio_files_urlsstring (JSON array)noAlternative 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_urlstring (URL)noAlternative to video: public HTTP(S) URL to video file. Max 50 MB. Use either video or video_url, not both.
booklet_urlstring (URL)noAlternative to booklet: public HTTP(S) URL to PDF. Max 50 MB. Use either booklet or booklet_url, not both.
Example request (JSON)
{
  "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.
}
Example response (JSON)
{
  "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
}
Request examples

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"]'
Booleans in form fields are strings: true/false/1/yes/on. JSON-array fields (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).
GET
/api/v1/music-distributor/moderation/

List submissions: { code, msg, submissions: [...] }. Each row: status + human message (vendor-neutral).

Example request (JSON)
{}
Example response (JSON)
{
  "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"
    }
  ]
}
Request examples

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"
GET
/api/v1/music-distributor/catalog/reference-data

One 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.

Example request (JSON)
{}
Example response (JSON)
{
  "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": []
  }
}
Request examples

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"
GET
/api/v1/music-distributor/catalog/platforms

List 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.

Example request (JSON)
{}
Example response (JSON)
[{ "id": 1, "name": "Spotify", "platform_name": "Spotify" }]
GET
/api/v1/music-distributor/catalog/platform-groups

Platform groupings from cache (for UI filters). reference-data may also include live_supplement.platform_groups.

Example request (JSON)
{}
Example response (JSON)
[]
GET
/api/v1/music-distributor/releases/all

List 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).

Example request (JSON)
{
  "search": "summer",
  "offset": 0,
  "limit": 50
}
Example response (JSON)
[
    {
      "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"
    }
  ]
Request examples

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"
GET
/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.

Example request (JSON)
{}
Example response (JSON)
{
  "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" }
  ]
}
GET
/api/v1/music-distributor/releases/{release_ref}/status

Live 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).

Example request (JSON)
{}
Example response (JSON)
{
  "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.
POST
/api/v1/music-distributor/releases/{release_ref}/sync

Re-fetch status and metadata (same as GET …/status). {release_ref} accepts numeric id, rel_…, or mdr_….

Example request (JSON)
{}
Example response (JSON)
{
  "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"
}
GET
/api/v1/music-distributor/releases/{release_ref}/cover

Binary cover art. {release_ref}: numeric id, rel_…, or mdr_….

Example request (JSON)
{}
Example response (JSON)
{
  "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
}
GET
/api/v1/music-distributor/releases/persons/search?query=…

Search people in the distributor directory (for credits).

Example request (JSON)
{
  "query": "Artist"
}
Example response (JSON)
{
  "code": 200,
  "results": [
    { "id": 55, "content_name": "Artist Name", "match_score": 0.98 }
  ]
}
Request examples

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"
POST
/api/v1/music-distributor/releases/persons

Body: { content_name: string }. Create a person entry.

Example request (JSON)
{
  "content_name": "New Artist"
}
Example response (JSON)
{
  "code": 200,
  "person": { "id": 901, "content_name": "New Artist" }
}
Request examples

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"}'
GET
/api/v1/music-distributor/releases/{release_ref}/video-clips

Album video clips list.

Example request (JSON)
{}
Example response (JSON)
{
  "code": 200,
  "clips": [
    { "id": 1, "title": "Official video", "url": "https://cdn.example.com/clip1.mp4", "track_id": null }
  ]
}
GET
/api/v1/music-distributor/releases/{release_ref}/track-video-clips

Per-track video clips.

Example request (JSON)
{}
Example response (JSON)
{
  "code": 200,
  "clips": [
    { "id": 2, "track_id": 1, "title": "Vertical clip", "url": "https://cdn.example.com/t1_clip.mp4" }
  ]
}
GET
/api/v1/music-distributor/releases/{release_ref}/persons

Album person links.

Example request (JSON)
{}
Example response (JSON)
{
  "code": 200,
  "persons": [
    { "person_id": 55, "role": "artist", "order": 1, "name": "Stage Name" }
  ]
}
POST
/api/v1/music-distributor/releases/{release_ref}/persons

Add album person (body per backend).

Example request (JSON)
{
  "person_id": 55,
  "order": 1,
  "role": "artist"
}
Example response (JSON)
{
  "code": 200,
  "link": { "release_id": 123, "person_id": 55, "role": "artist", "order": 1 }
}
GET
/api/v1/music-distributor/releases/{release_ref}/track-persons

Track person links.

Example request (JSON)
{}
Example response (JSON)
{
  "code": 200,
  "track_persons": [
    { "track_id": 1, "person_id": 55, "role": "artist", "order": 1 }
  ]
}
POST
/api/v1/music-distributor/releases/{release_ref}/track-persons

Add track person.

Example request (JSON)
{
  "track_id": 1,
  "person_id": 55,
  "order": 1,
  "role": "featured_artist"
}
Example response (JSON)
{
  "code": 200,
  "link": { "track_id": 1, "person_id": 55, "role": "featured_artist", "order": 1 }
}
POST
/api/v1/music-distributor/releases/{release_ref}/sort-tracks

Reorder tracks (body per backend).

Example request (JSON)
{
  "track_ids": [3, 1, 2]
}
Example response (JSON)
{
  "code": 200,
  "msg": "order updated"
}
GET
/api/v1/music-distributor/releases/{release_ref}/platform-links

DSP storefront links. Returns sale_platforms as { platform_name, link } for all available platforms: Wink, MTS, Yandex Music, Spotify, VK Music, Zvuk.

Example request (JSON)
{}
Example response (JSON)
{
  "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" }
  ]
}
POST
/api/v1/music-distributor/releases/{release_ref}/revoke

Distributor 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.

Example request (JSON)
{}
Example response (JSON)
{
  "status": "revoked",
  "release_id": 128,
  "upstream_album_id": 95501
}
Alternate success body when not on distributor moderation: {"status":"deleted","release_id":128,"upstream_album_id":95501} (catalog row removed only). 400 when workflow is live.
POST
/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/.

Request body
FieldTypeRequiredDescription
release_idstringyesOpaque public_id of the release.
release_namestringnoFor display.
artist_namestringnoFor display.
upcstringnoOptional.
isrcstringnoOptional.
reasonstringnoTakedown reason.
Example request (JSON)
{
  "release_id": "rel_01abc",
  "release_name": "Summer EP",
  "artist_name": "Stage Name",
  "upc": "886447833821",
  "reason": "Artist requested takedown"
}
Example response (JSON)
{
  "code": 200,
  "id": 501,
  "status": "pending"
}
Request examples

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"}'
GET
/api/v1/music-distributor/delete-requests/

List all takedown requests you have submitted. Status: pending → completed → rejected.

Example request (JSON)
{}
Example response (JSON)
{
  "code": 200,
  "requests": [
    {
      "id": 501,
      "release_id": "rel_01abc",
      "status": "pending",
      "reason": "Artist requested takedown",
      "created_at": "2026-04-20T09:00:00Z"
    }
  ]
}
Request examples

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"
GET
/api/v1/music-distributor/panel/scope

Dashboard: artists + releases in your scope. Each release includes release_id (numeric catalog id), status / message (public workflow), and optional admin-only debug fields.

Example request (JSON)
{}
Example response (JSON)
{
  "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"
    }
  ]
}
Request examples

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"
GET
/api/v1/music-distributor/panel/activity-log

Aggregated activity. Query: artist, action, limit, offset.

Example request (JSON)
{
  "artist": "Stage Name",
  "action": "submit",
  "limit": 20,
  "offset": 0
}
Example response (JSON)
{
  "code": 200,
  "events": [
    {
      "id": 1001,
      "action": "submit",
      "entity_type": "release",
      "entity_id": "rel_01abc",
      "created_at": "2026-04-21T08:00:00Z"
    }
  ],
  "total": 42
}
Request examples

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"
GET
/api/v1/music-distributor/panel/reports/streaming.csv

CSV export of your releases (400 if none).

Example request (JSON)
{}
Example response (JSON)
{
  "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"
}
Request examples

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"
POST
/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.

Request body
FieldTypeRequiredDescription
moderation_request_idintegeryesId of the moderation submission this pitch is tied to (from your product / support workflow).
payload_jsonstring (JSON in form)yesrelease_description, artist_bio_achievements, pitch_platforms[]
artist_photofilenoOptional; max 15 MB; jpg/png/webp.
Example request (JSON)
{
  "_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>"
}
Example response (JSON)
{
  "code": 200,
  "id": 77,
  "status": "received"
}
Request examples

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"]}'
50 credits per request (402 if insufficient). pitch_platforms: yandex_music, vk_music, zvooq, amazon_music, spotify, apple_music — allowed until public live (including sent_to_stores / delivery phases).
GET
/api/v1/music-distributor/pitch/

List your pitch requests (all statuses: pending, in_progress, completed, rejected).

Example request (JSON)
{}
Example response (JSON)
{
  "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
    }
  ]
}
Request examples

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"
Integrators must read 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.
GET
/api/v1/music-distributor/payout/settings

Payout method + details.

Example request (JSON)
{}
Example response (JSON)
{
  "code": 200,
  "method": "paypal",
  "details": { "paypal_email": "[email protected]" }
}
Request examples

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"
PUT
/api/v1/music-distributor/payout/settings

Set payout. JSON: { method: paypal|bank_account|card_swift|card_ru, details?: { … } }.

Example request (JSON)
{
  "method": "paypal",
  "details": { "paypal_email": "[email protected]" }
}
Example response (JSON)
{
  "code": 200,
  "msg": "settings saved"
}
Request examples

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]"}}'
GET
/api/v1/music-distributor/payout/withdrawals

List withdrawals (query limit).

Example request (JSON)
{
  "limit": 50
}
Example response (JSON)
{
  "code": 200,
  "withdrawals": [
    {
      "id": 9001,
      "amount_cents": 5000,
      "currency": "USD",
      "status": "completed",
      "created_at": "2026-04-01T00:00:00Z"
    }
  ]
}
Request examples

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"
POST
/api/v1/music-distributor/payout/withdrawals/request

Request a withdrawal. JSON: { amount_cents, currency } — min 100 cents.

Example request (JSON)
{
  "amount_cents": 5000,
  "currency": "USD"
}
Example response (JSON)
{
  "code": 200,
  "withdrawal_id": 9002,
  "status": "pending"
}
Request examples

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"}'
POST
/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.

Request body
FieldTypeRequiredDescription
releasesstring[]yes1–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.presetstringnoReporting 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.tostring (YYYY-MM-DD)noRequired only when preset = custom. Inclusive date range.
include.platformsbooleannoPer-platform stream/paid breakdown (release + per track). Default: true.
include.countriesbooleannoPer-country breakdown (release + per track). Default: true.
include.tracksbooleannoPer-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.genderbooleannoOptional secondary demographic/technical breakdowns (yes/no). Default: false — turn on only what you need to keep responses small.
include.timeseriesbooleannoPer-day stream/paid series for each release. Default: false.
Example request (JSON)
// 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 }
}
Example response (JSON)
{
  "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"
    }
  ]
}
One call, many releases. Each 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}.
GET
/api/v1/music-distributor/analytics/summary/filters

Analytics filter metadata (catalog-scoped).

Example request (JSON)
{}
Example response (JSON)
{
  "code": 200,
  "date_ranges": ["last_7d", "last_28d", "last_90d"],
  "metrics": ["streams", "listeners"],
  "albums": [{ "catalog_album_id": "ca_1", "title": "Summer EP" }]
}
Request examples

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"
Analytics: one HTTP call = one report — there is no single endpoint that returns summary + every DSP together. For each slice (summary table, Spotify graph, Yandex graph, …) call the matching URL. Gard serves responses from its own Postgres database — see response header X-Gard-Analytics-Cached (true = snapshot, facts = per-album aggregation). Full contract: docs/music-distributor.md (Analytics).
POST
/api/v1/music-distributor/analytics/summary/table

Cross-store table (all DSPs combined in this upstream view). Minimal POST body; Gard adds date range and Cabinet custom_filters from your catalog.

Example request (JSON)
// 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"
}
Example response (JSON)
{
  "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": {}
}
Request examples

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"}'
Request: {"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.
POST
/api/v1/music-distributor/analytics/spotify/table

Spotify analytics table (JSON body). Same minimal POST contract as summary analytics.

Example request (JSON)
// Whole catalog:
{
  "filters": {}
}

// One release:
{
  "filters": { "release_public_ids": ["rel_ExampleId123"] }
}

// Custom date range:
{
  "filters": {},
  "from": "2026-04-01",
  "to": "2026-04-30"
}
Example response (JSON)
{
  "pages": 1,
  "page": 0,
  "columns": ["track", "isrc", "streams"],
  "data": [{ "track": "Track A", "isrc": "USXXX2400001", "streams": 80000 }],
  "order": {}
}
Request examples

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"]}}'
POST
/api/v1/music-distributor/analytics/applemusic/table

Apple Music analytics table.

Example request (JSON)
// Whole catalog:
{
  "filters": {}
}

// One release:
{
  "filters": { "release_public_ids": ["rel_ExampleId123"] }
}
Example response (JSON)
{
  "pages": 1,
  "page": 0,
  "columns": ["album", "plays"],
  "data": [{ "album": "Summer EP", "plays": 60000 }],
  "order": {}
}
Request examples

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"]}}'
GET
/api/v1/music-distributor/analytics/spotify/filters

Spotify analytics filter metadata (catalog-scoped). Same prerequisite as other analytics routes.

Example request (JSON)
{}
Example response (JSON)
{
  "filters": { "date_range": ["last_7d", "last_28d"] },
  "dimensions": ["track", "album"],
  "metrics": ["streams"]
}
Request examples

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"
Analytics: 400 if you have no synced releases with upstream album ids. Responses are narrowed to your catalog.
POST
/api/v1/music-distributor/analytics/spotify/graph

Spotify — daily time-series graph.

Example request (JSON)
// 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"] }
}
Example response (JSON)
{
  "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
    }
  ]
}
Request examples

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"}'
Graph-style responses expose lines (metric keys) and data (points; name is usually an ISO date). Keys vary by DSP.
POST
/api/v1/music-distributor/analytics/spotify/bar

Spotify — bar chart payload (proxied).

Example request (JSON)
// Whole catalog:
{
  "filters": {}
}

// One release:
{
  "filters": { "release_public_ids": ["rel_ExampleId123"] }
}
Example response (JSON)
{
  "bars": [{ "label": "US", "value": 40000 }]
}
Request examples

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"}'
Exact bar payload shape follows upstream Cabinet JSON for this route.
POST
/api/v1/music-distributor/analytics/summary/graph/main

Cross-store summary — main trend graph.

Example request (JSON)
// Whole catalog:
{
  "filters": {}
}

// One release + custom range:
{
  "filters": { "release_public_ids": ["rel_ExampleId123"] },
  "from": "2026-04-01",
  "to": "2026-04-30"
}
Example response (JSON)
{
  "lines": ["all_streams", "all_paidstreams"],
  "data": [{ "name": "2026-05-11", "all_streams": 12000, "all_paidstreams": 4100 }]
}
Request examples

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"}'
POST
/api/v1/music-distributor/analytics/summary/graph/total

Cross-store summary — totals graph.

Example request (JSON)
// Whole catalog:
{
  "filters": {}
}

// By artist:
{
  "filters": { "artist_names": ["Aurora Nightingale"] }
}
Example response (JSON)
{
  "lines": ["all_streams"],
  "data": [{ "name": "2026-05-11", "all_streams": 250000 }]
}
Request examples

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"}'
POST
/api/v1/music-distributor/analytics/summary/graph/country

Cross-store summary — breakdown by country.

Example request (JSON)
// Whole catalog:
{
  "filters": {}
}

// One release:
{
  "filters": { "release_public_ids": ["rel_ExampleId123"] }
}
Example response (JSON)
{
  "lines": ["all_streams"],
  "data": [{ "name": "US", "all_streams": 80000 }]
}
Request examples

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"}'
POST
/api/v1/music-distributor/analytics/summary/graph/os

Cross-store summary — breakdown by OS.

Example request (JSON)
// Whole catalog:
{
  "filters": {}
}

// One release:
{
  "filters": { "release_public_ids": ["rel_ExampleId123"] }
}
Example response (JSON)
{
  "lines": ["all_streams"],
  "data": [{ "name": "iOS", "all_streams": 50000 }]
}
Request examples

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"}'
POST
/api/v1/music-distributor/analytics/summary/graph/device_type

Cross-store summary — breakdown by device type.

Example request (JSON)
// Whole catalog:
{
  "filters": {}
}

// One release:
{
  "filters": { "release_public_ids": ["rel_ExampleId123"] }
}
Example response (JSON)
{
  "lines": ["all_streams"],
  "data": [{ "name": "mobile", "all_streams": 90000 }]
}
Request examples

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"}'
POST
/api/v1/music-distributor/analytics/summary/graph/age

Cross-store summary — age buckets (whole-catalog only, not per-release).

Example request (JSON)
// Whole catalog only (per-release not supported for age/gender):
{
  "filters": {}
}
Example response (JSON)
{
  "lines": ["all_streams"],
  "data": [{ "name": "18-24", "all_streams": 30000 }]
}
Request examples

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"}'
POST
/api/v1/music-distributor/analytics/summary/graph/gender

Cross-store summary — gender breakdown (whole-catalog only, not per-release).

Example request (JSON)
// Whole catalog only (per-release not supported for age/gender):
{
  "filters": {}
}
Example response (JSON)
{
  "lines": ["all_streams"],
  "data": [{ "name": "female", "all_streams": 70000 }]
}
Request examples

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"}'
POST
/api/v1/music-distributor/analytics/summary/stats

Cross-store summary — per-platform totals for the caller's catalog or a release/artist subset.

Example request (JSON)
{
  "filters": {
    "release_public_ids": ["rel_…"]
  },
  "from": "2026-04-20",
  "to":   "2026-05-15"
}
Example response (JSON)
{
  "data": [
    { "name": "yandex",   "streams": 128 },
    { "name": "umavk",    "streams": 436 },
    { "name": "spotify",  "streams": 0   }
  ],
  "lines": ["streams"]
}
Request examples

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"}'
Narrow by any combination: 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.
GET
/api/v1/music-distributor/analytics/applemusic/filters

Apple Music analytics filter metadata.

Example request (JSON)
{}
Example response (JSON)
{
  "filters": { "date_range": ["last_7d", "last_28d"] },
  "dimensions": ["album", "track"],
  "metrics": ["plays", "listeners"]
}
Request examples

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"
POST
/api/v1/music-distributor/analytics/applemusic/graph

Apple Music — graph series.

Example request (JSON)
// Whole catalog:
{
  "filters": {}
}

// One release:
{
  "filters": { "release_public_ids": ["rel_ExampleId123"] }
}
Example response (JSON)
{
  "lines": ["all_plays"],
  "data": [{ "name": "2026-05-11", "all_plays": 1200 }]
}
Request examples

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"}'
POST
/api/v1/music-distributor/analytics/applemusic/graph/total

Apple Music — totals graph.

Example request (JSON)
// Whole catalog:
{
  "filters": {}
}

// One release:
{
  "filters": { "release_public_ids": ["rel_ExampleId123"] }
}
Example response (JSON)
{
  "lines": ["all_plays"],
  "data": [{ "name": "2026-05-11", "all_plays": 60000 }]
}
Request examples

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"}'
POST
/api/v1/music-distributor/analytics/applemusic/bar

Apple Music — bar chart.

Example request (JSON)
// Whole catalog:
{
  "filters": {}
}

// One release:
{
  "filters": { "release_public_ids": ["rel_ExampleId123"] }
}
Example response (JSON)
{
  "bars": [{ "label": "Worldwide", "value": 60000 }]
}
Request examples

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"}'
GET
/api/v1/music-distributor/analytics/vkclips/filters

VK Clips analytics filter metadata.

Example request (JSON)
{}
Example response (JSON)
{
  "filters": { "date_range": ["last_7d", "last_28d"] },
  "metrics": ["views"]
}
Request examples

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"
POST
/api/v1/music-distributor/analytics/vkclips/table

VK Clips analytics table.

Example request (JSON)
// Whole catalog:
{
  "filters": {}
}

// One release:
{
  "filters": { "release_public_ids": ["rel_ExampleId123"] }
}
Example response (JSON)
{
  "pages": 1,
  "page": 0,
  "columns": ["clip", "views"],
  "data": [],
  "order": {}
}
Request examples

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"}'
POST
/api/v1/music-distributor/analytics/vkclips/graph

VK Clips — graph.

Example request (JSON)
// Whole catalog:
{
  "filters": {}
}

// One release:
{
  "filters": { "release_public_ids": ["rel_ExampleId123"] }
}
Example response (JSON)
{
  "lines": ["all_streams"],
  "data": []
}
Request examples

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"}'
POST
/api/v1/music-distributor/analytics/vkclips/graph/total

VK Clips — totals graph.

Example request (JSON)
// Whole catalog:
{
  "filters": {}
}

// One release:
{
  "filters": { "release_public_ids": ["rel_ExampleId123"] }
}
Example response (JSON)
{
  "totals": { "views": 15000 }
}
Request examples

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"}'
POST
/api/v1/music-distributor/analytics/yandex/table

Yandex Music — analytics table.

Example request (JSON)
// Whole catalog:
{
  "filters": {}
}

// One release + custom range:
{
  "filters": { "release_public_ids": ["rel_ExampleId123"] },
  "from": "2026-04-01",
  "to": "2026-04-30"
}
Example response (JSON)
{
  "pages": 1,
  "page": 0,
  "columns": ["track", "streams", "royalty_streams"],
  "data": [{ "track": "Track A", "streams": 800, "royalty_streams": 600 }],
  "order": {}
}
Request examples

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"}'
POST
/api/v1/music-distributor/analytics/yandex/graph

Yandex Music — daily graph.

Example request (JSON)
// Whole catalog:
{
  "filters": {}
}

// By artist:
{
  "filters": { "artist_names": ["Aurora Nightingale"] }
}
Example response (JSON)
{
  "lines": ["all_streams", "all_paidstreams"],
  "data": [{ "name": "2026-05-11", "all_streams": 120, "all_paidstreams": 90 }]
}
Request examples

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"}'
POST
/api/v1/music-distributor/analytics/umavk/table

UMA / VK music — analytics table.

Example request (JSON)
// Whole catalog:
{
  "filters": {}
}

// One release:
{
  "filters": { "release_public_ids": ["rel_ExampleId123"] }
}
Example response (JSON)
{
  "pages": 1,
  "page": 0,
  "columns": ["track", "streams"],
  "data": [],
  "order": {}
}
Request examples

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"}'
POST
/api/v1/music-distributor/analytics/umavk/graph

UMA / VK music — daily graph.

Example request (JSON)
// Whole catalog:
{
  "filters": {}
}

// One release:
{
  "filters": { "release_public_ids": ["rel_ExampleId123"] }
}
Example response (JSON)
{
  "lines": ["all_streams"],
  "data": [{ "name": "2026-05-11", "all_streams": 50 }]
}
Request examples

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"}'
POST
/api/v1/music-distributor/analytics/mts/table

MTS Music — analytics table.

Example request (JSON)
// Whole catalog:
{
  "filters": {}
}

// One release:
{
  "filters": { "release_public_ids": ["rel_ExampleId123"] }
}
Example response (JSON)
{
  "pages": 1,
  "page": 0,
  "columns": ["track", "streams"],
  "data": [],
  "order": {}
}
Request examples

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"}'
POST
/api/v1/music-distributor/analytics/mts/graph

MTS Music — daily graph.

Example request (JSON)
// Whole catalog:
{
  "filters": {}
}

// One release:
{
  "filters": { "release_public_ids": ["rel_ExampleId123"] }
}
Example response (JSON)
{
  "lines": ["all_streams"],
  "data": [{ "name": "2026-05-11", "all_streams": 30 }]
}
Request examples

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"}'
POST
/api/v1/music-distributor/analytics/zvooq/table

Zvooq — analytics table.

Example request (JSON)
// Whole catalog:
{
  "filters": {}
}

// One release:
{
  "filters": { "release_public_ids": ["rel_ExampleId123"] }
}
Example response (JSON)
{
  "pages": 1,
  "page": 0,
  "columns": ["track", "streams"],
  "data": [],
  "order": {}
}
Request examples

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"}'
POST
/api/v1/music-distributor/analytics/zvooq/graph

Zvooq — daily graph.

Example request (JSON)
// Whole catalog:
{
  "filters": {}
}

// One release:
{
  "filters": { "release_public_ids": ["rel_ExampleId123"] }
}
Example response (JSON)
{
  "lines": ["all_streams"],
  "data": [{ "name": "2026-05-11", "all_streams": 20 }]
}
Request examples

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": "…"
}