Referencia de API

Esta página explica de dónde sale el contrato de API y qué endpoints importan para el flujo de deploy de una landing web desde GitHub. La fuente canónica es ../cloud-api/docs/api-reference.md; los detalles del ciclo de vida de apps web vienen de ../cloud-api/docs/app/web-app-flow.md.

Fuente de verdad

No se asume generación de OpenAPI en este corte de documentación. Trata la referencia Markdown de cloud-api como fuente hasta que exista un artefacto OpenAPI verificado.

URL base

https://api.septiembre.ai

Autenticación

Usa el ID token de Cognito como bearer token:

Authorization: Bearer <cognito-id-token>

La API lee el claim email del ID token de Cognito. No reemplaces ese token por el access token al llamar endpoints de la API de Septiembre.

Endpoints de landing web

Paso	Endpoint	Por qué importa
Crear app	POST /api/v1/orgs/{orgID}/projects/{projectID}/apps	Guarda la app web, repositorio GitHub, rama, comando de build, directorio de salida, región, subdominio generado y ambiente de producción.
Actualizar app	PATCH /api/v1/orgs/{orgID}/projects/{projectID}/apps/{appID}	Cambia metadatos como repositorio GitHub, rama, comando de build o directorio de salida.
Gestionar env	PUT /api/v1/orgs/{orgID}/projects/{projectID}/apps/{appID}/env	Reemplaza variables de entorno a nivel app.
Leer ambientes	GET /api/v1/orgs/{orgID}/projects/{projectID}/apps/{appID}/environments	Encuentra el ambiente de producción creado con la app.
Desplegar	POST /api/v1/orgs/{orgID}/projects/{projectID}/apps/{appID}/deployments	Inicia el flujo de build/deploy. Para apps web no hace falta release tag.
Listar deploys	GET /api/v1/orgs/{orgID}/projects/{projectID}/apps/{appID}/deployments	Muestra el estado de deploys recientes.
Leer falla	GET /api/v1/orgs/{orgID}/projects/{projectID}/apps/{appID}/deployments/{deployID}/failure	Devuelve información estructurada después de un deploy fallido.

Nota de ciclo de vida para apps web

Para documentación orientada a usuarios, usa el ciclo de vida de web-app-flow.md: la creación de la app web guarda configuración de base de datos y GitHub. El primer deploy exitoso construye el repositorio, sincroniza la salida estática con S3 y activa/materializa la infraestructura DNS/CDN en vivo. Los deploys posteriores reconstruyen, sincronizan con S3 e invalidan la caché del CDN.

Si una tabla de referencia de API parece sugerir que la infraestructura web en vivo queda completa al crear la app, prioriza el documento de ciclo de vida para la guía de landing web. Esa diferencia importa para usuarios no técnicos: no deberían esperar que la URL pública funcione antes del primer deploy exitoso.

Instrucción para agentes

Lee la referencia de API de Septiembre desde ../cloud-api/docs/api-reference.md.
Lee el ciclo de vida web desde ../cloud-api/docs/app/web-app-flow.md.
Usa el ID token de Cognito para Authorization.
No afirmes que existe generación OpenAPI salvo que haya un artefacto verificado.
Cuando documentes landings web, indica que el DNS/CDN en vivo aparece después del primer deploy exitoso.