Referência

API REST

Crie, agende e publique publicações, carregue multimédia e consulte resultados a partir do seu próprio código. A API segue as mesmas regras e a mesma validação que o próprio SPREVA.

O seu primeiro pedido

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

Liste as suas contas sociais:

Terminal

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

Leia a resposta. Os resultados vêm dentro de data, e o id de uma conta é o que 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
    }
  ]
}

Noções básicas

Todos os endpoints estão 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 uma área de trabalho e só vê essa área de trabalho.
Limite: 120 pedidos por minuto para cada pessoa numa área de trabalho, partilhados por todas as chaves que criou. Acima disso, a resposta é um 429 cuja mensagem indica quantos segundos esperar.
Os erros vêm na língua do cabeçalho Accept-Language do pedido; o code nunca muda.
A partir de um browser com sessão iniciada no SPREVA, envie x-workspace-id com o id da área 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. As chaves são criadas por proprietários e administradores, num plano que inclua acesso à API, e a chave completa só é mostrada uma vez. Cada chave tem as permissões que lhe foram dadas:

posts:read: Ver publicações, o estado delas, os resultados e as filas
media:read: Ver a biblioteca de multimédia
accounts:read: Ver as contas sociais ligadas
analytics:read: Ver as estatísticas
posts:write: Criar, editar, agendar, publicar e eliminar publicações, e gerir filas
media:write: Carregar, mudar o nome e eliminar multimédia
webhooks:write: Ver e adicionar endpoints de webhook
ai:write: Utilizar a IA. As legendas e as hashtags também precisam de posts:write; o texto alternativo e as imagens também precisam de media:write

Apenas 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 significa que falta a permissão à chave, ou que a função de quem a criou já não o permite.

Erros

Todos os erros têm a mesma forma. 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 consulta não correspondem ao endpoint. details lista cada campo que está errado. Uma chamada do browser sem x-workspace-id recebe WORKSPACE_REQUIRED.
401: UNAUTHENTICATED
A chave falta, está mal escrita, foi revogada ou expirou. Envie “Authorization: Bearer <key>”.
402: ENTITLEMENT_EXCEEDED · AI_LIMIT_REACHED
A área 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 Definições, Faturação.
403: FORBIDDEN
A chave não tem permissão para este pedido, ou a sua função não o permite. Crie uma chave com mais acesso.
404: NOT_FOUND
Não existe esse objeto nesta área de trabalho. Uma chave só vê a área de trabalho onde foi criada.
409: CONCURRENT_MODIFICATION · INVALID_STATE_TRANSITION · CONFLICT · AI_NOT_CONFIGURED
A publicação mudou desde que a leu, está num estado que não permite isto (publicar algo já publicado), um ficheiro que está a eliminar ainda é usado numa publicação, ou a IA não está configurada nesta instalação. Volte a obtê-la e tente de novo.
422: VALIDATION_FAILED · PROVIDER_VALIDATION_FAILED · AI_REFUSED
O conteúdo não serve para a conta para onde vai, ou um pedido à IA foi recusado. GET /providers lista as regras de cada rede.
429: RATE_LIMITED · AI_BUSY
Mais de 120 pedidos num minuto feitos por si nesta área de trabalho, ou demasiados pedidos à IA de uma vez. Para RATE_LIMITED, a mensagem diz quantos segundos esperar; para AI_BUSY, espere um momento.
500: INTERNAL
Algo falhou ao tratar o pedido, no SPREVA ou numa rede social. Tente novamente dentro de momentos.
503: AI_UNAVAILABLE
O fornecedor de IA não está disponível neste momento. Tente novamente dentro de momentos.

Endpoints

Os caminhos são relativos ao URL base. O documento OpenAPI descreve cada corpo e parâmetro, e 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 ligadas.
get /providersAs regras de cada rede: formatos, posicionamentos e limites.

Publicações

get /postsPublicações, filtradas por estado, datas, conta, rede ou campanha.
post /postsCriar um rascunho para uma ou mais contas.
get /posts/{id}Uma publicação com as suas contas, validação e multimédia.
patch /posts/{id}Alterar uma publicação. Envie a version que leu; se mudou entretanto, a resposta é 409.
delete /posts/{id}Eliminar 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 uma hora, com um fuso horário.
post /posts/{id}/queuePôr no próximo espaço livre de uma fila.
post /posts/{id}/retryTentar de novo uma conta que falhou.

Multimédia

get /mediaA biblioteca, com pesquisa e filtros.
post /media/uploadsComeçar um carregamento: a resposta indica para onde enviar o ficheiro.
post /media/uploads/{id}/completeTerminar um carregamento. O ficheiro é depois verificado e processado.
get /media/{id}Um ficheiro, com o seu estado e o que se sabe sobre ele.
delete /media/{id}Eliminar um ficheiro. Um ficheiro ainda usado numa publicação responde 409.
put /media/{id}/alt-textGuardar ou limpar o texto alternativo de um ficheiro.
post /media/{id}/alt-text/suggestionSugerir texto alternativo com IA, sem o guardar.

Estatísticas

get /analyticsResultados de um período.
get /analytics/exportOs mesmos resultados num ficheiro CSV.

Filas

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

Webhooks

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

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 as guardar.
post /ai/imagesGerar uma imagem. Consulte GET /media/{id} até estar pronta.