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 ouBearer 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:
| Rota | Site | Chaves | Cache |
|---|---|---|---|
/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_ALLOWED | Pública, guardada na borda do Cloudflare e purgada quando o post muda |
/public/v1/… | O da chave | Secreta ou publicável | private, 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étodo | Caminho | O que faz |
|---|---|---|
GET | /posts | Lista os posts publicados, paginados. |
GET | /posts/:slug | Um 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
ETageCache-Control: revalide comIf-None-Matche receba304.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"