REST API

Cada objeto que declaras obtiene automáticamente un conjunto completo de endpoints REST. Cada acción se convierte en un POST. Cada flujo se convierte en un POST a /flows/.... No hay que escribir ni desplegar una capa de API aparte.

URL base: https://<your-host>/api/v1. La especificación OpenAPI está disponible en vivo en /api/v1/openapi.json.

Autenticación

ObjectOS utiliza Better Auth. Todas las rutas bajo /api/v1 requieren una sesión autenticada, salvo que estén marcadas explícitamente como públicas (consulta Formularios públicos). Los métodos de autenticación se configuran en apps/<app>/auth.config.ts — normalmente una cookie de sesión o un token bearer obtenido de /api/v1/auth/sign-in.

Los permisos se comprueban por ruta y por registro. Las rutas anotadas a continuación con una clave de permiso (p. ej. ai:chat) invocan requirePermission(...); el acceso a nivel de registro lo aplica RBAC + seguridad a nivel de fila + seguridad a nivel de campo dentro del motor de datos.

Discovery

Restringir la superficie de la API

Los endpoints autogenerados se gobiernan por objeto, de modo que puedes retirar un objeto de la API o hacerlo de solo lectura sin escribir código de rutas:

• apiEnabled (boolean, por defecto true): establécelo en false para omitir el objeto de la superficie REST por completo. Las solicitudes a sus rutas devuelven 404.
• apiMethods (lista blanca opcional): cuando se establece, solo son accesibles las operaciones listadas; cualquier otra operación se rechaza en la capa REST. Valores permitidos: get, list, create, update, delete, upsert, bulk, aggregate, history, search, restore, purge, import, export.

// Un objeto de referencia de solo lectura, nunca escribible por la API:
defineObject({
  name: 'exchange_rate',
  apiMethods: ['get', 'list'],
  // ...fields
})

// Un objeto interno que la API nunca expone:
defineObject({
  name: 'sync_cursor',
  apiEnabled: false,
  // ...fields
})

Ambos se aplican ahora en la capa REST (ADR-0049): las versiones anteriores analizaban estas propiedades pero no las aplicaban.

Datos — /api/v1/data/*

CRUD + consultas avanzadas para cada objeto que declaras. :object es el name del objeto (snake_case).

Ejemplo rápido

GET /api/v1/data/support_ticket?where={"status":{"$eq":"open"}}&orderBy=-created_at&limit=20
Authorization: Bearer <token>

{
  "items": [ { "id": "...", "subject": "...", "status": "open" } ],
  "total": 137,
  "nextCursor": "eyJpZCI6IjAxSDA..."
}

AI — /api/v1/ai/*

Los endpoints sobre los que se apoyan el AI Builder y tus agentes.

La separación entre ai:read y ai:approve es la primitiva de seguridad que hace que el AI Builder sea seguro para los usuarios finales.

Acciones — /api/v1/actions/*

Cada *.action.ts que declaras se convierte en un endpoint.

Cada acción también se expone a la IA como una herramienta action_<name> — consulta Acciones.

Flujos — /api/v1/flows/*

Metadatos — /api/v1/meta/*

Introspección de solo lectura de los metadatos del runtime en ejecución. Útil para herramientas y para la Console.

Compartición y aprobaciones

Informes y búsqueda

Formularios públicos

Las únicas rutas que son no autenticadas, habilitadas de forma opcional mediante FormView.sharing.allowAnonymous.

Utilidades

Envoltorio de errores

Toda respuesta distinta de 2xx sigue la misma forma:

{
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "Missing ai:approve on conversation 01H…",
    "details": { "permission": "ai:approve", "subject": "01H…" }
  }
}

Códigos comunes: UNAUTHENTICATED, PERMISSION_DENIED, VALIDATION_ERROR, NOT_FOUND, CONCURRENT_UPDATE, RATE_LIMITED, INTERNAL.

Versionado

/api/v1 es la API estable. Los cambios incompatibles van a /api/v2 y ambas se sirven en paralelo durante una versión menor. La versión actual y el horizonte de obsolescencia están en GET /api/v1.

Véase también

• ObjectQL — el lenguaje de consulta utilizado por /data/*
• Tipos de campo — qué formas pueden adoptar los datos
• Build → Acciones — declarar endpoints personalizados
• Seguridad — qué comprueba cada ruta antes de ejecutarse