--- title: "Documentación para developers de StudioChat: API y OpenAPI" description: "La API pública de solo lectura de StudioChat: cada página y cada post del blog en JSON, el contrato OpenAPI 3.1, los límites de uso y la versión markdown de cada página. Sin API key." url: https://studiochat.io/es/developers locale: es translations: { en: https://studiochat.io/developers.md, pt: https://studiochat.io/pt/developers.md } site: https://studiochat.io --- Para developers y agentes # La API de contenido de StudioChat Todo lo publicado en studiochat.io se puede leer de tres formas: como HTML, como markdown, y como JSON a través de la API que sigue. Sin API key, sin OAuth, y nada de acá escribe. Esta página es el contrato. ## Empezar por acá Un solo request describe la API completa: qué endpoints existen, dónde está el documento OpenAPI, y cuál es el límite de uso vigente. curl https://studiochat.io/api/v1 ## Endpoints | GET | /api/v1 | Qué ofrece la API, con el límite de uso vigente y la política de versionado. | | ---- | -------------------- | ----------------------------------------------------------------------------------------- | | GET | /api/v1/pages | Todas las páginas indexadas, como un directorio de URLs. Es barato: trae links, no texto. | | GET | /api/v1/pages/{path} | Una página, con su texto completo en markdown. Para el home, usar \`index\`. | | GET | /api/v1/posts | Los posts publicados del blog, del más nuevo al más viejo. Se filtra con \`?tag=\`. | | GET | /api/v1/posts/{slug} | Un post, con su cuerpo y su FAQ. | | POST | /api/v1/batch | Hasta 20 lecturas en un solo request. | | GET | /openapi.json | La descripción OpenAPI 3.1 de todo lo anterior. | curl "https://studiochat.io/api/v1/pages/ecommerce?locale=es" curl "https://studiochat.io/api/v1/posts?tag=soporte&limit=5" ## Idiomas Todos los endpoints aceptan \`?locale=en|es|pt\`, y el default es inglés. Un post del blog que todavía no está traducido resuelve a otro idioma: la respuesta informa a qué locale resolvió y en cuáles existe de verdad, así un fallback nunca se presenta como traducción. ## Paginación Las listas paginan por cursor. Leer \`pagination.nextCursor\` y devolverlo como \`?cursor=\`. El cursor es opaco: se reenvía, no se construye. \`limit\` arranca en 25 y tiene tope de 100. ## Lecturas en lote Un agente que arma una respuesta suele querer varias páginas a la vez, y hacer un request por página es lo que vuelve caro usar una API. Se hace POST de un array \`operations\` y vuelve un resultado por operación, cada uno con su propio status, así una falla no arrastra al resto. Un lote cuenta como un request contra el límite de uso y admite hasta 20 operaciones. 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"} ]}' ## Errores Toda falla es un documento problem de RFC 9457, servido como \`application/problem+json\`, con un \`code\` estable para ramificar y un \`resolution\` que nombra el próximo paso. Ramificar por el código, no por el mensaje. invalid\_request 400 Un parámetro está mal. \`detail\` dice cuál. resource\_not\_found 404 No existe ninguna página ni post en ese path o slug. method\_not\_allowed 405 Usar GET. Solo /api/v1/batch acepta POST. rate\_limit\_exceeded 429 Esperar los segundos que indica \`Retry-After\` y reintentar. content\_unavailable 502 La página existe y falló la lectura de nuestro lado. Reintentar, o leer el HTML o el markdown. ## Límites de uso 120 requests por cada 60 segundos, por IP de origen. Toda respuesta trae los campos estructurados \`RateLimit-Policy\` y \`RateLimit\` del IETF más el trío \`X-RateLimit-\*\` más viejo, y un 429 agrega \`Retry-After\`. Conviene leerlos y regular el ritmo con los números reales en vez de estimar. RateLimit-Policy: "content";q=120;w=60 RateLimit: "content";r=118;t=47 ## Versionado y deprecación La versión mayor va en el path, empezando en \`/api/v1\`. Dentro de v1 se pueden agregar campos sin aviso, así que ignorar lo que no se reconozca. Un cambio incompatible recibe un path mayor nuevo, señalizado con los headers \`Deprecation\` y \`Link\` de RFC 9745, y un header \`Sunset\` con fecha al menos 90 días antes de que se dé de baja algo. ## Otras formas de leer el sitio La API es la vía estructurada. Estas cuatro suelen ser menos trabajo, y ninguna necesita un request por página. * /llms.txt El índice curado: cada página con una línea sobre qué cubre. * /llms-full.txt El texto de todas las páginas en un solo archivo. Con \`?locale=es|pt\` para los otros dos idiomas. * cualquier URL del sitio más.md Esa página en markdown, alrededor del 4% de los bytes del HTML. Mandar \`Accept: text/markdown\` a la URL normal hace lo mismo. * /sitemap.xml Todas las URLs indexables, en los tres idiomas. * /.well-known/api-catalog El catálogo de RFC 9727, que apunta al contrato y a esta página. ## Preguntas Escribir a hey@studiochat.io y contesta una persona. ## El playbook ya existe. Nosotros lo multiplicamos. [Hablemos ahora](https://cal.com/studiochat) [Agendar una demo](https://cal.com/studiochat) [O escribir a hey@studiochat.io](mailto:hey@studiochat.io)