REST API

선언하는 모든 객체는 자동으로 완전한 REST 엔드포인트 세트를 갖게 됩니다. 모든 액션은 POST가 되고, 모든 플로우는 /flows/...로의 POST가 됩니다. 별도로 작성하거나 배포할 API 계층이 없습니다.

기본 URL: https://<your-host>/api/v1. OpenAPI 사양은 /api/v1/openapi.json에서 실시간으로 제공됩니다.

Authentication

ObjectOS는 Better Auth를 사용합니다. /api/v1 아래의 모든 라우트는 명시적으로 public으로 표시되지 않는 한 인증된 세션이 필요합니다(Public forms 참고). 인증 방식은 apps/<app>/auth.config.ts에서 구성되며, 일반적으로 세션 쿠키 또는 /api/v1/auth/sign-in에서 받은 bearer 토큰입니다.

권한은 라우트별, 레코드별로 확인됩니다. 아래에서 권한 키(예: ai:chat)가 표시된 라우트는 requirePermission(...)을 호출하며, 레코드 수준 접근은 데이터 엔진 내부의 RBAC + 행 수준 보안 + 필드 수준 보안에 의해 적용됩니다.

Discovery

Restricting the API surface

자동 생성된 엔드포인트는 객체 단위로 제어되므로, 라우트 코드를 작성하지 않고도 객체를 API에서 제외하거나 읽기 전용으로 만들 수 있습니다:

• apiEnabled (boolean, 기본값 true) — false로 설정하면 객체가 REST 표면에서 완전히 제외됩니다. 해당 라우트로의 요청은 404를 반환합니다.
• apiMethods (선택적 화이트리스트) — 설정하면 나열된 작업만 도달 가능하며, 그 외 작업은 REST 계층에서 거부됩니다. 허용 값: get, list, create, update, delete, upsert, bulk, aggregate, history, search, restore, purge, import, export.

// API로는 절대 쓸 수 없는 읽기 전용 참조 객체:
defineObject({
  name: 'exchange_rate',
  apiMethods: ['get', 'list'],
  // ...fields
})

// API가 절대 노출하지 않는 내부 객체:
defineObject({
  name: 'sync_cursor',
  apiEnabled: false,
  // ...fields
})

이 둘은 이제 REST 계층에서 강제됩니다(ADR-0049) — 이전 버전은 이 속성들을 파싱했지만 적용하지는 않았습니다.

Data — /api/v1/data/*

선언하는 모든 객체에 대한 CRUD + 고급 쿼리. :object는 객체의 name입니다(snake_case).

Quick example

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

AI Builder와 agents가 사용하는 엔드포인트입니다.

ai:read와 ai:approve의 분리는 AI Builder를 최종 사용자에게 안전하게 만드는 보안 기본 요소입니다.

Actions — /api/v1/actions/*

선언하는 모든 *.action.ts는 엔드포인트가 됩니다.

각 액션은 AI에게도 action_<name> 도구로 노출됩니다 — Actions 참고.

Flows — /api/v1/flows/*

Metadata — /api/v1/meta/*

실행 중인 런타임의 메타데이터에 대한 읽기 전용 인트로스펙션. 도구와 Console에 유용합니다.

Sharing & approvals

Reports & search

Public forms

인증되지 않은 유일한 라우트로, FormView.sharing.allowAnonymous를 통해 옵트인합니다.

Utilities

Error envelope

2xx가 아닌 모든 응답은 동일한 형태를 따릅니다:

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

일반적인 코드: UNAUTHENTICATED, PERMISSION_DENIED, VALIDATION_ERROR, NOT_FOUND, CONCURRENT_UPDATE, RATE_LIMITED, INTERNAL.

Versioning

/api/v1은 안정(stable) API입니다. 호환성을 깨는 변경 사항은 /api/v2로 가며, 두 버전은 하나의 마이너 릴리스 동안 병렬로 제공됩니다. 현재 버전과 지원 중단(deprecation) 기한은 GET /api/v1에 있습니다.

See also

• ObjectQL — /data/*가 사용하는 쿼리 언어
• Field types — 데이터가 가질 수 있는 형태
• Build → Actions — 커스텀 엔드포인트 선언
• Security — 모든 라우트가 실행 전에 확인하는 것