Ir para o conteúdo
SPREVA

O SPREVA abre em breve.

Entre na lista de espera e vamos mandar um único email para você, quando sua conta estiver pronta.

Nada de newsletter. Só um email quando o SPREVA abrir.

Referência

API REST

Crie, agende e publique publicações, envie mídia e consulte resultados pelo seu próprio código. A API segue as mesmas regras e a mesma validação do próprio SPREVA.

Sua primeira requisição

  1. 1

    Crie uma chave de API no SPREVA em Desenvolvimento, depois Chaves de API. Uma chave Só leitura basta para este exemplo; para publicar, é preciso uma chave com acesso Publicação.

  2. 2

    Liste suas contas sociais:

    Terminal
    curl https://dev-app.spreva.ai/api/v1/social-accounts \
  -H "Authorization: Bearer spreva_sk_..."
  3. 3

    Leia a resposta. Os resultados vêm dentro de data, e o id de uma conta é o que você passa como connectionId ao criar uma publicação para ela. O exemplo está resumido: o objeto real tem mais campos.

    JSON
    {
  "data": [
    {
      "id": "e81b3f52-0000-4000-8000-000000000005",
      "provider": "instagram",
      "displayName": "Acme Studio",
      "username": "acme",
      "status": "ACTIVE",
      "needsReconnect": false
    }
  ]
}

O básico

Todos os endpoints ficam neste endereço. Envie JSON, com a chave como Authorization: Bearer seguido da chave.

URL
https://dev-app.spreva.ai/api/v1
  • Uma chave pertence a um espaço de trabalho e só enxerga esse espaço de trabalho.
  • Limite: 120 requisições por minuto para cada pessoa em um espaço de trabalho, divididas entre todas as chaves que ela criou. Acima disso, a resposta é um 429 cuja mensagem diz quantos segundos esperar.
  • Os erros vêm no idioma do cabeçalho Accept-Language da requisição; o code nunca muda.
  • De um navegador com login no SPREVA, envie x-workspace-id com o id do espaço de trabalho em vez de uma chave.

Chaves e permissões

Uma chave age em nome da pessoa que a criou e nunca pode fazer mais do que a função dessa pessoa permite. Proprietários e administradores criam chaves, em um plano que inclua acesso à API, e a chave completa aparece só uma vez. Cada chave tem as permissões que recebeu:

posts:read
Ver publicações, o status delas, os resultados e as filas
media:read
Ver a biblioteca de mídia
accounts:read
Ver as contas sociais conectadas
analytics:read
Ver as análises
posts:write
Criar, editar, agendar, publicar e excluir publicações, e gerenciar filas
media:write
Enviar, renomear e excluir mídia
webhooks:write
Ver e adicionar endpoints de webhook
ai:write
Usar a IA. Legendas e hashtags também precisam de posts:write; texto alternativo e imagens também precisam de media:write

Só leitura dá as quatro permissões de leitura. Publicação acrescenta posts:write, media:write e ai:write, o suficiente para uma automação ou um agente de IA. Um 403 quer dizer que falta a permissão à chave, ou que a função de quem a criou não permite mais.

Erros

Todo erro tem o mesmo formato. Decida pelo code e mostre a message.

JSON
{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key needs the posts:write scope for posts:create"
  }
}
400
INVALID_REQUEST · INVALID_JSON · WORKSPACE_REQUIRED

O corpo ou a query não batem com o endpoint. details lista cada campo que está errado. Uma chamada do navegador sem x-workspace-id recebe WORKSPACE_REQUIRED.

401
UNAUTHENTICATED

A chave está faltando, escrita errado, revogada ou expirada. Mande “Authorization: Bearer <key>”.

402
ENTITLEMENT_EXCEEDED · AI_LIMIT_REACHED

O espaço de trabalho não tem nenhum plano ativo, ficou sem créditos de IA ou o plano não inclui isto. Um proprietário pode escolher um plano ou comprar créditos em Configurações, Cobrança.

403
FORBIDDEN

A chave não tem permissão para esta requisição, ou sua função não permite. Crie uma chave com mais acesso.

404
NOT_FOUND

Não existe esse objeto neste espaço de trabalho. Uma chave só enxerga o espaço de trabalho em que foi criada.

409
CONCURRENT_MODIFICATION · INVALID_STATE_TRANSITION · CONFLICT · AI_NOT_CONFIGURED

A publicação mudou depois que você leu, está em um estado que não permite isso (publicar algo já publicado), um arquivo que você está excluindo ainda é usado em uma publicação, ou a IA não está configurada nesta instalação. Busque de novo e tente outra vez.

422
VALIDATION_FAILED · PROVIDER_VALIDATION_FAILED · AI_REFUSED

O conteúdo não serve para a conta para onde vai, ou uma requisição à IA foi recusada. GET /providers lista as regras de cada rede.

429
RATE_LIMITED · AI_BUSY

Mais de 120 requisições em um minuto feitas por você neste espaço de trabalho, ou requisições demais à IA de uma vez. Para RATE_LIMITED, a mensagem diz quantos segundos esperar; para AI_BUSY, espere um pouco.

500
INTERNAL

Algo falhou ao tratar a requisição, no SPREVA ou em uma rede social. Tente de novo em instantes.

503
AI_UNAVAILABLE

O provedor de IA está indisponível agora. Tente de novo em instantes.

Endpoints

Os caminhos são relativos ao URL base. O documento OpenAPI descreve cada corpo e parâmetro, e você pode gerar um cliente a partir dele:

URL
https://dev-app.spreva.ai/api/openapi.json

Contas sociais e redes

  • get /social-accountsAs contas sociais conectadas.
  • get /providersAs regras de cada rede: formatos, posicionamentos e limites.

Publicações

  • get /postsPublicações, filtradas por status, datas, conta, rede ou campanha.
  • post /postsCriar um rascunho para uma ou mais contas.
  • get /posts/{id}Uma publicação com suas contas, validação e mídia.
  • patch /posts/{id}Alterar uma publicação. Envie a version que você leu; se ela mudou nesse meio-tempo, a resposta é 409.
  • delete /posts/{id}Excluir uma publicação.
  • post /posts/{id}/publishPublicar agora. A resposta é 202: acompanhe a publicação, ou um webhook, para saber o resultado.
  • post /posts/{id}/scheduleAgendar para um horário, com um fuso horário.
  • post /posts/{id}/queueColocar no próximo horário livre de uma fila.
  • post /posts/{id}/retryTentar de novo uma conta que falhou.

Mídia

  • get /mediaA biblioteca, com busca e filtros.
  • post /media/uploadsComeçar um envio: a resposta diz para onde mandar o arquivo.
  • post /media/uploads/{id}/completeTerminar um envio. O arquivo é então verificado e processado.
  • get /media/{id}Um arquivo, com seu status e o que se sabe sobre ele.
  • delete /media/{id}Excluir um arquivo. Um arquivo ainda usado em uma publicação responde 409.
  • put /media/{id}/alt-textSalvar ou limpar o texto alternativo de um arquivo.
  • post /media/{id}/alt-text/suggestionSugerir texto alternativo com IA, sem salvar.

Estatísticas

  • get /analyticsResultados de um período.
  • get /analytics/exportOs mesmos resultados em um arquivo CSV.

Filas

  • get /queuesAs filas de publicação.
  • post /queuesCriar uma fila com seus horários semanais.
  • patch /queues/{id}Alterar uma fila.
  • delete /queues/{id}Excluir uma fila.

Webhooks

  • get /webhooksOs endpoints de webhook.
  • post /webhooksAdicionar um endpoint. A resposta traz o segredo, só desta vez.

IA

  • get /aiSe a IA está disponível, os créditos que restam e quanto custa cada ação.
  • post /ai/captionsSugerir novas versões de uma legenda, traduções ou hashtags, sem salvar.
  • post /ai/imagesGerar uma imagem. Consulte GET /media/{id} até ela ficar pronta.