MarkaestroMarkaestro

Desenvolvedores

API pública de publicação

Envie mídia, crie posts e publique no Facebook, Instagram, TikTok, LinkedIn, Threads e Pinterest, tudo vinculado a um produto por meio de uma chave de API do workspace. A forma recomendada de integrar é a Connect API, uma superfície pequena e simples em /api/connect/v1 que a maioria das ferramentas de agendamento pode usar como está.

Precisa de controle total, publicação explícita, verificação de execução de tarefas, webhooks assinados, lote, configurações por canal? A API avançada /api/public/v1 mais abaixo expõe tudo isso. Ambas compartilham a mesma autenticação, produtos e pipeline de publicação; use apenas essas rotas públicas versionadas (as rotas internas do app exigem autenticação de usuário do Firebase e não fazem parte do contrato público).

Facebook, Instagram e TikTok são manual-first via API. Esses canais usam manual_reminder por padrão: o Markaestro não chama a API da plataforma e move o post para a fila 'Para Publicar'. Passe deliveryMode: "direct_publish" para usar a API oficial. No TikTok, o padrão é a caixa de entrada, exceto quando settings.postMode é direct_post. LinkedIn, Threads e Pinterest publicam programaticamente por padrão.

Workspaces podem ter múltiplos produtos. Cada chave de API é vinculada a um produto no momento da criação, então as chamadas atingem esse produto automaticamente e solicitações para qualquer outro produto são rejeitadas.

Construindo um agente de IA?

Comece pelo guia do agente de IA. Ele traz esquemas de ferramentas prontos para copiar e colar, um resumo de prompt de sistema, as regras de nova tentativa e tratamento de erros que um agente precisa, e um guia rápido de quatro comandos. Seu agente também pode ler /llms.txt diretamente.

Especificação legível por máquina

Cada endpoint, formato de requisição e resposta e código de erro, em OpenAPI 3.1. Gerada a partir dos mesmos esquemas que a API valida, portanto não pode descrever uma API que não servimos.

Connect API
Recomendado
A forma padrão de integrar: uma superfície simples em snake_case em /api/connect/v1 que a maioria das ferramentas de agendamento pode usar como está. Ela mapeia a convenção comum create-upload-url → PUT → post para o mesmo workspace, autenticação, produtos e pipeline de publicação da API completa abaixo. Defina a URL base do cliente como /api/connect e autentique com uma chave de API do workspace vinculada a um produto (escopos posts.read, posts.write, media.write).
GET/api/connect/v1/social-accounts

Lista os destinos ligados de Facebook, Instagram, TikTok e LinkedIn como contas planas, cada uma etiquetada com o seu produto para que os clientes possam agrupar e distinguir. Cada canal tem o seu próprio caminho, sem distribuição entre canais.

GET/api/connect/v1/products

Lista marcas (nome na API: products) com suas contas conectadas aninhadas, um seletor com marca em primeiro lugar.

POST/api/connect/v1/media/create-upload-url

Retorna uma URL PUT assinada, de uso único e curta duração, mais um id de mídia.

PUT<upload_url>

Envie os bytes brutos da imagem para a URL assinada. Não é necessária chave de API, a assinatura já autoriza.

POST/api/connect/v1/posts

Cria um rascunho para cada conta selecionada. Defina is_draft=false com scheduled_at para agendar a entrega; o TikTok usa o envio para a caixa de entrada do criador.

GET/api/connect/v1/posts

Lista posts do workspace com status, legenda e URLs de mídia simplificados.

# 1. List connected accounts
curl "$MARKAESTRO_URL/api/connect/v1/social-accounts" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"

# 2. Request a signed upload url, then PUT the bytes
curl -X POST "$MARKAESTRO_URL/api/connect/v1/media/create-upload-url" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "mime_type": "image/png", "size_bytes": 184320, "name": "slide-1.png" }'
curl -X PUT "<upload_url>" -H "Content-Type: image/png" --data-binary @slide-1.png

# 3. Create a draft post for one or more accounts
curl -X POST "$MARKAESTRO_URL/api/connect/v1/posts" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "New drop",
    "media": ["ast_111", "ast_222"],
    "social_accounts": ["prod_123#instagram:instagram:ig_123"]
  }'

Cada conta retornada por /social-accounts é rotulada com seu product, o nome no formato da API para uma marca (a mesma conta pode aparecer sob várias marcas), e seu id codifica productId#destinationId, passe-o de volta literalmente em social_accounts, e a solicitação se propaga em um post por conta. Cada chave é vinculada a uma marca, então ela só vê e publica nessa marca. Posts do Facebook, Instagram e TikTok são manual-first, criados como rascunhos e publicados nativamente pelo proprietário do workspace a partir da fila 'Para Publicar' do Markaestro, nunca via API da plataforma. LinkedIn, Threads e Pinterest publicam programaticamente após uma ação de publicação explícita. O status do post é um entre draft, processing, posted ou failed. Facebook, Instagram, LinkedIn, TikTok e Threads são cada um seu próprio destino dedicado, publicar em um nunca se propaga para outro. Acompanhe o estado de publicação através de GET /api/connect/v1/posts.

Avançado: API Pública completa

A superfície completa /api/public/v1, publicação explícita, execuções de tarefas assíncronas, webhooks assinados, criação em lote e configurações por canal. Use quando a Connect API não for suficiente.

Meta e TikTok são manual-first
Posts do Facebook, Instagram e TikTok usam por padrão a fila manual 'Para Publicar', sem chamada à API da plataforma, o proprietário do workspace publica nativamente e confirma. Opte por publicação via API por post com deliveryMode.
Login do Instagram compatível
As marcas podem expor contas profissionais independentes do Instagram mesmo sem uma Página do Facebook vinculada.
TikTok oferece dois caminhos opcionais
A publicação via API usa a caixa de entrada por padrão. Defina settings.postMode como direct_post com um nível de privacidade para solicitar Direct Post quando seu app TikTok estiver aprovado.
Assíncrono por design
Toda publicação retorna um id de execução. Verifique as execuções ou inscreva-se em webhooks assinados em vez de assumir conclusão síncrona.
Marcas e destinos
Descubra as marcas e destinos de publicação disponíveis para a chave de API. As marcas são chamadas de products no formato da API, caminhos e payloads usam products/productId por compatibilidade retroativa, e os corpos de POST também aceitam brandId como um alias.
GET/api/public/v1/products

Lista as marcas da chave, além dos canais atualmente disponíveis para cada uma.

GET/api/public/v1/products/:id/destinations

Lista os destinos de publicação dessa marca, incluindo Login do Instagram independente, Página do Facebook, Threads, Perfil/Página do LinkedIn e destinos do TikTok conectados.

Mídia
Envie imagens ou vídeos para o armazenamento gerenciado do Markaestro antes de criar posts.
POST/api/public/v1/media/upload-sessions

Cria uma sessão de upload direto de 15 minutos com nome, tipo e tamanho exato.

PUT<uploadSession.uploadUrl>

Envia os bytes diretamente ao armazenamento com o Content-Type retornado, sem a chave de API.

POST/api/public/v1/media/upload-sessions/:id/finalize

Verifica tipo e tamanho e retorna o ativo de mídia; sessões concluídas podem ser repetidas com segurança.

POST/api/public/v1/media

Upload multipart de compatibilidade. Retorna um id de ativo e a URL hospedada.

Posts
Crie, liste, inspecione, publique e exclua posts para Facebook, Instagram, LinkedIn, Threads, Pinterest e TikTok.
POST/api/public/v1/posts

Cria um rascunho no workspace. Facebook, Instagram e TikTok usam por padrão publicação manual (deliveryMode manual_reminder); passe deliveryMode direct_publish para optar por publicação via API.

GET/api/public/v1/posts

Lista posts, do mais recente ao mais antigo. Filtre com ?status=scheduled para ver o que está na fila, e ?productId= para limitar a uma marca. Uma chave vinculada a uma marca sempre é limitada à sua própria marca e pode omitir productId.

GET/api/public/v1/posts/:id

Retorna o status atual do post, o modo de entrega e os resultados de publicação.

POST/api/public/v1/posts/:id/publish

Enfileira uma execução de publicação assíncrona. Posts manuais entram na fila 'Para Publicar' do workspace para publicação nativa; LinkedIn, Threads e Pinterest publicam diretamente; posts do Meta com opção ativada publicam via API oficial, e posts do TikTok com opção ativada usam o envio para caixa de entrada.

DELETE/api/public/v1/posts/:id

Exclui o post do Markaestro. Usa o escopo posts.write existente. Retorna 400 VALIDATION_POST_IS_PUBLISHING enquanto uma execução de publicação está em andamento. Excluir um post publicado não retira a cópia ativa na plataforma.

Execuções e Webhooks
Acompanhe trabalho assíncrono por verificação ou entrega de webhook assinado.
GET/api/public/v1/job-runs/:id

Retorna queued, running, succeeded ou failed.

POST/api/public/v1/webhook-endpoints

Registra um destino de webhook, até 25 endpoints ativos por workspace.

GET/api/public/v1/webhook-endpoints

Lista os destinos de webhook registrados para o escopo dessa chave de API.

DELETE/api/public/v1/webhook-endpoints/:id

Desativa um destino de webhook.

1. Listar produtos
Descubra quais produtos essa chave de API pode acessar.
curl "$MARKAESTRO_URL/api/public/v1/products" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"
2. Inspecionar destinos
Veja as páginas e contas vinculadas de um produto antes de criar o post. Use o destinationId retornado quando um produto tiver vários destinos, como um Perfil do LinkedIn mais Páginas.
curl "$MARKAESTRO_URL/api/public/v1/products/prod_123/destinations" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"
3. Enviar mídia
Cada post referencia ativos de mídia enviados anteriormente.
# 1. Create a 15-minute upload session
UPLOAD=$(curl -s -X POST "$MARKAESTRO_URL/api/public/v1/media/upload-sessions" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fileName":"launch-1.jpg","contentType":"image/jpeg","sizeBytes":184320}')

# 2. PUT bytes directly to uploadSession.uploadUrl with its returned headers
curl -X PUT "<upload_url>" -H "Content-Type: image/jpeg" --data-binary @launch-1.jpg

# 3. Finalize; the response contains asset.id for mediaAssetIds
curl -X POST "$MARKAESTRO_URL/api/public/v1/media/upload-sessions/<session_id>/finalize" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"
4. Criar um post
Crie um rascunho usando esses ids de ativos. O Instagram usa publicação manual por padrão; adicione "deliveryMode": "direct_publish" para optar por publicação via API oficial nesse post.
curl -X POST "$MARKAESTRO_URL/api/public/v1/posts" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: post-001" \
  -d '{
    "channel": "instagram",
    "caption": "Launch day carousel",
    "mediaAssetIds": ["ast_123", "ast_124"],
    "productId": "prod_123",
    "destinationId": "instagram:instagram:ig_123"
  }'
Exemplo do TikTok
Posts do TikTok chegam como rascunhos do Markaestro e usam publicação manual por padrão a partir da fila 'Para Publicar'. Com deliveryMode: "platform_inbox" (ou direct_publish), uma publicação explícita envia o rascunho para a caixa de entrada do criador no TikTok.
curl -X POST "$MARKAESTRO_URL/api/public/v1/posts" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: post-tt-001" \
  -d '{
    "channel": "tiktok",
    "caption": "Spring drop teaser",
    "mediaAssetIds": ["ast_vid_123"],
    "productId": "prod_123",
    "destinationId": "tiktok:tiktok:tt_open_123"
  }'
5. Enfileirar publicação
A publicação cria uma execução assíncrona. Posts manuais (o padrão do Facebook/Instagram/TikTok) vão para a fila 'Para Publicar' e disparam post.action_required; LinkedIn, Threads, Pinterest e posts do Meta com opção ativada publicam diretamente; posts do TikTok com opção ativada enfileiram o envio para caixa de entrada.
curl -X POST "$MARKAESTRO_URL/api/public/v1/posts/pst_123/publish" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY" \
  -H "Idempotency-Key: publish-001"
6. Revisar a programação e cancelar
Liste o que está na fila para uma marca, então exclua qualquer coisa que você não queira mais publicar. Ambos usam escopos que chaves existentes já possuem: posts.read e posts.write.
# The key is already bound to one brand
curl "$MARKAESTRO_URL/api/public/v1/posts?status=scheduled&limit=100" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"

# Cancel one
curl -X DELETE "$MARKAESTRO_URL/api/public/v1/posts/pst_123" \
  -H "Authorization: Bearer $MARKAESTRO_API_KEY"
Exemplo de payload de webhook
As entregas são assinadas com HMAC usando o segredo do seu webhook.
{
  "id": "evt_123",
  "type": "post.action_required",
  "createdAt": "2026-04-08T18:06:10.000Z",
  "workspaceId": "ws_123",
  "data": {
    "postId": "pst_123",
    "channel": "instagram",
    "status": "platform_action_required",
    "nextAction": "post_manually_from_reminder"
  }
}
Comportamento por canal
Regras de validação e entrega aplicadas pela API pública.

Facebook

Posts somente texto, imagem ou vídeo. Até 10 imagens ou 1 vídeo por post. Publicação manual por padrão; publicação direta com opção ativada.

Instagram

Pelo menos uma imagem ou vídeo, até 10 itens. Vídeo único publica como Reel. Publicação manual por padrão; publicação direta com opção ativada.

TikTok

Pelo menos uma imagem ou vídeo. Até 35 imagens ou 1 vídeo. Publicação manual por defeito; publicações ativadas vão para a caixa de entrada do TikTok do criador, ou diretamente para o perfil com postMode direct_post do TikTok.

LinkedIn

Texto, imagem única, vídeo único ou posts orgânicos de múltiplas imagens com até 20 imagens. Direcione para o Perfil conectado ou uma Página gerenciada.

X

Texto, até quatro imagens, um GIF ou um vídeo. Os controlos de resposta aplicam-se por publicação e a publicação é bloqueada quando o orçamento de custos do X do workspace se esgota.