API HTTP

La interfaz web y el CLI usan esta API, y no hay nada que solo pueda hacerse desde el navegador. Esta página es la referencia: autenticación, convenciones y la lista de rutas por área. El comportamiento de cada operación se explica en su guía.

Autenticación

Un token tiene los mismos derechos que la sesión de su dueño; lo que cambia es cómo se retira: revocar un token no cierra la sesión del navegador, ni al revés. Se emite con fundaia login o desde Línea de comandos en la interfaz.

Toda ruta exige credencial salvo unas pocas públicas: la documentación (/llms.txt, /docs/…, /agent.md), GET /api/version, GET /api/infra/plans, las novedades (GET /api/infra/changelog y su canal Atom), /robots.txt, /sitemap.xml y /site.webmanifest, los webhooks de GitHub y Stripe (que se verifican por firma) y el inicio del login del CLI.

Convenciones

• Dos identificadores de servicio. serviceEnvironmentId es un servicio en un entorno y es el que usan casi todas las rutas. serviceId es el servicio a secas y solo lo usan la posición en el lienzo, el nombre y el borrado. Confundirlos da 404.
• **PATCH es parcial**: una clave ausente se deja como estaba.
• Un despliegue es asíncrono. POST …/deploy responde 202; el progreso está en GET /api/infra/deployments/:id, en el campo pipeline, y termina cuando finished es true.
• Crear un servicio lo despliega; "deployNow": false lo evita.
• Un recurso de otro espacio responde 404, igual que uno que no existe.
• El entorno va en la consulta. Las lecturas de proyecto (servicios, lienzo, salud, manifiesto, auditoría de variables, búsqueda en registros) aceptan ?environment= con el id, el slug o el nombre de uno de sus entornos; sin él, el entorno por defecto. Uno que no es del proyecto responde

1. Un serviceEnvironmentId ya dice en qué entorno está.

Errores

{ "error": "conflict", "message": "This project already has a service called \"api\"" }

message es para una persona y puede cambiar de redacción. error es el código sobre el que programar: validation_failed, not_found, conflict, forbidden, unauthorized, rate_limited, external_service_failed y deploy_frozen (423: el entorno está congelado; force: true en el cuerpo o ?force=true lo hace igualmente).

El pipeline

{
  "pipeline": {
    "currentStageId": "build",
    "finished": false,
    "succeeded": false,
    "stages": [
      { "id": "queue", "label": "En cola", "state": "done", "startedAt": "…", "finishedAt": "…" },
      { "id": "build", "label": "Construyendo la imagen", "state": "running" }
    ]
  }
}

Etapas: queue, checkout, build, start, health, live. Estados: pending, running, skipped, done, failed, cancelled.

Versión

GET /api/version es público y dice qué está corriendo, para comprobar la compatibilidad antes de autenticarse:

{ "platform": "0.1.0", "revision": null, "modules": { "infrastructure": "0.1.0" } }

Rutas

Todas bajo /api/infra. :service es un serviceEnvironmentId salvo donde se indica.

Proyectos y espacios

Servicios

Crear un servicio:

{
  "name": "api",
  "sourceKind": "github",
  "repoFullName": "owner/api",
  "branch": "main",
  "rootDirectory": "apps/api",
  "connectTo": ["sve_..."]
}

sourceKind es github, image (con image), template (con templateKey) o upload. environmentId (id, slug o nombre) dice en qué entorno se crea; sin él, en el por defecto.

Crear un entorno responde 201 con lo que pasó con cada servicio:

{
  "environment": { "id": "env_...", "name": "staging", "slug": "staging", "isDefault": false, "serviceCount": 2 },
  "copiedFrom": { "id": "env_...", "name": "production", "slug": "production", "isDefault": true },
  "services": [
    { "name": "Postgres", "status": "deploying", "reason": null, "volumes": ["/var/lib/postgresql/data"], "host": null, "notes": [] },
    { "name": "api", "status": "deploying", "reason": null, "volumes": [], "host": "tienda-api--staging.fundaia.com", "notes": [] }
  ],
  "variables": { "copied": ["REGION"], "skipped": [] }
}

status es deploying, copied (está, sin arrancar; reason dice por qué) o skipped (no se copió; reason dice por qué).

Despliegues

Variables, conexiones y dominios

Volúmenes, copias y datos

Registros, métricas e incidencias

Diagnóstico

El canal de un despliegue lleva sus líneas de registro; el global (/stream) solo cambios de estado, para no necesitar una conexión por servicio.

Workflows

Foro

Búsqueda y asistente

Novedades

Facturación