DOCUMENTAÇÃO DA API

API REST pública. Autenticada por chave, documentada com OpenAPI.

Leia seu catálogo OGRECORDS™ e gerencie Smartlinks e Releases em rascunho de forma programática — por meio de uma API REST simples. Autentique-se com uma chave de API com escopo do seu painel. Acesso antecipado mediante solicitação.

Referência da APIGerenciar chaves de APISolicitar acesso antecipado

Visão geral: API REST, chaves com escopo, limites de taxa, OpenAPI

Leitura + escrita REST

Veja Releases, Tracks, Smartlinks e estatísticas — e crie ou edite seus Smartlinks e Releases em andamento — por meio de HTTPS simples. Respostas JSON, paginação com limit/offset e esquemas previsíveis. A distribuição e o envio permanecem fora da API.

Chaves de API com escopo

Autentique-se com uma chave ogr_pk_ como token Bearer ou no cabeçalho X-API-Key. Cada chave possui escopos explícitos — read:releases, read:smartlinks, read:stats, write:smartlinks, write:releases — e pode ser rotacionada ou revogada a qualquer momento no painel.

Limites de taxa + cabeçalhos

Toda resposta inclui os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Acima do limite, retorna 429 com Retry-After. Chaves gratuitas têm 1.000 requisições/dia; chaves business, 100.000.

OpenAPI 3.0 hospedado por você

A especificação completa e legível por máquina está em /api/v1/public/openapi.json e é renderizada como referência interativa nesta página — sem hospedagem terceirizada de documentação, sem chamadas externas.

VISÃO GERAL DOS ENDPOINTS

Os endpoints para o lançamento.

Cada endpoint é autenticado com uma chave de API com escopo e é fornecido por https://api.og-records.com. Endpoints de leitura mais escritas com escopo de proprietário para Smartlinks e Releases em rascunho — distribuição e submissão não estão expostos.

Lançamentos

  • GET/api/v1/public/releasesListe seus Releases. Paginação com limit e offset.
  • GET/api/v1/public/releases/{id}Um único Release por ID.
  • POST/api/v1/public/releasesCriar um Release em rascunho (write:releases). KYC + onboarding necessários.
  • PATCH/api/v1/public/releases/{id}Atualizar metadados do rascunho (write:releases). Apenas rascunhos pré-submissão.
  • DELETE/api/v1/public/releases/{id}Excluir um Release em rascunho (write:releases).

Faixas

  • GET/api/v1/public/tracks?release_id={id}Tracks de um Release que é seu.
  • GET/api/v1/public/tracks/{id}Um único track por ID.

Smartlinks

  • GET/api/v1/public/smartlinksListe seus Smartlinks.
  • POST/api/v1/public/smartlinksCriar um Smartlink para um lançamento seu (write:smartlinks).
  • PATCH/api/v1/public/smartlinks/{id}Atualizar um dos seus Smartlinks (write:smartlinks).
  • DELETE/api/v1/public/smartlinks/{id}Desativar um Smartlink (write:smartlinks).

Estatísticas & Especs

  • GET/api/v1/public/stats/release/{id}Streams, ouvintes e salvamentos com detalhamento por DSP e país. range = 7d, 14d, 30d, 90d, 1y ou ytd.
  • GET/api/v1/public/openapi.jsonO documento OpenAPI-3.0. Público e cacheável — não precisa de chave.

Artistas & Receitas

  • GET/api/v1/public/artistsLista seus artistas da roster (read:artists).
  • GET/api/v1/public/earnings/balanceSeu saldo do wallet em USD (read:earnings).
WEBHOOKS

Seja notificado quando um lançamento mudar de status.

Registre um endpoint HTTPS e enviaremos um evento JSON assinado por POST assim que um dos seus lançamentos for entregue, rejeitado ou retirado. Você gerencia seus endpoints no painel — cada um tem seu próprio Signing-Secret, exibido apenas uma vez.

Eventos no Lançamento

  • release.delivered — o lançamento foi entregue às lojas.
  • release.rejected — uma loja ou etapa de QC rejeitou o lançamento.
  • release.takedown — o lançamento foi removido.
  • release.live — o lançamento agora está ao vivo nas lojas.

Cada entrega inclui esses cabeçalhos

  • X-Webhook-Signature — HMAC-SHA256 em minúsculas e hexadecimais do corpo da requisição bruto, usando seu Signing-Secret como chave.
  • X-Webhook-Timestamp — horário de envio no formato ISO-8601, igual ao created_at no corpo.
  • X-Webhook-Event — o nome do evento, por exemplo: release.delivered.
  • X-Webhook-Id — uma ID única para esta entrega.

O payload é um corpo JSON com id, event, created_at e um objeto data que contém release_id. Para verificar, calcule novamente o HMAC-SHA256 sobre o corpo bruto exato usando seu Signing-Secret e compare de forma segura no tempo com X-Webhook-Signature — depois verifique se X-Webhook-Timestamp está dentro de aproximadamente cinco minutos para rejeitar repetições.

Entregas falhadas são repetidas com backoff exponencial. Após 15 falhas consecutivas, o endpoint é desativado automaticamente e você precisa recriá-lo para continuar.

Gerenciar webhooks no seu painel.

AUTENTICAÇÃO

API-Keys com scopes.

Crie um key no seu painel e envie como cabeçalho Authorization: Bearer ogr_pk_… ou no cabeçalho X-API-Key. Cada key tem escopo — read:releases, read:smartlinks, read:stats, write:smartlinks, write:releases — para que uma integração receba apenas o que precisa. Keys podem ser rotacionados e revogados a qualquer momento. O acesso de escrita é scoped ao owner e nunca dispara distribuição; OAuth não faz parte deste lançamento.

LIMITES DE TAXA

O que seu key pode fazer.

Gratuito
1.000 req/dia

Padrão para cada novo key. Adequado para painéis, sincronizações cron e prototipagem.

Negócios
100.000 req/dia

Contingente diário maior para integrações em produção. Sob solicitação.

Toda resposta inclui X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Quando o limite diário for esgotado, será retornado 429 com o cabeçalho Retry-After — os segundos até o reinício da janela.

ACESSO ANTECIPADO

Construa com base no seu catálogo.

A API pública está em Acesso Antecipado. Nos diga o que você quer construir e ativaremos keys para sua conta.

Solicitar acesso antecipadoLer referência