Skip to content
For developers

Posttai API and webhooks

The same token that connects your AI (MCP) also opens the REST API. Create posts, schedule them, upload media and get signed notices when something happens. Field names and API messages are in Portuguese.

Authentication

Create a token under Configurações → Tokens e MCP (Settings → Tokens and MCP, on the Profissional and Agência plans). It starts with ptt_, belongs to one brand and is shown only once. Send it on every request in the Authorization header:

curl https://api.posttai.com/tokens-api/atual \
  -H "Authorization: Bearer ptt_seu_token"
  • The token has the editor role: it creates, edits, schedules and cancels posts; it doesn't approve, and it can't touch the team, tokens, webhooks or plan.
  • If whoever created the token leaves the team, or the plan no longer includes the API, the token stops working immediately (401/403).
  • Times in ISO 8601. Send them with a time zone (2026-10-09T18:30:00-03:00); Posttai works on Brasília time.

Responses and errors

Every response comes in the same envelope. On errors, body carries a ready-to-show message, in Portuguese.

{ "status": "ok", "statusCode": 200, "body": { ... } }
{ "status": "error", "statusCode": 422, "body": "Escolha pelo menos um canal." }
  • 401 invalid or revoked token · 403 no permission or outside the plan · 404 doesn't exist in this brand · 409 state conflict · 422 invalid data · 429 rate limit.
  • General limit: 300 requests per minute per IP. AI has its own limit per person and per brand.

Channels

The brand's connected accounts. Connecting a new account is done in the app (or through the "ask the client to connect" link).

GET/canais

Lists connected accounts: _id, rede, nome, usuario and status (active, expired, error).

curl https://api.posttai.com/canais -H "Authorization: Bearer $POSTTAI_TOKEN"
GET/canais/redes

Available networks, with each one's text and media limits.

curl https://api.posttai.com/canais/redes -H "Authorization: Bearer $POSTTAI_TOKEN"
GET/grupos-canais

Channel groups (e.g. "Client X"), to publish to several at once.

curl https://api.posttai.com/grupos-canais -H "Authorization: Bearer $POSTTAI_TOKEN"

Posts

A post has base text, channels, media and, if you like, its own text per channel (variacoes).

GET/posts?status=agendado&de=…&ate=…

Lists posts. status accepts several values separated by commas; de/ate filter by scheduled date.

curl "https://api.posttai.com/posts?status=agendado,publicado&de=2026-10-01&ate=2026-10-31" -H "Authorization: Bearer $POSTTAI_TOKEN"
GET/posts/:id

A post with its per-network publications (link and error for each) and history.

curl https://api.posttai.com/posts/ID_DO_POST -H "Authorization: Bearer $POSTTAI_TOKEN"
POST/posts

Creates a draft. canais and midias are ids; variacoes is optional.

curl -X POST https://api.posttai.com/posts -H "Authorization: Bearer $POSTTAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"conteudo":"Novidade na loja!","canais":["ID_DO_CANAL"],"midias":[]}'
PUT/posts/:id

Changes text, channels, media, variations or date (the same fields as POST).

curl -X PUT https://api.posttai.com/posts/ID_DO_POST -H "Authorization: Bearer $POSTTAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"conteudo":"Texto novo"}'
POST/posts/:id/agendar

Schedules. If the brand requires approval, the post goes to the approval queue instead.

curl -X POST https://api.posttai.com/posts/ID_DO_POST/agendar -H "Authorization: Bearer $POSTTAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agendadoPara":"2026-10-09T18:30:00-03:00"}'
POST/posts/:id/publicar-agora

Sends it to the publishing queue now.

curl -X POST https://api.posttai.com/posts/ID_DO_POST/publicar-agora -H "Authorization: Bearer $POSTTAI_TOKEN"
POST/posts/:id/cancelar

Takes a scheduled post out of the queue (back to draft).

curl -X POST https://api.posttai.com/posts/ID_DO_POST/cancelar -H "Authorization: Bearer $POSTTAI_TOKEN"
DELETE/posts/:id

Deletes an idea, draft, canceled or failed post.

curl -X DELETE https://api.posttai.com/posts/ID_DO_POST -H "Authorization: Bearer $POSTTAI_TOKEN"
GET/calendario?de=…&ate=…

Posts in the period, in every calendar status.

curl "https://api.posttai.com/calendario?de=2026-10-01&ate=2026-10-31" -H "Authorization: Bearer $POSTTAI_TOKEN"
GET/sugestoes/horarios?rede=instagram&dias=7

Suggested free time slots in the coming days.

curl "https://api.posttai.com/sugestoes/horarios?rede=instagram&dias=7" -H "Authorization: Bearer $POSTTAI_TOKEN"

Media

POST/midias/url

Brings in an image or video from a public address and returns the _id to use in midias.

curl -X POST https://api.posttai.com/midias/url -H "Authorization: Bearer $POSTTAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://exemplo.com/foto.jpg"}'
POST/midias

Uploads a file (multipart, field arquivo, up to 100 MB).

curl -X POST https://api.posttai.com/midias -H "Authorization: Bearer $POSTTAI_TOKEN" -F "[email protected]"
GET/midias

The brand's media library.

curl https://api.posttai.com/midias -H "Authorization: Bearer $POSTTAI_TOKEN"

Workflow and comments

GET/fluxo

Stages of the brand's board.

curl https://api.posttai.com/fluxo -H "Authorization: Bearer $POSTTAI_TOKEN"
POST/posts/:id/etapa

Moves the post to another stage (with optional assignee and due date).

curl -X POST https://api.posttai.com/posts/ID_DO_POST/etapa -H "Authorization: Bearer $POSTTAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"etapa":"revisao"}'
GET/posts/:id/comentarios

Team comments on the post.

curl https://api.posttai.com/posts/ID_DO_POST/comentarios -H "Authorization: Bearer $POSTTAI_TOKEN"
POST/posts/:id/comentarios

Comments on the post.

curl -X POST https://api.posttai.com/posts/ID_DO_POST/comentarios -H "Authorization: Bearer $POSTTAI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"texto":"Pronto para revisar"}'

Webhooks

Under Configurações → Webhooks (Settings → Webhooks), owners and admins register up to 5 URLs per brand and choose the events. Each delivery is a POST with JSON, sent from our worker (it never blocks the app).

  • post.publicado the post went out on all networks (or on some of them, with status: "parcial").
  • post.erro one or more networks refused it for good.
  • post.aprovado approved by the team or the client (dados.por).
  • post.reprovado rejected by the team or changes requested by the client, with dados.motivo.
  • canal.desconectado the account left, expired or had its access removed on the network (dados.motivo).
  • webhook.teste only from the "Testar" (Test) button.
POST https://seu-sistema.com/webhooks/posttai
Content-Type: application/json
X-Posttai-Evento: post.publicado
X-Posttai-Entrega: 6702f0c1a9e4b1d2c3e4f5a6
X-Posttai-Assinatura: t=1791403800,v1=5f0c…e9

{
  "id": "6702f0c1a9e4b1d2c3e4f5a6",
  "evento": "post.publicado",
  "criadoEm": "2026-10-09T21:30:04.120Z",
  "idMarca": "66fe…",
  "dados": {
    "post": { "id": "6701…", "status": "publicado", "trecho": "Lançamento amanhã…", "agendadoPara": "2026-10-09T21:30:00.000Z", "publicadoEm": "2026-10-09T21:30:04.000Z" },
    "publicacoes": [{ "idCanal": "66ff…", "rede": "instagram", "status": "publicado", "url": "https://www.instagram.com/p/…", "erro": null }]
  }
}
  • Delivered = a 2xx response within 10 s. Redirects are not followed.
  • Retries: 408, 429, 5xx and network failures are retried after 30 s, 1, 2, 4 and 8 min (6 attempts). Other 4xx stop immediately.
  • Use id (same as X-Posttai-Entrega) to ignore duplicates: the same delivery may arrive more than once.
  • The last 20 deliveries for each URL, with body and response, stay on the webhook screen for 30 days.
  • https:// only. Internal or private addresses (localhost, 10/8, 172.16/12, 192.168/16, 169.254/16, ::1, fc00::/7…) are refused, including when the name resolves to them in DNS.

Verifying the signature

The secret (whsec_…) is shown once, when you create the webhook. The signature is HMAC-SHA256(secret, t + "." + raw body) in hexadecimal. Always verify against the body exactly as it arrived, before parsing the JSON, and reject a t older than 5 minutes.

import crypto from 'node:crypto'
import express from 'express'

const app = express()

// Corpo CRU: a assinatura é sobre os bytes que chegaram.
app.post('/webhooks/posttai', express.raw({ type: 'application/json' }), (req, res) => {
  const corpo = req.body.toString('utf8')
  const { t, v1 } = Object.fromEntries(String(req.get('X-Posttai-Assinatura')).split(',').map(p => p.split('=')))
  const esperado = crypto.createHmac('sha256', process.env.POSTTAI_WEBHOOK_SEGREDO).update(`${t}.${corpo}`).digest('hex')
  const ok = v1 && esperado.length === v1.length && crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(v1))
  if (!ok || Math.abs(Date.now() / 1000 - Number(t)) > 300) return res.sendStatus(401)

  const evento = JSON.parse(corpo)
  // ...trate evento.evento e evento.dados (ignore ids de entrega já vistos)
  res.sendStatus(204)
})

Start today

Plan your week today

Create your account, connect your networks and get your calendar ready. Try the Profissional plan free for 7 days, no card needed.

  • 7 days free
  • No card needed to try
  • Unlimited posts on every plan
Talk to us