Postream

Carregando o índice…

Documentação: Visão geral da API

Visão geral da API

Uma API REST somente leitura para cada site buscar os próprios posts publicados.

A API pública entrega os posts publicados de um site. Cada chave pertence a um site e só enxerga os posts dele.

  • Base: https://<api>/public/v1 (em desenvolvimento, http://localhost:4060/public/v1).
  • Autenticação: Authorization: Bearer sk_... no servidor ou Bearer pk_... no navegador. Veja Autenticação.
  • Formato: JSON. Erros sempre como { "statusCode": 404, "code": "NOT_FOUND" }, com códigos estáveis.

Duas rotas

Cada endpoint existe em duas rotas, com o mesmo conteúdo:

RotaSiteChavesCache
/public/v1/sites/{siteId}/…Na URL (o siteId aparece no painel, em API pública)Só secreta; a publicável recebe 403 KEY_KIND_NOT_ALLOWEDPública, guardada na borda do Cloudflare e purgada quando o post muda
/public/v1/…O da chaveSecreta ou publicávelprivate, no-cache: só o blog e o navegador guardam

Recomendado: a rota por site, chamada do servidor do blog com a chave secreta. Uma chave de outro site nessa rota responde 404 NOT_FOUND. Veja Cache.

Endpoints

MétodoCaminhoO que faz
GET/postsLista os posts publicados, paginados.
GET/posts/:slugUm post com o corpo, por slug.

Também há /authors, /authors/:slug, /categories, /site e /sitemap, usados pelo kit de SEO.

O que aparece

Só versões de post com status publicado, data de publicação já passada e slug definido. Um post agendado aparece sozinho quando chega a hora; um despublicado some na hora.

Em todas as respostas

  • ETag e Cache-Control: revalide com If-None-Match e receba 304.
  • RateLimit-* na rota pela chave: quantas requisições restam na janela.
  • CORS só na rota pela chave, para os domínios permitidos do site.

Primeiro teste

curl -H "Authorization: Bearer $POSTREAM_API_KEY" \
  "https://api.postream.blog/public/v1/sites/$POSTREAM_SITE_ID/posts?perPage=5"