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
| Header | Use |
|---|---|
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). |
Magic link
| Endpoint | Purpose |
|---|---|
POST /v1/link-requests | Create a request and email the link. Body: { appId, appName?, email }. |
GET /v1/link-requests/:id/status | Poll with the link secret. Returns pending, approved, denied or expired. |
POST /v1/link-requests/:id/redeem | Exchange 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/approve | Approve with an explicit POST. Body: { token }. |
POST /v1/public/link-requests/deny | Deny 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
| Endpoint | Purpose |
|---|---|
POST /v1/sessions/refresh | Renew a short session from a device token. Body: { deviceToken }. |
POST /v1/sessions/disconnect | Revoke a device token (logout). Body: { deviceToken }. |
Records
All record routes require a valid session and membership in the project.
| Method | Path |
|---|---|
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
| Method | Path | Permission |
|---|---|---|
GET | /v1/apps/:appId/projects/:projectId/members | member |
POST | /v1/apps/:appId/projects/:projectId/invitations | owner |
DELETE | /v1/apps/:appId/projects/:projectId/members/:userId | owner |
DELETE | /v1/apps/:appId/projects/:projectId | owner |
GET | /v1/apps/:appId/projects/:projectId/export | member |
Invitations create an email link. Editors can read, write and export; only owners invite, revoke or delete.
Invitations
| Endpoint | Purpose |
|---|---|
GET /v1/public/invitations?token=... | Read the invitation (email, role, project). |
POST /v1/public/invitations/accept | Accept. Body: { token }. |
POST /v1/public/invitations/deny | Deny. 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
| Code | HTTP | Meaning |
|---|---|---|
AUTH_REQUIRED | 401 | Missing or invalid token. |
SESSION_EXPIRED | 401 | Session expired or revoked. |
ACCESS_DENIED | 403 | Not a member, blocked entity or insufficient role. |
LINK_EXPIRED | 410 | Magic link or invitation expired/used. |
VERSION_CONFLICT | 409 | Stale record version; refresh and retry. |
VALIDATION_ERROR | 400 | Invalid payload or missing fields. |
RATE_LIMITED | 429 | Too many requests; back off. |
QUOTA_EXCEEDED | 429 | Project or storage limit reached. |
NOT_FOUND | 404 | Resource not found. |
Error shape: { error: { code, message, requestId, details? } }.