--- title: "Documentação para developers da StudioChat: API e OpenAPI" description: "A API pública somente de leitura da StudioChat: cada página e cada post do blog em JSON, o contrato OpenAPI 3.1, os limites de uso e a versão markdown de cada página. Sem API key." url: https://studiochat.io/pt/developers locale: pt translations: { en: https://studiochat.io/developers.md, es: https://studiochat.io/es/developers.md } site: https://studiochat.io --- 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\_request 400 Um parâmetro está errado. \`detail\` diz qual. resource\_not\_found 404 Não existe nenhuma página nem post nesse path ou slug. method\_not\_allowed 405 Usar GET. Só /api/v1/batch aceita POST. rate\_limit\_exceeded 429 Esperar os segundos indicados em \`Retry-After\` e tentar de novo. content\_unavailable 502 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. ## O playbook já existe. Nós multiplicamos. [Fale conosco agora](https://cal.com/studiochat) [Agendar uma demonstração](https://cal.com/studiochat) [Ou escrever para hey@studiochat.io](mailto:hey@studiochat.io)