DOCUMENTATION API

API REST publique. Authentification par clé, documentée avec OpenAPI.

Consulte ton catalogue OGRECORDS™ et gère tes Smartlinks et tes releases en brouillon de façon programmatique — via une API REST simple. Authentifie-toi avec une clé API à portée depuis ton tableau de bord. Accès anticipé sur demande.

Référence APIGérer les clés APIDemander l'accès anticipé

Aperçu : API REST, clés à portée, limites de taux, OpenAPI

Lire + écrire via REST

Consultez les releases, les tracks, les Smartlinks et les statistiques — et créez ou modifiez vos Smartlinks et vos releases en brouillon — via HTTPS simple. Réponses JSON, pagination avec limit/offset, schémas prévisibles. La distribution et le dépôt restent en dehors de l'API.

Clés API à portée

Authentifie-toi avec une clé ogr_pk_ en tant que jeton Bearer ou dans l’en-tête X-API-Key. Chaque clé a des portées explicites — read:releases, read:smartlinks, read:stats, write:smartlinks, write:releases — et peut être rotée ou révoquée à tout moment depuis le tableau de bord.

Limites de taux + en-têtes

Chaque réponse contient les en-têtes X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset. Au-delà du quota, retourne 429 avec Retry-After. Les clés gratuites offrent 1 000 requêtes/jour, les clés Business 100 000.

OpenAPI 3.0 auto-hébergé

La spécification entièrement lisible par machine est disponible sous /api/v1/public/openapi.json et s’affiche comme référence interactive sur cette page — aucun hébergement tiers pour la documentation, aucun appel externe.

APERÇU DES ENDPOINTS

Les endpoints pour le lancement.

Chaque endpoint est authentifié avec une clé API à portée et est accessible depuis https://api.og-records.com. Les endpoints de lecture, ainsi que les écritures avec portée propriétaire pour les Smartlinks et les releases en brouillon — la distribution et le soumission ne sont pas exposés.

Sorties

  • GET/api/v1/public/releasesListe tes releases. Pagination avec limit et offset.
  • GET/api/v1/public/releases/{id}Un seul release par ID.
  • POST/api/v1/public/releasesCréer un release en brouillon (write:releases). KYC + onboarding requis.
  • PATCH/api/v1/public/releases/{id}Mettre à jour les métadonnées du brouillon (write:releases). Uniquement pour les brouillons pré-soumission.
  • DELETE/api/v1/public/releases/{id}Supprimer un release en brouillon (write:releases).

Titres

  • GET/api/v1/public/tracks?release_id={id}Les tracks d'un release dont vous êtes propriétaire.
  • GET/api/v1/public/tracks/{id}Un track spécifique par son ID.

Smartlinks

  • GET/api/v1/public/smartlinksListe tes Smartlinks.
  • POST/api/v1/public/smartlinksCréer un Smartlink pour ton propre release (write:smartlinks).
  • PATCH/api/v1/public/smartlinks/{id}Mettre à jour un de tes Smartlinks (write:smartlinks).
  • DELETE/api/v1/public/smartlinks/{id}Désactiver un Smartlink (write:smartlinks).

Stats & Spécifications

  • GET/api/v1/public/stats/release/{id}Streams, auditeurs et saves avec détail par DSP et pays. range = 7d, 14d, 30d, 90d, 1y ou ytd.
  • GET/api/v1/public/openapi.jsonLe document OpenAPI-3.0. Public et cacheable — aucun key nécessaire.

Artistes & Revenus

  • GET/api/v1/public/artistsListe tes artistes du roster (read:artists).
  • GET/api/v1/public/earnings/balanceSnapshot de ton solde USD dans ton portefeuille (read:earnings).
WEBHOOKS

Sois notifié quand un release change de statut.

Enregistre un endpoint HTTPS et nous t'enverrons un événement JSON signé par POST dès qu’un de tes releases est livré, rejeté ou retiré. Tu gères tes endpoints dans le tableau de bord — chacun a son propre secret de signature, affiché une seule fois.

Événements au lancement

  • release.delivered — le release a été livré aux magasins.
  • release.rejected — un magasin ou une étape de contrôle qualité a rejeté le release.
  • release.takedown — le release a été retiré.
  • release.live — le release est maintenant en ligne sur les plateformes.

Chaque livraison contient ces en-têtes

  • X-Webhook-Signature — HMAC-SHA256 en minuscules hexadécimales du corps brut de la requête, avec ton Signing-Secret comme clé.
  • X-Webhook-Timestamp — horodatage au format ISO-8601, identique à created_at dans le corps.
  • X-Webhook-Event — le nom de l'événement, par exemple release.delivered.
  • X-Webhook-Id — une identifiant unique pour cette livraison.

Le payload est un corps JSON contenant id, event, created_at et un objet data avec release_id. Pour vérifier, calcule à nouveau HMAC-SHA256 sur le corps brut exact avec ton Signing-Secret, compare-le de manière sécurisée avec X-Webhook-Signature, puis vérifie que X-Webhook-Timestamp est dans les cinq dernières minutes pour rejeter les répétitions.

Les livraisons échouées sont réessayées avec un backoff exponentiel. Après 15 échecs consécutifs, le point d'entrée est désactivé automatiquement ; tu dois le réenregistrer pour continuer.

Gérer les webhooks dans ton tableau de bord.

AUTHENTIFICATION

Clés API avec scopes.

Crée une clé dans ton tableau de bord et envoie-la comme en-tête Authorization: Bearer ogr_pk_… ou dans l'en-tête X-API-Key. Chaque clé est scannée — read:releases, read:smartlinks, read:stats, write:smartlinks, write:releases — afin qu'une intégration n'obtienne que ce dont elle a besoin. Les clés sont rotatives et révocables à tout moment. L'accès en écriture est limité au propriétaire et ne déclenche jamais de distribution ; OAuth n'est pas inclus dans ce lancement.

LIMITES DE TAUX

Ce que ton clé peut faire.

Gratuit
1 000 requêtes / jour

Standard pour chaque nouvelle clé. Convient aux tableaux de bord, synchronisations cron et prototypes.

Entreprise
100 000 requêtes / jour

Contingent journalier plus élevé pour les intégrations en production. Sur demande.

Chaque réponse contient X-RateLimit-Limit, X-RateLimit-Remaining et X-RateLimit-Reset. Si le quota journalier est épuisé, une réponse 429 avec l'en-tête Retry-After est renvoyée — les secondes restantes jusqu'au réinitialisation de la fenêtre.

ACCÈS PRÉCOCE

Construis sur ton catalogue.

L'API publique est en accès anticipé. Écris-nous ce que tu veux construire, et nous activerons des clés API pour ton compte.

Demander l'accès anticipéLire la référence