Referência de API

Em Breve — A API REST pública está atualmente no nosso roadmap e ainda não está disponível. A documentação abaixo descreve o design planejado da API. Anunciaremos a disponibilidade no nosso changelog.

A API REST do PostClaw permitirá gerenciar posts, plataformas, automações e geração de IA de forma programática.

URL base: https://app.postclaw.fun/v1

Autenticação

Todas as requisições exigem um token Bearer. Gere chaves de API em Configurações → Chaves de API.

curl https://app.postclaw.fun/v1/posts \
  -H "Authorization: Bearer YOUR_API_KEY"

As chaves possuem escopo: read, write ou admin. Use o escopo mínimo necessário.

Limites de Taxa

Os cabeçalhos de limite de taxa são retornados em todas as respostas:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1743484800

Endpoints

Posts

# Listar posts
GET /v1/posts?status=scheduled&limit=20

# Criar um post
POST /v1/posts
{
  "content": "Sua legenda aqui",
  "platforms": ["twitter", "linkedin"],
  "scheduled_at": "2026-04-01T09:00:00Z",
  "media_ids": ["media_abc123"]
}

# Obter um post
GET /v1/posts/{id}

# Cancelar um post agendado
DELETE /v1/posts/{id}

Mídia

# Fazer upload de mídia
POST /v1/media
Content-Type: multipart/form-data
# Retorna: { "id": "media_abc123", "url": "...", "type": "image" }

# Listar biblioteca de mídia
GET /v1/media?type=image&limit=50

Plataformas

# Listar contas conectadas
GET /v1/platforms

# Desconectar uma conta
DELETE /v1/platforms/{id}

Geração de IA

# Gerar texto de post
POST /v1/ai/text
{
  "prompt": "Anuncie nosso novo recurso: modo escuro",
  "platform": "twitter",
  "tone": "casual"
}

# Gerar imagem
POST /v1/ai/image
{
  "prompt": "Configuração minimalista de mesa, luz natural",
  "size": "1024x1024"
}

Automações

# Listar automações
GET /v1/automations

# Acionar automação manualmente
POST /v1/automations/{id}/trigger
{ "input": "https://example.com/article" }

Webhooks

Registre uma URL para receber eventos:

POST /v1/webhooks
{
  "url": "https://yoursite.com/postclaw-events",
  "events": ["post.published", "post.failed", "automation.completed"]
}

Estrutura do payload do evento:

{
  "event": "post.published",
  "timestamp": "2026-04-01T09:00:05Z",
  "data": {
    "post_id": "post_xyz789",
    "platform": "twitter",
    "url": "https://twitter.com/user/status/..."
  }
}

Respostas de Erro

Todos os erros seguem um formato consistente:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Muitas requisições. Tente novamente após 60 segundos.",
    "retry_after": 60
  }
}

Códigos de erro comuns: unauthorized, forbidden, not_found, validation_error, rate_limit_exceeded, platform_error.

SDKs

SDKs oficiais estão em desenvolvimento. Por enquanto, use qualquer cliente HTTP. A API está totalmente documentada em app.postclaw.fun/docs (especificação OpenAPI 3.1 disponível para download).