Para developers e agentes

A API de conteúdo da StudioChat

Tudo o que está publicado em studiochat.io pode ser lido de três formas: como HTML, como markdown, e como JSON pela API abaixo. Sem API key, sem OAuth, e nada aqui escreve. Esta página é o contrato.

Começar por aqui

Um único request descreve a API completa: quais endpoints existem, onde está o documento OpenAPI, e qual é o limite de uso vigente.

curl https://studiochat.io/api/v1

Endpoints

GET	/api/v1	O que a API oferece, com o limite de uso vigente e a política de versionamento.
GET	/api/v1/pages	Todas as páginas indexadas, como um diretório de URLs. É barato: traz links, não texto.
GET	/api/v1/pages/{path}	Uma página, com o texto completo em markdown. Para a home, usar `index`.
GET	/api/v1/posts	Os posts publicados do blog, do mais novo ao mais antigo. Filtra-se com `?tag=`.
GET	/api/v1/posts/{slug}	Um post, com o corpo e o FAQ.
POST	/api/v1/batch	Até 20 leituras em um único request.
GET	/openapi.json	A descrição OpenAPI 3.1 de tudo o que está acima.

curl "https://studiochat.io/api/v1/pages/ecommerce?locale=es"
curl "https://studiochat.io/api/v1/posts?tag=soporte&limit=5"

Idiomas

Todos os endpoints aceitam `?locale=en|es|pt`, e o padrão é inglês. Um post do blog ainda sem tradução resolve para outro idioma: a resposta informa para qual locale resolveu e em quais ele existe de verdade, então um fallback nunca é apresentado como tradução.

Paginação

As listas paginam por cursor. Ler `pagination.nextCursor` e devolver como `?cursor=`. O cursor é opaco: reenvia-se, não se constrói. `limit` começa em 25 e tem teto de 100.

Leituras em lote

Um agente que monta uma resposta normalmente quer várias páginas ao mesmo tempo, e fazer um request por página é o que torna caro usar uma API. Faz-se POST de um array `operations` e volta um resultado por operação, cada um com o próprio status, então uma falha não arrasta o resto. Um lote conta como um request contra o limite de uso e aceita até 20 operações.

curl -X POST https://studiochat.io/api/v1/batch \
  -H "Content-Type: application/json" \
  -d '{"operations":[
        {"id":"home","resource":"page","path":"/"},
        {"id":"fin","resource":"page","path":"/fintech","locale":"es"}
      ]}'

Erros

Toda falha é um documento problem da RFC 9457, servido como `application/problem+json`, com um `code` estável para ramificar e um `resolution` que nomeia o próximo passo. Ramificar pelo código, não pela mensagem.

invalid_request400: Um parâmetro está errado. `detail` diz qual.
resource_not_found404: Não existe nenhuma página nem post nesse path ou slug.
method_not_allowed405: Usar GET. Só /api/v1/batch aceita POST.
rate_limit_exceeded429: Esperar os segundos indicados em `Retry-After` e tentar de novo.
content_unavailable502: A página existe e a leitura falhou do nosso lado. Tentar de novo, ou ler o HTML ou o markdown.

Limites de uso

120 requests a cada 60 segundos, por IP de origem. Toda resposta traz os campos estruturados `RateLimit-Policy` e `RateLimit` do IETF mais o trio `X-RateLimit-*` mais antigo, e um 429 acrescenta `Retry-After`. Vale ler e regular o ritmo pelos números reais em vez de estimar.

RateLimit-Policy: "content";q=120;w=60
RateLimit: "content";r=118;t=47

Versionamento e depreciação

A versão maior fica no path, começando em `/api/v1`. Dentro da v1 podem ser adicionados campos sem aviso, então ignorar o que não for reconhecido. Uma mudança incompatível recebe um novo path maior, sinalizada com os headers `Deprecation` e `Link` da RFC 9745, e um header `Sunset` com data pelo menos 90 dias antes de algo sair do ar.

Outras formas de ler o site

A API é o caminho estruturado. Estas quatro costumam dar menos trabalho, e nenhuma precisa de um request por página.

/llms.txt
O índice curado: cada página com uma linha sobre o que cobre.
/llms-full.txt
O texto de todas as páginas em um único arquivo. Com `?locale=es|pt` para os outros dois idiomas.
qualquer URL do site mais .md
Essa página em markdown, cerca de 4% dos bytes do HTML. Enviar `Accept: text/markdown` para a URL normal faz o mesmo.
/sitemap.xml
Todas as URLs indexáveis, nos três idiomas.
/.well-known/api-catalog
O catálogo da RFC 9727, que aponta para o contrato e para esta página.

Perguntas

Escrever para hey@studiochat.io e responde uma pessoa.