REST API

Jedes Objekt, das du deklarierst, erhält automatisch einen vollständigen Satz von REST-Endpunkten. Jede Action wird zu einem POST. Jeder Flow wird zu einem POST auf /flows/.... Es gibt keine separate API-Schicht, die du schreiben oder bereitstellen musst.

Basis-URL: https://<your-host>/api/v1. Die OpenAPI-Spezifikation ist live unter /api/v1/openapi.json verfügbar.

Authentication

ObjectOS verwendet Better Auth. Alle Routen unter /api/v1 erfordern eine authentifizierte Sitzung, sofern sie nicht ausdrücklich als public markiert sind (siehe Public forms). Die Authentifizierungsmethoden werden in apps/<app>/auth.config.ts konfiguriert — typischerweise ein Session-Cookie oder ein Bearer-Token von /api/v1/auth/sign-in.

Berechtigungen werden pro Route, pro Datensatz geprüft. Routen, die unten mit einem Berechtigungsschlüssel (z. B. ai:chat) annotiert sind, rufen requirePermission(...) auf; der Zugriff auf Datensatzebene wird durch RBAC + Row-Level Security + Field-Level Security innerhalb der Daten-Engine durchgesetzt.

Discovery

API-Oberfläche einschränken

Die automatisch generierten Endpunkte werden pro Objekt gesteuert, sodass du ein Objekt von der API nehmen oder schreibgeschützt machen kannst, ohne Routen-Code zu schreiben:

• apiEnabled (boolean, Standard true) — auf false setzen, um das Objekt vollständig von der REST-Oberfläche auszuschließen. Anfragen an seine Routen liefern 404.
• apiMethods (optionale Whitelist) — wenn gesetzt, sind nur die aufgeführten Operationen erreichbar; jede andere Operation wird auf der REST-Ebene abgelehnt. Erlaubte Werte: get, list, create, update, delete, upsert, bulk, aggregate, history, search, restore, purge, import, export.

// Ein schreibgeschütztes Referenzobjekt, niemals über die API beschreibbar:
defineObject({
  name: 'exchange_rate',
  apiMethods: ['get', 'list'],
  // ...fields
})

// Ein internes Objekt, das die API niemals offenlegt:
defineObject({
  name: 'sync_cursor',
  apiEnabled: false,
  // ...fields
})

Beide werden jetzt auf der REST-Ebene durchgesetzt (ADR-0049) — frühere Versionen parsten diese Eigenschaften, wendeten sie aber nicht an.

Data — /api/v1/data/*

CRUD + erweiterte Abfragen für jedes Objekt, das du deklarierst. :object ist der name des Objekts (snake_case).

Kurzes Beispiel

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/*

Die Endpunkte, auf denen der AI Builder und deine Agenten aufsetzen.

Die Trennung zwischen ai:read und ai:approve ist das Sicherheitsprimitiv, das den AI Builder für Endbenutzer sicher macht.

Actions — /api/v1/actions/*

Jede *.action.ts, die du deklarierst, wird zu einem Endpunkt.

Jede Action wird der KI außerdem als action_<name>-Tool bereitgestellt — siehe Actions.

Flows — /api/v1/flows/*

Metadata — /api/v1/meta/*

Schreibgeschützte Introspektion der Metadaten des laufenden Runtime. Nützlich für Tooling und die Console.

Sharing & Freigaben

Reports & Suche

Public forms

Die einzigen Routen, die unauthentifiziert sind, per Opt-in über FormView.sharing.allowAnonymous.

Utilities

Fehler-Envelope

Jede Antwort, die nicht 2xx ist, folgt derselben Struktur:

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

Häufige Codes: UNAUTHENTICATED, PERMISSION_DENIED, VALIDATION_ERROR, NOT_FOUND, CONCURRENT_UPDATE, RATE_LIMITED, INTERNAL.

Versionierung

/api/v1 ist die stabile API. Breaking Changes gehen nach /api/v2, und beide werden für ein Minor-Release parallel bereitgestellt. Die aktuelle Version und der Deprecation-Horizont stehen in GET /api/v1.

Siehe auch

• ObjectQL — die von /data/* verwendete Abfragesprache
• Field types — welche Formen Daten annehmen können
• Build → Actions — eigene Endpunkte deklarieren
• Security — was jede Route prüft, bevor sie ausgeführt wird