Como usar a API pública do Postoria

A API pública do Postoria permite conectar ferramentas externas, scripts e sistemas internos ao Postoria.

Você pode usá-la para conectar e reconectar contas de redes sociais, listar seus espaços de trabalho e contas conectadas, enviar mídia, criar e gerenciar posts e consultar análises atuais ou agregadas dos posts.

A API pública está disponível nos planos Pro e Agency.

Antes de começar

Veja os principais pontos que você precisa saber antes de usar a API:

Você precisa de um plano Pro ou Agency ativo.
Cada conta do Postoria pode ter apenas uma chave de API ativa.
As chaves de API pertencem à conta, e não ao espaço de trabalho.
Os endpoints específicos de um espaço de trabalho exigem um workspace_id na URL.
A API usa autenticação por token Bearer.
A API tem um limite de 300 requisições a cada 5 minutos por conta.
O processamento de mídia é assíncrono.
As respostas da API usam campos JSON em snake_case.
A API v1 usa o prefixo de caminho /v1.

URL base

Use esta URL base:

https://api.postoria.io/v1

A documentação da API está disponível aqui: https://api.postoria.io/v1/docs/.

O documento OpenAPI está disponível aqui: https://api.postoria.io/v1/openapi.json.

Crie uma chave de API

Abra o Postoria.
Vá para Configurações.
Encontre a seção API pública, servidor MCP e integração com n8n.
Clique em Criar chave de API.
Copie a chave e guarde-a com segurança.

O Postoria mostra a chave de API completa apenas uma vez. Depois de fechar a janela, você verá somente o prefixo da chave.

Se perder a chave, revogue-a e crie uma nova.

Autentique as requisições

Envie a chave de API no cabeçalho Authorization:

Authorization: Bearer pst_live_your_api_key

Exemplo:

curl https://api.postoria.io/v1/workspaces \
  -H "Authorization: Bearer pst_live_your_api_key"

Se a chave estiver ausente, for inválida ou tiver sido revogada, o Postoria retornará 401 invalid_api_key.

Formato das respostas

As respostas de um único recurso retornam o objeto diretamente.

As respostas de listas usam este formato:

{
  "data": [],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "next": null
  }
}

Quando um endpoint de lista aceita paginação, has_more informa se há outra página disponível. Use next para solicitar a próxima página diretamente ou envie o next_cursor retornado como parâmetro de consulta cursor.

As respostas de erro usam este formato:

{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "param": null,
    "details": null,
    "request_id": "req_abc123"
  }
}

Limite de requisições

A API pública permite:

300 requests per 5 minutes per account

Se você exceder o limite, o Postoria retornará 429 rate_limit_exceeded com cabeçalhos para uma nova tentativa.

Exemplo:

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1770000000

Endpoints

A API pública v1 inclui estes endpoints:

GET    /v1/workspaces

GET    /v1/social-account-connection-options
POST   /v1/workspaces/{workspace_id}/social-account-connections
GET    /v1/workspaces/{workspace_id}/social-account-connections/{state}
POST   /v1/workspaces/{workspace_id}/social-account-connections/{state}/accounts
POST   /v1/workspaces/{workspace_id}/social-account-connections/{state}/reconnect

GET    /v1/workspaces/{workspace_id}/social-accounts
PATCH  /v1/workspaces/{workspace_id}/social-accounts/{social_account_id}
DELETE /v1/workspaces/{workspace_id}/social-accounts/{social_account_id}
GET    /v1/workspaces/{workspace_id}/queues

POST   /v1/workspaces/{workspace_id}/media/uploads
POST   /v1/workspaces/{workspace_id}/media/{media_id}/complete
POST   /v1/workspaces/{workspace_id}/media/imports
GET    /v1/workspaces/{workspace_id}/media/{media_id}

POST   /v1/workspaces/{workspace_id}/posts
GET    /v1/workspaces/{workspace_id}/posts
GET    /v1/workspaces/{workspace_id}/posts/{post_id}
DELETE /v1/workspaces/{workspace_id}/posts/{post_id}

GET    /v1/workspaces/{workspace_id}/analytics/posts
GET    /v1/workspaces/{workspace_id}/analytics/post-performance/summary

Liste os espaços de trabalho

Use este endpoint para obter os espaços de trabalho disponíveis para sua conta:

GET /v1/workspaces

Exemplo de resposta:

{
  "data": [
    {
      "id": 1,
      "name": "My Workspace",
      "timezone": "America/New_York"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "next": null
  }
}

Use o id retornado como workspace_id nos endpoints específicos de um espaço de trabalho.

Conecte ou reconecte contas de redes sociais

A API pública usa um fluxo OAuth interativo para conectar novas contas de redes sociais ou renovar a autorização das existentes. Seu aplicativo inicia uma autorização, direciona o usuário à URL do provedor retornada pela API e verifica o estado da conexão depois que o provedor redireciona o usuário de volta ao Postoria.

O mesmo fluxo de autorização pode retornar contas novas e existentes:

connectable_accounts contém contas do provedor que não estão conectadas no espaço de trabalho especificado.
reconnectable_accounts contém contas existentes nesse espaço de trabalho que podem ser autorizadas novamente com a concessão OAuth concluída.

Depois de examinar essas listas, chame o endpoint de conexão com os PIDs do provedor, o endpoint de reconexão com os IDs de conta do Postoria ou ambos, quando apropriado.

Liste as opções de conexão

Obtenha as redes sociais e os métodos de autenticação disponíveis no momento pela API pública:

GET /v1/social-account-connection-options

Exemplo de resposta:

{
  "data": [
    {
      "network": "facebook",
      "auth_methods": [
        "facebook_login",
        "meta_business_portfolio"
      ]
    },
    {
      "network": "instagram",
      "auth_methods": [
        "instagram_login",
        "facebook_login",
        "meta_business_portfolio"
      ]
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "next": null
  }
}

Não fixe a resposta de exemplo no código como se fosse a lista completa. Use este endpoint como fonte de referência, pois as opções aceitas podem mudar.

A versão inicial aceita estas opções:

Rede	Métodos de autenticação
`facebook`	`facebook_login`, `meta_business_portfolio`
`instagram`	`instagram_login`, `facebook_login`, `meta_business_portfolio`
`linkedin`	`linkedin_login`
`tumblr`	`tumblr_login`
`youtube`	`google_login`
`pinterest`	`pinterest_login`
`tiktok`	`tiktok_api_for_business`
`google_business_profile`	`google_login`
`threads`	`threads_login`

Inicie uma autorização

Crie um estado de conexão para um espaço de trabalho:

POST /v1/workspaces/{workspace_id}/social-account-connections

Exemplo de requisição:

{
  "network": "instagram",
  "auth_method": "instagram_login"
}

Resposta de sucesso (201 Created):

{
  "state": "e4b69043-ead1-428e-9c9a-5e212c4f058e",
  "is_completed": false,
  "authorization_url": "https://www.instagram.com/oauth/authorize?...",
  "expires_at": "2026-09-07T11:25:28.222872Z"
}

Abra authorization_url em um navegador e deixe o usuário concluir o fluxo do provedor. O provedor redireciona o navegador para o callback hospedado pelo Postoria, que registra o resultado do OAuth no state. Seu aplicativo não precisa fornecer uma URL de retorno nem chamar um endpoint separado de conclusão.

O estado expira uma hora após sua criação. Inicie uma nova autorização se expires_at já tiver passado. Um estado expirado ou pertencente a outro espaço de trabalho ou conta do Postoria retorna 404 social_account_connection_not_found.

Confira o resultado da autorização

Depois que o usuário concluir o fluxo do provedor, consulte o estado da conexão:

GET /v1/workspaces/{workspace_id}/social-account-connections/{state}

Você pode consultar este endpoint periodicamente enquanto is_completed for false. Esse valor indica que o Postoria ainda não recebeu e armazenou o callback OAuth; o campo não indica que as contas já foram conectadas ou reconectadas.

Exemplo de resposta com a autorização concluída:

{
  "state": "e4b69043-ead1-428e-9c9a-5e212c4f058e",
  "is_completed": true,
  "expires_at": "2026-09-07T11:25:28.222872Z",
  "network": "instagram",
  "auth_method": "instagram_login",
  "error": null,
  "connectable_accounts": [
    {
      "pid": "17841400000000001",
      "name": "Postoria Demo",
      "username": "postoria.demo",
      "description": "Demo account",
      "url": "https://www.instagram.com/postoria.demo/",
      "logo_url": "https://example.com/profile.jpg",
      "account_category": "profile"
    }
  ],
  "reconnectable_accounts": [
    {
      "account_id": 123,
      "pid": "17841400000000002",
      "name": "Postoria",
      "username": "postoria.app",
      "description": "Postoria",
      "url": "https://www.instagram.com/postoria.app/",
      "logo_url": "https://example.com/profile-2.jpg",
      "account_category": "profile"
    }
  ]
}

Se is_completed for true e error não for null, a autorização do provedor falhou ou foi recusada. Não chame nenhum dos endpoints de ação sobre contas; mostre o erro ou inicie uma nova autorização.

Conecte novas contas

Selecione um ou mais PIDs exatamente como retornados em connectable_accounts:

POST /v1/workspaces/{workspace_id}/social-account-connections/{state}/accounts

Exemplo de requisição:

{
  "pids": [
    "17841400000000001"
  ]
}

A requisição falha na validação se um PID não estiver disponível nessa autorização ou já estiver conectado no espaço de trabalho.

Reconecte contas existentes

Selecione um ou mais IDs de conta do Postoria exatamente como retornados em reconnectable_accounts:

POST /v1/workspaces/{workspace_id}/social-account-connections/{state}/reconnect

Exemplo de requisição:

{
  "account_ids": [123, 456]
}

Todas as contas solicitadas devem pertencer ao espaço de trabalho e à rede especificados, e a concessão OAuth concluída deve fornecer acesso a elas. Se alguma conta solicitada não estiver disponível, a API retornará 400 social_accounts_not_available antes de reconectar as contas selecionadas.

Uma conta existente pode ser reconectada por qualquer método de autenticação atualmente aceito para sua rede; não precisa ser o mesmo método usado na conexão original. Sempre selecione o account_id retornado, em vez de tentar identificar a correspondência das contas por conta própria.

Resposta da ação sobre contas

Os endpoints de conexão e reconexão retornam as contas do Postoria afetadas:

{
  "state": "e4b69043-ead1-428e-9c9a-5e212c4f058e",
  "accounts": [
    {
      "id": 123,
      "name": "Postoria",
      "custom_name": "Channel 113",
      "description": "postoria.app",
      "network": "instagram",
      "url": "https://www.instagram.com/postoria.app/",
      "metadata": {
        "channel_number": "113"
      }
    }
  ]
}

Liste as contas de redes sociais

Use este endpoint para obter as contas de redes sociais conectadas em um espaço de trabalho:

GET /v1/workspaces/{workspace_id}/social-accounts

Exemplo de resposta:

{
  "data": [
    {
      "id": 123,
      "name": "Postoria",
      "custom_name": "Channel 113",
      "description": "postoria.app",
      "network": "instagram",
      "url": "https://www.instagram.com/postoria.app",
      "metadata": {
        "channel_number": "113",
        "owner_account": "acme-media"
      }
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "next": null
  }
}

name é o nome da conta recebido da rede social. custom_name é um nome opcional definido no Postoria. metadata é um objeto opcional com chaves e valores de texto controlados pela sua integração. As chaves de metadados mantêm suas maiúsculas e minúsculas originais.

Use os IDs de conta retornados em social_account_ids ao criar posts. Você também pode usar metadados para associar cada conta conectada a um identificador estável no seu próprio sistema.

Use este endpoint para definir ou atualizar o nome personalizado e os metadados de uma conta de rede social conectada:

PATCH /v1/workspaces/{workspace_id}/social-accounts/{social_account_id}

Exemplo de requisição:

{
  "custom_name": "Channel 113",
  "metadata": {
    "channel_number": "113",
    "owner_account": "acme-media",
    "group": "north-america"
  }
}

Ambos os campos são opcionais, mas a requisição deve incluir pelo menos um deles. Campos omitidos permanecem inalterados.

Comportamentos importantes:

Os espaços em branco das extremidades de custom_name são removidos antes de armazená-lo, e ele pode conter até 255 caracteres.
Defina custom_name como null ou uma string vazia para deixar de usar um nome personalizado na interface do Postoria.
metadata deve ser um objeto JSON com chaves e valores de texto.
Os metadados podem conter até 50 entradas. As chaves podem ter até 64 caracteres e os valores, até 1.024 caracteres.
Enviar metadata substitui o objeto de metadados inteiro; as chaves individuais não são mescladas.
Defina metadata como null para limpá-lo, ou como {} para manter um objeto de metadados vazio.
Os nomes personalizados e os metadados permanecem associados à conta de rede social do Postoria quando ela é reconectada ou autorizada novamente.

Resposta de sucesso:

{
  "id": 123,
  "name": "Postoria",
  "custom_name": "Channel 113",
  "description": "postoria.app",
  "network": "instagram",
  "url": "https://www.instagram.com/postoria.app",
  "metadata": {
    "channel_number": "113",
    "owner_account": "acme-media",
    "group": "north-america"
  }
}

Se a conta de rede social não existir no espaço de trabalho especificado, a API retornará 404 social_account_not_found.

Use este endpoint para remover uma conta de rede social conectada de um espaço de trabalho:

DELETE /v1/workspaces/{workspace_id}/social-accounts/{social_account_id}

O parâmetro de consulta force é opcional e tem false como padrão. Por padrão, a conta não pode ser removida enquanto estiver selecionada em posts com status scheduled ou queued. Rascunhos não impedem a remoção.

Se ainda houver posts agendados ou na fila, a API retornará 409 social_account_has_scheduled_posts sem alterar a conta nem suas associações com os posts:

{
  "error": {
    "code": "social_account_has_scheduled_posts",
    "message": "The social account cannot be deleted while scheduled or queued posts remain.",
    "param": null,
    "details": {
      "post_ids": [3001, 3002],
      "has_more": false
    },
    "request_id": "01JEXAMPLE"
  }
}

post_ids contém os IDs de até 10 posts que impedem a remoção. Se houver mais posts impedindo a remoção, has_more será true.

Para remover a conta mesmo quando ainda houver posts agendados ou na fila, defina force=true:

DELETE /v1/workspaces/{workspace_id}/social-accounts/{social_account_id}?force=true

Quando a exclusão prossegue, o Postoria aplica o mesmo procedimento de limpeza do painel. A conta é removida dos rascunhos, dos posts agendados e na fila e das automações conectadas. Posts que ficarem sem nenhuma conta de rede social também poderão ser excluídos.

Remover uma conta a desconecta do espaço de trabalho do Postoria. Isso não revoga a autorização na rede social. Uma requisição bem-sucedida retorna 204 No Content. Se a conta de rede social não existir no espaço de trabalho especificado ou já tiver sido removida, a API retornará 404 social_account_not_found.

Liste as filas

Use este endpoint para obter as filas de um espaço de trabalho:

GET /v1/workspaces/{workspace_id}/queues

Exemplo de resposta:

{
  "data": [
    {
      "id": 456,
      "name": "Morning posts",
      "is_paused": false
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "next": null
  }
}

Use o ID de fila retornado ao criar um post com publish_mode definido como queue.

Envie mídia

Há duas maneiras de adicionar mídia pela API:

Crie uma URL de upload e envie o arquivo diretamente.
Importe mídia de uma URL HTTPS pública.

Ambos os métodos criam um objeto de mídia. Use o endpoint de consulta do status da mídia para verificar quando ela está pronta.

Um item de mídia deve ter status definido como ready antes de você poder referenciá-lo ao criar um post.

Há duas maneiras de fornecer uma miniatura de vídeo:

Imagem de miniatura personalizada: envie ou importe um arquivo de imagem pelos endpoints de mídia. Quando o item de mídia da imagem estiver ready, passe seu ID como thumbnail_media_id para o vídeo em POST /posts.
Miniatura gerada de um quadro do vídeo: inclua thumbnail_timestamp_ms ao criar um upload de vídeo ou uma importação por URL. O valor é medido em milissegundos. O Postoria cria um item de mídia de imagem separado e retorna seu ID como thumbnail_media_id. Aguarde até que o vídeo e a imagem gerada estejam ready e passe esse ID em POST /posts.

Os tipos de upload aceitos incluem formatos comuns de imagem, vídeo e documento, como JPEG, PNG, WebP, GIF, MP4, MOV e PDF.

Envie mídia com uma URL de upload

Primeiro, crie um upload:

POST /v1/workspaces/{workspace_id}/media/uploads

Requisição:

{
  "name": "image.jpg",
  "content_type": "image/jpeg"
}

Exemplo de resposta:

{
  "id": 9001,
  "status": "waiting_for_upload",
  "upload": {
    "url": "https://temporary-upload-url.example"
  }
}

Para gerar uma miniatura em um upload direto de vídeo, inclua o instante opcional ao criar o upload:

{
  "name": "video.mp4",
  "content_type": "video/mp4",
  "thumbnail_timestamp_ms": 5000
}

A resposta 201 Created contém o ID de mídia da miniatura gerada antes de o processamento de qualquer um dos arquivos terminar:

{
  "id": 9002,
  "status": "waiting_for_upload",
  "thumbnail_media_id": 9003,
  "upload": {
    "url": "https://temporary-upload-url.example"
  }
}

Envie os bytes do arquivo para a upload.url retornada usando uma requisição HTTP PUT. Envie os bytes brutos do arquivo no corpo da requisição e use o mesmo valor de content_type informado ao criar o upload.

Exemplo:

curl -X PUT "https://temporary-upload-url.example" \
  -H "Content-Type: image/jpeg" \
  --data-binary "@image.jpg"

A URL de upload é temporária. Se ela expirar antes de você enviar e concluir o item de mídia, crie um novo upload.

Depois de enviar o arquivo, conclua o upload:

POST /v1/workspaces/{workspace_id}/media/{media_id}/complete

Exemplo de resposta:

{
  "id": 9001,
  "status": "processing",
  "file_id": null,
  "error_code": null,
  "error_message": null
}

O Postoria processará a mídia em segundo plano.

Importe mídia de uma URL

Use este endpoint quando o arquivo de mídia já estiver disponível em uma URL HTTPS pública:

POST /v1/workspaces/{workspace_id}/media/imports

Requisição:

{
  "url": "https://example.com/video.mp4",
  "thumbnail_timestamp_ms": 5000
}

Exemplo de resposta:

{
  "id": 9002,
  "status": "processing",
  "file_id": null,
  "thumbnail_media_id": 9003,
  "error_code": null,
  "error_message": null
}

Apenas URLs HTTPS públicas são aceitas. URLs privadas, URLs que exigem autenticação, arquivos locais e caminhos relativos não são aceitos.

Neste exemplo, o item de mídia 9002 é o vídeo, e o item de mídia 9003 é a miniatura gerada. Consulte os dois itens periodicamente até que estejam prontos. O vídeo de origem contém thumbnail_media_id, enquanto a miniatura gerada contém o thumbnail_timestamp_ms solicitado.

O mesmo campo opcional pode ser incluído ao criar um upload direto de vídeo. Ele só é válido para mídias de vídeo e deve ser maior ou igual a zero.

Confira o status da mídia

Use este endpoint para verificar se um item de mídia está pronto:

GET /v1/workspaces/{workspace_id}/media/{media_id}

Exemplo de resposta de mídia pronta:

{
  "id": 9001,
  "status": "ready",
  "file_id": 701,
  "error_code": null,
  "error_message": null
}

Exemplo de resposta de miniatura gerada:

{
  "id": 9003,
  "status": "ready",
  "file_id": 702,
  "thumbnail_timestamp_ms": 5000,
  "error_code": null,
  "error_message": null
}

Exemplo de resposta de falha:

{
  "id": 9001,
  "status": "failed",
  "file_id": null,
  "error_code": "media_processing_failed",
  "error_message": "The file format is not supported."
}

Status da mídia:

waiting_for_upload
processing
ready
failed

Crie um post

Use este endpoint para criar um post:

POST /v1/workspaces/{workspace_id}/posts

A API não cria rascunhos. Um post é criado para um destes modos de publicação:

publish_now
schedule
queue

scheduled_time é obrigatório apenas para schedule. queue_id é obrigatório apenas para queue. Nenhum dos campos deve ser enviado para publish_now.

Todas as contas de redes sociais selecionadas devem aceitar o tipo de conteúdo escolhido; caso contrário, a requisição é rejeitada.

Exemplo de requisição de post agendado:

{
  "publish_mode": "schedule",
  "social_account_ids": [123],
  "content_type": "image",
  "media": [
    {
      "media_id": 9001
    }
  ],
  "caption": "Post caption",
  "first_comment": "More details in the first comment.",
  "comment_delay": 5,
  "is_ai_generated": true,
  "scheduled_time": "2026-06-01T10:00:00Z"
}

Exemplo de resposta:

{
  "id": 3001,
  "status": "scheduled",
  "date": "2026-06-01T10:00:00Z",
  "queue_id": null,
  "is_ai_generated": true,
  "results": [
    {
      "account_id": 123,
      "link_to_post": null,
      "error": null
    }
  ],
  "instagram": {
    "content": "image",
    "caption": "Post caption",
    "files": [
      {
        "url": "https://assets.postoria.io/w/1/image.jpg?st=temporary_signed_token"
      }
    ],
    "comment": "More details in the first comment.",
    "comment_delay": 5
  }
}

As respostas de posts incluem um objeto para cada rede social habilitada no post, como facebook, instagram, linkedin, youtube ou tiktok. Cada objeto de rede contém:

content: o tipo de conteúdo efetivo para aquela rede.
caption: o texto da legenda para aquela rede.
files: os arquivos de mídia para aquela rede. As URLs dos arquivos são assinadas e temporárias, e podem ser abertas sem autenticação por cerca de uma hora. Um vídeo também pode incluir thumbnail_url quando houver uma miniatura disponível. thumbnail_timestamp_ms só é incluído quando a miniatura foi gerada a partir de um quadro do vídeo.

Exemplo de arquivo de vídeo com miniatura gerada:

{
  "url": "https://assets.postoria.io/w/1/video.mp4?st=temporary_signed_token",
  "thumbnail_url": "https://assets.postoria.io/w/1/thumbnail.png?st=temporary_signed_token",
  "thumbnail_timestamp_ms": 5000
}

Dependendo da rede e do tipo de conteúdo, um objeto de rede também pode incluir comment e comment_delay, link ou opções de publicação específicas da rede. comment_delay é medido em minutos. Posts de link e primeiros comentários só estão disponíveis quando a rede e o tipo de conteúdo selecionados oferecem suporte. Stories não aceitam primeiros comentários.

Os resultados de publicação são retornados por conta em results, quando disponíveis. Para posts agendados ou na fila, os resultados podem não estar disponíveis até que o post seja processado. Um post pode ter resultados bem-sucedidos e com falha em contas diferentes.

Identificação de conteúdo gerado por IA

Defina o campo is_ai_generated do nível superior como true quando o post deve exibir a identificação de conteúdo gerado por IA das redes sociais compatíveis.

{
  "is_ai_generated": true
}

O Postoria envia a identificação correspondente quando o destino e o tipo de conteúdo oferecem suporte:

Contas do Instagram
Posts de vídeo do TikTok
Vídeos do YouTube
Posts do X
Pins do Pinterest

A configuração não é enviada para posts de fotos do TikTok. Destinos e tipos de conteúdo incompatíveis a ignoram.

Campos de data e horário

Os campos de data e horário usam strings UTC no formato ISO 8601.

Exemplo:

"scheduled_time": "2026-06-01T10:00:00Z"

Use UTC e inclua o Z no final.

Se estiver agendando com base em um horário local, converta-o para UTC antes de enviá-lo à API.

Crie um post para publicar agora

Defina publish_mode como publish_now.

{
  "publish_mode": "publish_now",
  "social_account_ids": [123],
  "content_type": "image",
  "media": [
    {
      "media_id": 9001
    }
  ],
  "caption": "Publishing from Postoria Public API"
}

Agende um post

Defina publish_mode como schedule e informe scheduled_time.

{
  "publish_mode": "schedule",
  "social_account_ids": [123],
  "content_type": "image",
  "media": [
    {
      "media_id": 9001
    }
  ],
  "caption": "Scheduled from Postoria Public API",
  "scheduled_time": "2026-06-01T10:00:00Z"
}

scheduled_time deve estar no futuro.

Adicione um post a uma fila

Defina publish_mode como queue e informe queue_id.

{
  "publish_mode": "queue",
  "social_account_ids": [123],
  "content_type": "image",
  "media": [
    {
      "media_id": 9001
    }
  ],
  "caption": "Queued from Postoria Public API",
  "queue_id": 456
}

A fila deve pertencer ao mesmo espaço de trabalho.

Tipos de conteúdo

Valores aceitos para content_type:

text
image
video
document
carousel
link
story
reel

Se content_type não for informado, o Postoria tentará identificá-lo a partir dos dados da requisição:

Vários itens de mídia → carousel
Um item de mídia → o tipo de mídia correspondente, como image, video ou document
URL de link sem mídia → link
Apenas legenda → text

A validação específica de cada rede social continua valendo. Todas as contas de redes sociais selecionadas devem aceitar o tipo de conteúdo solicitado; caso contrário, a API retorna um erro de validação e não cria o post.

Adicione mídia a um post

Use o array media para referenciar itens de mídia criados pelos endpoints de upload ou importação. Cada item deve ter status definido como ready.

{
  "media": [
    {
      "media_id": 9001
    }
  ]
}

Para um vídeo, você pode fornecer uma miniatura opcional. thumbnail_media_id pertence ao media_id correspondente e deve referenciar um item de mídia de imagem pronto.

Para uma imagem de miniatura personalizada, envie ou importe o arquivo de imagem pelos endpoints de mídia e use seu ID de mídia.
Para uma miniatura gerada de um quadro do vídeo, envie thumbnail_timestamp_ms ao criar o upload ou a importação do vídeo e use o thumbnail_media_id retornado depois que estiver ready.

Nos dois casos, POST /posts recebe thumbnail_media_id. O instante é informado apenas ao criar o item de mídia do vídeo, e não ao criar o post.

{
  "media": [
    {
      "media_id": 9002,
      "thumbnail_media_id": 9003
    }
  ]
}

Posts de link

Para posts de link, informe link_url:

{
  "publish_mode": "schedule",
  "social_account_ids": [123],
  "content_type": "link",
  "caption": "Useful link",
  "link_url": "https://example.com/article",
  "scheduled_time": "2026-06-01T10:00:00Z"
}

O Postoria importará as informações do link ao criar o post.

Primeiro comentário

Use first_comment para adicionar um primeiro comentário quando a rede selecionada oferecer suporte. Use comment_delay para atrasar o primeiro comentário; o valor é medido em minutos.

{
  "first_comment": "More details in the first comment."
}

As regras específicas de cada rede continuam valendo. Os campos de resposta do primeiro comentário são retornados apenas para redes que aceitam primeiros comentários.

Opções do Facebook

Use o objeto facebook para as opções específicas do Facebook:

{
  "facebook": {
    "location_id": "12345678901234567890",
    "also_publish_media_to_stories": true
  }
}

location_id é opcional e deve ser uma string numérica positiva com no máximo 64 dígitos. Ele identifica a Página do Facebook do local físico que a Meta deve associar ao post. Envie o ID como uma string JSON, e não como um número, para preservar IDs grandes com exatidão.

Quando also_publish_media_to_stories é true, o Postoria cria primeiro a publicação comum do Facebook e depois publica cada arquivo de mídia anexado como um Story separado do Facebook. A opção não tem efeito quando content_type é story ou link.

Opções do Instagram

Use o objeto instagram para as opções específicas do Instagram:

{
  "instagram": {
    "location_id": "12345678901234567890",
    "also_publish_media_to_stories": true,
    "collaborators": ["creator_one"],
    "publish_as_trial_reel": false,
    "auto_share_if_performs_well": false,
    "user_tags": [
      {
        "media_id": 9001,
        "username": "creator_one",
        "x": 0.5,
        "y": 0.5
      }
    ]
  }
}

location_id é opcional e segue o mesmo formato da opção do Facebook: uma string numérica positiva com no máximo 64 dígitos. Ele deve identificar uma Página do Facebook associada a um local físico.

Quando also_publish_media_to_stories é true, o Postoria cria primeiro a publicação comum do Instagram e depois publica cada arquivo de mídia anexado como um Story separado do Instagram. A opção não tem efeito quando content_type é story.

user_tags.media_id deve referenciar uma mídia anexada ao mesmo post. Nas respostas de posts, as marcações de usuários usam file_id em vez de media_id.

Opções do Pinterest

Use o objeto pinterest para as opções específicas do Pinterest:

{
  "pinterest": {
    "title": "Pin title",
    "website": "https://example.com/article",
    "alt_text": "A description of the image"
  }
}

website é a URL de destino do Pin.

Opções do Perfil da Empresa no Google

Use o objeto google_business_profile para adicionar um botão de ação:

{
  "google_business_profile": {
    "button_type": "LEARN_MORE",
    "button_url": "https://example.com"
  }
}

Os tipos de botão aceitos são BOOK, ORDER, SHOP, LEARN_MORE, SIGN_UP e CALL. Uma URL de botão é obrigatória para todos os tipos, exceto CALL.

Configurações de republicação

Use repost para configurar a republicação.

Exemplo:

{
  "repost": {
    "frequency": "do_not_repeat",
    "until": null
  }
}

Se você definir uma frequência de republicação, until deverá ser uma data e um horário futuros em UTC quando as configurações de republicação selecionadas exigirem esse campo.

Opções do YouTube

Use o objeto youtube ao criar posts para contas do YouTube.

Exemplo:

{
  "youtube": {
    "title": "Video title",
    "visibility": "public",
    "category": "People & Blogs",
    "made_for_kids": false,
    "video_language": "en",
    "recording_date": "2026-06-01T00:00:00Z",
    "tags": ["tag1", "tag2"]
  }
}

Use os campos do YouTube apenas quando pelo menos uma conta de rede social selecionada for do YouTube.

Para ver os valores aceitos pelo YouTube, consulte a documentação de importação em lote: Como importar posts em lote com um arquivo CSV no Postoria.

Opções do TikTok

Use o objeto tiktok ao criar posts para contas do TikTok.

Exemplo:

{
  "tiktok": {
    "who_can_watch": "public",
    "allow_comments": true,
    "allow_duet": false,
    "allow_stitch": false,
    "disclose_post_content": false,
    "your_brand": false,
    "branded_content": false,
    "photo_title": "Photo title",
    "auto_add_music": false
  }
}

Campos aceitos para o TikTok:

who_can_watch: public, followers, friends ou private
allow_comments: true ou false
allow_duet: true ou false
allow_stitch: true ou false
disclose_post_content: true ou false
your_brand: true ou false
branded_content: true ou false
photo_title: texto simples com até 90 caracteres
auto_add_music: true ou false

Use os campos do TikTok apenas quando pelo menos uma conta de rede social selecionada for do TikTok.

Opções do Tumblr

Use o objeto tumblr para adicionar tags nativas do Tumblr separadamente da legenda do post:

{
  "caption": "Explore our latest indie game",
  "tumblr": {
    "tags": ["gaming", "indiegame", "steam", "hades2"]
  }
}

O Postoria aceita até 30 tags do Tumblr. Ele remove espaços em branco das extremidades, remove um # inicial, ignora valores vazios e elimina tags duplicadas sem diferenciar maiúsculas de minúsculas. Um item individual do array não pode conter vírgula nem aspas duplas. Use as opções do Tumblr apenas quando pelo menos uma conta de rede social selecionada for do Tumblr.

Liste os posts

Use este endpoint para listar os posts de um espaço de trabalho:

GET /v1/workspaces/{workspace_id}/posts

Parâmetros de consulta opcionais:

account_ids: IDs de contas de redes sociais. Repita o parâmetro ou use valores separados por vírgulas.
queue_id: ID da fila.
status: um dos valores draft, scheduled, in_progress, posted ou queued.
networks: um ou mais valores de rede, como instagram, facebook, linkedin, youtube ou tiktok.
date_from: data e horário agendados iguais ou posteriores a este valor UTC.
date_to: data e horário agendados anteriores a este valor UTC.
limit: quantidade de posts a retornar. O padrão é 25; o máximo é 100.
cursor: cursor de paginação retornado pela página anterior.

account_ids e queue_id devem pertencer ao espaço de trabalho especificado.

Exemplo de requisição:

curl "https://api.postoria.io/v1/workspaces/1/posts?status=scheduled&limit=25" \
  -H "Authorization: Bearer pst_live_your_api_key"

Exemplo de resposta:

{
  "data": [
    {
      "id": 3001,
      "status": "scheduled",
      "date": "2026-06-01T10:00:00Z",
      "queue_id": null,
      "is_ai_generated": true,
      "results": [
        {
          "account_id": 123,
          "link_to_post": null,
          "error": null
        }
      ],
      "instagram": {
        "caption": "Scheduled post caption",
        "files": [
          {
            "url": "https://assets.postoria.io/w/1/image.jpg?st=temporary_signed_token"
          }
        ]
      }
    }
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "eyJJZCI6MzAwMSwiRGF0ZSI6IjIwMjYtMDYtMDFUMTA6MDA6MDBaIiwiUXVldWVQb3NpdGlvbiI6bnVsbH0",
    "next": "https://api.postoria.io/v1/workspaces/1/posts?status=scheduled&limit=25&cursor=eyJJZCI6MzAwMSwiRGF0ZSI6IjIwMjYtMDYtMDFUMTA6MDA6MDBaIiwiUXVldWVQb3NpdGlvbiI6bnVsbH0"
  }
}

Para solicitar a próxima página, chame next diretamente ou envie next_cursor de volta como cursor:

GET /v1/workspaces/{workspace_id}/posts?status=scheduled&limit=25&cursor=eyJJZCI6MzAwMSwiRGF0ZSI6IjIwMjYtMDYtMDFUMTA6MDA6MDBaIiwiUXVldWVQb3NpdGlvbiI6bnVsbH0

Confira o status do post

Use este endpoint para verificar o status de um post:

GET /v1/workspaces/{workspace_id}/posts/{post_id}

date é o horário de publicação agendado. Pode ser null para posts na fila ou de publicação imediata.

Exemplo de resposta:

{
  "id": 3001,
  "status": "posted",
  "date": "2026-06-01T10:00:00Z",
  "queue_id": null,
  "is_ai_generated": true,
  "results": [
    {
      "account_id": 123,
      "link_to_post": "https://www.instagram.com/p/example",
      "error": null
    }
  ],
  "instagram": {
    "caption": "Published post caption",
    "files": [
      {
        "url": "https://assets.postoria.io/w/1/image.jpg?st=temporary_signed_token"
      }
    ]
  }
}

Status dos posts:

draft
scheduled
in_progress
posted
queued

Significado dos itens de resultado:

link_to_post é definido quando o post foi publicado com sucesso e há um link público disponível.
error é definido quando a publicação falhou para aquela conta.
Tanto link_to_post quanto error podem ser null antes de o post ser publicado.

Exclua um post

Use este endpoint para excluir um post:

DELETE /v1/workspaces/{workspace_id}/posts/{post_id}

Resposta de sucesso:

204 No Content

O post deve pertencer ao espaço de trabalho especificado.

Excluir um post o remove do Postoria. Isso não exclui posts já publicados nas redes sociais. Se a publicação já tiver começado, excluir o post do Postoria não interromperá essa publicação. Os resultados das contas são removidos junto com o post e não podem ser consultados depois.

Consulte as análises de posts específicos

Use este endpoint para consultar as análises mais recentes disponíveis para um conjunto de 1 a 100 IDs de posts do Postoria:

GET /v1/workspaces/{workspace_id}/analytics/posts?post_ids=3001&post_ids=3002

Repita post_ids para cada post. Os IDs devem ser números inteiros positivos. IDs duplicados são aceitos e tratados como um único ID.

Todos os posts solicitados devem pertencer ao espaço de trabalho. Se algum post não existir ou pertencer a outro espaço de trabalho, a requisição inteira falhará com 404 post_not_found; a resposta não identifica quais IDs causaram a falha.

A resposta contém uma linha para cada publicação nas contas de redes sociais selecionadas que esteja associada aos posts solicitados. As métricas são representadas como pares de nome e valor, pois a disponibilidade varia por rede e pode mudar com o tempo:

{
  "data": [
    {
      "post_id": 3001,
      "social_account_id": 123,
      "network": "tiktok",
      "content_type": "video",
      "published_at": "2026-08-01T10:00:00Z",
      "analytics_refreshed_at": "2026-08-25T12:34:56Z",
      "metrics": [
        { "name": "views", "value": 1250 },
        { "name": "likes", "value": 84 }
      ]
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null,
    "next": null
  }
}

Métricas indisponíveis são omitidas. Quando uma métrica tem valor zero, esse zero é retornado. analytics_refreshed_at é o horário em UTC no formato ISO 8601 em que o Postoria atualizou com sucesso, pela última vez, as análises da publicação a partir da rede social. Se a publicação existir, mas as análises ainda não estiverem disponíveis, analytics_refreshed_at será null e metrics será um array vazio.

Os valores de rede nas análises usam identificadores canônicos, como linkedin, youtube, tiktok e google_business_profile.

As métricas do YouTube usam nomes distintos com o prefixo youtube_. Alguns exemplos são youtube_views, youtube_engaged_views, youtube_likes, youtube_dislikes, youtube_estimated_minutes_watched, youtube_average_view_duration e youtube_subscribers_gained. O endpoint de análises de posts pode retornar métricas aditivas e médias ou taxas não aditivas.

Obtenha um resumo agregado do desempenho dos posts

Use este endpoint para agregar as métricas mais recentes disponíveis dos posts publicados durante um intervalo UTC:

GET /v1/workspaces/{workspace_id}/analytics/post-performance/summary?published_from=2026-08-01T00:00:00Z&published_to=2026-09-01T00:00:00Z&granularity=day&group_by=network

Parâmetros de consulta obrigatórios:

published_from: instante inicial inclusivo em UTC no formato ISO 8601, usando Z ou +00:00.
published_to: instante final exclusivo em UTC no formato ISO 8601, usando Z ou +00:00.

O intervalo deve ser maior que zero e não pode exceder 366 dias.

Parâmetros de consulta opcionais:

granularity: hour, day, month ou year. Omita para não retornar agrupamentos por período de publicação.
group_by: network, content_type ou social_account. Omita para não retornar uma dimensão adicional de agrupamento.

granularity e group_by são independentes. Por exemplo, você pode agrupar por rede sem agrupar por período, usar agrupamentos diários sem agrupar por outra dimensão, combinar ambos ou omitir ambos para obter uma única linha com o total.

Quando granularity está presente, os períodos de agrupamento usam o fuso horário do espaço de trabalho. A resposta inclui esse fuso horário IANA e um published_period para cada linha. Os campos start e end do período são instantes UTC, end é exclusivo e key é o rótulo do período correspondente no horário local do espaço de trabalho.

{
  "data": [
    {
      "published_period": {
        "start": "2026-08-01T04:00:00Z",
        "end": "2026-08-02T04:00:00Z",
        "key": "2026-08-01"
      },
      "network": "linkedin",
      "post_count": 3,
      "metrics": [
        { "name": "views", "value": 4200 },
        { "name": "comments", "value": 17 }
      ]
    }
  ],
  "timezone": "America/New_York"
}

Se granularity for omitido, tanto published_period quanto o campo timezone do nível superior serão omitidos. Quando group_by é omitido, nenhum campo de agrupamento é retornado. Caso contrário, cada linha contém exatamente um campo aplicável: network, content_type ou social_account_id.

O resumo agrupa os posts pelo momento em que foram publicados. Ele soma as métricas mais recentes disponíveis; não mostra quando as visualizações, reações ou outras interações aconteceram. Totais de métricas iguais a zero ou indisponíveis são omitidos das linhas do resumo. Métricas não aditivas, como video_skip_rate, video_average_watch_time_milliseconds, médias do YouTube e taxas do YouTube, não são incluídas porque não podem ser somadas corretamente.

Erros comuns

Chave de API inválida

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key is invalid or has been revoked.",
    "param": null,
    "details": null,
    "request_id": "req_abc123"
  }
}

Plano necessário

{
  "error": {
    "code": "public_api_plan_required",
    "message": "Public API access is available on Pro and Agency plans.",
    "param": null,
    "details": null,
    "request_id": "req_abc123"
  }
}

Falha na validação

{
  "error": {
    "code": "validation_failed",
    "message": "One or more fields are invalid.",
    "param": "content_type",
    "details": {
      "reason": "The selected social account does not support this content type."
    },
    "request_id": "req_abc123"
  }
}

Espaço de trabalho não encontrado

{
  "error": {
    "code": "workspace_not_found",
    "message": "The requested workspace was not found.",
    "param": "workspace_id",
    "details": null,
    "request_id": "req_abc123"
  }
}

Boas práticas

Guarde sua chave de API com segurança.
Não exponha a chave de API no código do frontend.
Envie ou importe a mídia primeiro e aguarde até que o status dela seja ready.
Use GET /posts/{post_id} para verificar o status depois de criar um post.
Trate os nomes das métricas de análises como extensíveis, em vez de fixar um conjunto no código.
Use UTC nos filtros do resumo; ao usar granularity, interprete as chaves dos períodos de agrupamento no fuso horário do espaço de trabalho retornado.
Trate os erros de validação e mostre a mensagem retornada aos seus usuários.
Faça novas tentativas apenas após respeitar os cabeçalhos de limite de requisições.
Revogue a chave imediatamente se achar que ela foi exposta.

Como usar a API pública do Postoria

Antes de começar

URL base

Crie uma chave de API

Autentique as requisições

Formato das respostas

Limite de requisições

Endpoints

Liste os espaços de trabalho

Conecte ou reconecte contas de redes sociais

Liste as opções de conexão

Inicie uma autorização

Confira o resultado da autorização

Conecte novas contas

Reconecte contas existentes

Resposta da ação sobre contas

Liste as contas de redes sociais

Atualize uma conta de rede social

Exclua uma conta de rede social

Liste as filas

Envie mídia

Envie mídia com uma URL de upload

Importe mídia de uma URL

Confira o status da mídia

Crie um post

Identificação de conteúdo gerado por IA

Campos de data e horário

Crie um post para publicar agora

Agende um post

Adicione um post a uma fila

Tipos de conteúdo

Adicione mídia a um post

Posts de link

Primeiro comentário

Opções do Facebook

Opções do Instagram

Opções do Pinterest

Opções do Perfil da Empresa no Google

Configurações de republicação

Opções do YouTube

Opções do TikTok

Opções do Tumblr

Liste os posts

Confira o status do post

Exclua um post

Consulte as análises de posts específicos

Obtenha um resumo agregado do desempenho dos posts

Erros comuns

Chave de API inválida

Plano necessário

Falha na validação

Espaço de trabalho não encontrado

Boas práticas