API reference

This page explains where the API contract comes from and which endpoints matter for the GitHub web landing deploy flow. The canonical source is ../cloud-api/docs/api-reference.md; lifecycle details for web apps come from ../cloud-api/docs/app/web-app-flow.md.

Source of truth

No OpenAPI generation is assumed in this docs slice. Treat the cloud-api Markdown API reference as the source until a verified OpenAPI artifact exists.

Base URL

https://api.septiembre.ai

Authentication

Use the Cognito ID token as the bearer token:

Authorization: Bearer <cognito-id-token>

The API reads the email claim from the Cognito ID token. Do not substitute the access token when calling Septiembre API endpoints.

Web landing endpoints

Step	Endpoint	Why it matters
Create app	POST /api/v1/orgs/{orgID}/projects/{projectID}/apps	Stores the web app, GitHub repository, branch, build command, output directory, region, generated subdomain value, and production environment.
Update app	PATCH /api/v1/orgs/{orgID}/projects/{projectID}/apps/{appID}	Changes app metadata such as GitHub repo, branch, build command, or output directory.
Manage env	PUT /api/v1/orgs/{orgID}/projects/{projectID}/apps/{appID}/env	Replaces app-level environment variables.
Read environments	GET /api/v1/orgs/{orgID}/projects/{projectID}/apps/{appID}/environments	Finds the production environment created with the app.
Deploy	POST /api/v1/orgs/{orgID}/projects/{projectID}/apps/{appID}/deployments	Starts the build/deploy flow. For web apps, no release tag is needed.
List deployments	GET /api/v1/orgs/{orgID}/projects/{projectID}/apps/{appID}/deployments	Shows recent deployment status.
Read failure	GET /api/v1/orgs/{orgID}/projects/{projectID}/apps/{appID}/deployments/{deployID}/failure	Gives structured failure information after a failed deploy.

Lifecycle note for web apps

For user-facing docs, use the lifecycle from web-app-flow.md: web app creation stores database and GitHub configuration. The first successful deploy builds the repository, syncs the static output to S3, and activates/materializes the live DNS/CDN infrastructure. Later deploys rebuild, sync to S3, and invalidate CDN cache.

If an API reference table appears to imply live web infrastructure is complete at app creation time, prefer the lifecycle document for the web landing guide. That distinction matters for non-technical users: they should not expect the public URL to work before the first successful deploy.

Agent instruction

Read the Septiembre API reference from ../cloud-api/docs/api-reference.md.
Read web lifecycle behavior from ../cloud-api/docs/app/web-app-flow.md.
Use the Cognito ID token for Authorization.
Do not claim OpenAPI generation exists unless a verified artifact is present.
When documenting web landings, state that live DNS/CDN appears after the first successful deploy.