OptioAIDocumentação
API de Conteúdo · v1

Integre agentes ao
Blog da OptioAI.

Crie, consulte, edite e exclua rascunhos com uma API simples. A publicação continua sob controle humano no painel.

Começar integração Base URLhttps://optioai.net/api/cms/posts
Visão geral

Primeiros passos

A API foi feita para integrações e agentes que produzem conteúdo. Toda criação começa como rascunho e fica vinculada à chave que a criou.

1
Gere uma chave

No painel administrativo, abra Blog → Integrações.

2
Guarde o token

A chave completa é exibida uma única vez.

3
Envie o conteúdo

Use HTML ou declare Markdown explicitamente.

Segurança

Autenticação

Envie a chave no cabeçalho Authorization de todas as requisições. Nunca coloque o token na URL ou no conteúdo do post.

Cabeçalho HTTP
Authorization: Bearer SUA_CHAVE

Permissões

draft:createCria rascunhosdraft:readLista e consultadraft:updateEdita rascunhosdraft:deleteExclui rascunhos
Referência

Endpoints

POST /api/cms/postsCriar rascunhoGET /api/cms/postsListar rascunhosGET /api/cms/posts/{id}Consultar rascunhoPATCH /api/cms/posts/{id}Editar traduçãoDELETE /api/cms/posts/{id}Excluir rascunho

Compatibilidade: POST /api/cms/drafts continua disponível como alias legado para criação. Novas integrações devem usar /api/cms/posts.

POST/api/cms/posts

Criar rascunho

Scope draft:create

Cria um post em estado draft e adiciona sua primeira tradução.

Corpo da requisição

CampoTipoObrigatórioPadrãoDescrição
localestringNãoptIdioma da tradução: pt, en ou es.
titlestringSim—Título entre 3 e 180 caracteres.
slugstringNãoGeradoIdentificador na URL, único por idioma. Máximo de 110 caracteres.
excerptstringNão""Resumo do post. Máximo de 360 caracteres.
content_formatstringNãohtmlFormato de content: html ou markdown.
contentstringSim—Corpo do post com pelo menos 20 caracteres.
seo_titlestringNãonullTítulo para buscadores. Máximo de 180 caracteres.
seo_descriptionstringNãonullDescrição para buscadores. Máximo de 360 caracteres.
cover_image_urlstringNãonullURL HTTP ou HTTPS da imagem de capa.
cURL
curl -X POST https://optioai.net/api/cms/posts \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "locale": "pt",
    "title": "Como agentes locais protegem seus dados",
    "slug": "agentes-locais-e-privacidade",
    "excerpt": "Entenda por que executar agentes localmente reduz riscos.",
    "content_format": "html",
    "content": "<h2>Seus dados ficam com você</h2><p>O processamento local reduz a exposição de informações sensíveis.</p>",
    "seo_title": "Agentes locais e privacidade",
    "seo_description": "Como agentes locais ajudam a manter seus dados sob controle."
  }'
Resposta · 201 Created
{
  "id": "8f352848-3ef5-4f07-9608-d4f45687fd48",
  "status": "draft",
  "locale": "pt",
  "title": "Como agentes locais protegem seus dados",
  "slug": "agentes-locais-e-privacidade",
  "excerpt": "Entenda por que executar agentes localmente reduz riscos.",
  "content": "<h2>Seus dados ficam com você</h2><p>O processamento local reduz a exposição de informações sensíveis.</p>",
  "content_format": "html",
  "seo_title": "Agentes locais e privacidade",
  "seo_description": "Como agentes locais ajudam a manter seus dados sob controle.",
  "cover_image_url": null,
  "available_locales": ["pt"],
  "created_at": "2026-09-11T14:30:00.000Z",
  "updated_at": "2026-09-11T14:30:00.000Z"
}
GET/api/cms/posts

Listar rascunhos

Scope draft:read

Retorna somente os rascunhos criados pela chave atual, do mais recente para o mais antigo.

limitQuantidade de itens por página.offsetQuantidade de itens a ignorar.localeFiltra por pt, en ou es.
cURL
curl "https://optioai.net/api/cms/posts?limit=20&offset=0&locale=pt" \
  -H "Authorization: Bearer SUA_CHAVE"
Resposta · 200 OK
{
  "data": [
    {
      "id": "8f352848-3ef5-4f07-9608-d4f45687fd48",
      "status": "draft",
      "locale": "pt",
      "title": "Como agentes locais protegem seus dados",
      "slug": "agentes-locais-e-privacidade",
      "excerpt": "Entenda por que executar agentes localmente reduz riscos.",
      "content": "<h2>Seus dados ficam com você</h2><p>O processamento local reduz a exposição de informações sensíveis.</p>",
      "content_format": "html",
      "seo_title": "Agentes locais e privacidade",
      "seo_description": "Como agentes locais ajudam a manter seus dados sob controle.",
      "cover_image_url": null,
      "available_locales": ["pt"],
      "created_at": "2026-09-11T14:30:00.000Z",
      "updated_at": "2026-09-11T14:30:00.000Z"
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 1 }
}
GET/api/cms/posts/{id}

Consultar rascunho

Scope draft:read

Retorna um rascunho específico pertencente à integração. Use ?locale=pt para selecionar a tradução; sem o parâmetro, a API prioriza português.

cURL
curl "https://optioai.net/api/cms/posts/8f352848-3ef5-4f07-9608-d4f45687fd48?locale=pt" \
  -H "Authorization: Bearer SUA_CHAVE"
PATCH/api/cms/posts/{id}

Editar rascunho

Scope draft:update

Atualiza a tradução indicada por locale. Envie apenas os campos que deseja alterar; a operação nunca muda o status para publicado.

cURL
curl -X PATCH "https://optioai.net/api/cms/posts/8f352848-3ef5-4f07-9608-d4f45687fd48?locale=pt" \
  -H "Authorization: Bearer SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{
    "locale": "pt",
    "title": "Novo título do post",
    "content_format": "html",
    "content": "<h2>Conteúdo revisado</h2><p>Nova versão do rascunho.</p>",
    "expected_updated_at": "2026-09-11T14:30:00.000Z"
  }'
DELETE/api/cms/posts/{id}

Excluir rascunho

Scope draft:delete

Exclui permanentemente o rascunho e suas traduções. A operação não aceita posts já publicados.

cURL
curl -X DELETE https://optioai.net/api/cms/posts/8f352848-3ef5-4f07-9608-d4f45687fd48 \
  -H "Authorization: Bearer SUA_CHAVE"
Resposta · 200 OK
{
  "id": "8f352848-3ef5-4f07-9608-d4f45687fd48",
  "deleted": true
}
Conteúdo

HTML ou Markdown

HTML é o formato padrão e recomendado. Ele oferece controle previsível sobre títulos, parágrafos, listas, links e destaques.

Recomendado

HTML

Use content_format: "html" ou omita o campo.

<h2>Título</h2><p>Texto...</p>
Conversão automática

Markdown

Use content_format: "markdown". A API converte o conteúdo para HTML antes de salvar.

## Título Texto com **destaque**
JSON com Markdown
{
  "locale": "pt",
  "title": "Título do post",
  "content_format": "markdown",
  "content": "## Primeira seção\n\nTexto com **destaque** e uma lista:\n\n- Item um\n- Item dois"
}
Referência

Erros

Erros usam códigos HTTP convencionais e retornam uma mensagem legível no campo error.

400Requisição inválida

JSON malformado, campo inválido ou conteúdo fora dos limites.

401Não autenticado

Bearer ausente, chave inválida, revogada ou expirada.

403Sem permissão

A chave não possui o scope exigido pela operação.

404Não encontrado

Rascunho inexistente, já publicado ou pertencente a outra chave.

409Conflito

Slug duplicado ou rascunho alterado depois da última leitura.

500Erro interno

Não foi possível concluir a operação.

Exemplo de erro
{
  "error": {
    "code": "insufficient_scope",
    "message": "A chave não possui o escopo draft:update.",
    "details": { "required_scope": "draft:update" }
  }
}
Controle editorial

Publicação só pelo painel

A API não publica, despublica nem altera posts publicados. Revise a prévia, conteúdo, imagem e SEO no painel administrativo antes de publicar.