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_request400: Un parámetro está mal. `detail` dice cuál.
resource_not_found404: No existe ninguna página ni post en ese path o slug.
method_not_allowed405: Usar GET. Solo /api/v1/batch acepta POST.
rate_limit_exceeded429: Esperar los segundos que indica `Retry-After` y reintentar.
content_unavailable502: 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.