API reference

HTTP API for app sessions.

The SDK wraps these endpoints. Use them directly only when you need to build your own client. All non-public endpoints require a bearer token.

Base URL

Local development: http://127.0.0.1:3001/v1. In Docker, the web and admin containers proxy /v1 to the API.

Authentication

HeaderUse
Authorization: Bearer <token>Short-lived session token for records and projects.
X-Iavica-Link-Secret: <secret>Polling and redeeming a magic-link request from the app.
X-Iavica-Dev-Token: <token>Development-only bootstrap (/v1/dev/bootstrap).
EndpointPurpose
POST /v1/link-requestsCreate a request and email the link. Body: { appId, appName?, email }.
GET /v1/link-requests/:id/statusPoll with the link secret. Returns pending, approved, denied or expired.
POST /v1/link-requests/:id/redeemExchange the approved request for a session and device token. Body: { projectId?, createOwnProject?, appName? }.
GET /v1/public/link-requests?token=...Load the authorization page data.
POST /v1/public/link-requests/approveApprove with an explicit POST. Body: { token }.
POST /v1/public/link-requests/denyDeny with an explicit POST. Body: { token }.
curl -X POST http://127.0.0.1:3001/v1/link-requests \
  -H 'Content-Type: application/json' \
  -d '{"appId":"YOUR_APP_ID","email":"you@example.com"}'

If the user belongs to several projects for the same app, redeem returns { status: "selection_required", projects: [...] }. Call it again with the chosen projectId, or with createOwnProject: true.

Sessions

EndpointPurpose
POST /v1/sessions/refreshRenew a short session from a device token. Body: { deviceToken }.
POST /v1/sessions/disconnectRevoke a device token (logout). Body: { deviceToken }.

Records

All record routes require a valid session and membership in the project.

MethodPath
GET/v1/apps/:appId/collections/:collection/records?limit=&cursor=
POST/v1/apps/:appId/collections/:collection/records — body: { data }
GET/v1/apps/:appId/collections/:collection/records/:id
PATCH/v1/apps/:appId/collections/:collection/records/:id — requires If-Match: <version>
DELETE/v1/apps/:appId/collections/:collection/records/:id — requires If-Match: <version>

A record returns { id, data, version, createdAt, updatedAt }. Updates and deletes with a stale version return 409 VERSION_CONFLICT and the current version.

Projects

MethodPathPermission
GET/v1/apps/:appId/projects/:projectId/membersmember
POST/v1/apps/:appId/projects/:projectId/invitationsowner
DELETE/v1/apps/:appId/projects/:projectId/members/:userIdowner
DELETE/v1/apps/:appId/projects/:projectIdowner
GET/v1/apps/:appId/projects/:projectId/exportmember

Invitations create an email link. Editors can read, write and export; only owners invite, revoke or delete.

Invitations

EndpointPurpose
GET /v1/public/invitations?token=...Read the invitation (email, role, project).
POST /v1/public/invitations/acceptAccept. Body: { token }.
POST /v1/public/invitations/denyDeny. Body: { token }.

Telemetry

POST /v1/telemetry/app-open — body: { appId, visitorId, event: "opened" | "connected" }. The SDK calls it automatically; it is rate-limited and best-effort.

Errors

CodeHTTPMeaning
AUTH_REQUIRED401Missing or invalid token.
SESSION_EXPIRED401Session expired or revoked.
ACCESS_DENIED403Not a member, blocked entity or insufficient role.
LINK_EXPIRED410Magic link or invitation expired/used.
VERSION_CONFLICT409Stale record version; refresh and retry.
VALIDATION_ERROR400Invalid payload or missing fields.
RATE_LIMITED429Too many requests; back off.
QUOTA_EXCEEDED429Project or storage limit reached.
NOT_FOUND404Resource not found.

Error shape: { error: { code, message, requestId, details? } }.