# Endpoint Reference

Every path the Sovrium REST API serves. The authentication model, error envelope and cross-cutting behaviours that govern all of them are in the [REST API Overview](/en/docs/api-reference).

## Health

Unauthenticated server health check.

| Method | Path          | Description         |
| ------ | ------------- | ------------------- |
| `GET`  | `/api/health` | Check server status |

## Tables

Read table definitions, and manage outgoing table webhooks.

| Method | Path                                                      | Description           |
| ------ | --------------------------------------------------------- | --------------------- |
| `GET`  | `/api/tables`                                             | List all tables       |
| `GET`  | `/api/tables/{tableId}`                                   | Get table by ID       |
| `GET`  | `/api/tables/{tableId}/permissions`                       | Get table permissions |
| `GET`  | `/api/tables/{tableId}/export`                            | Export records as CSV |
| `GET`  | `/api/tables/{tableId}/webhooks`                          | List table webhooks   |
| `POST` | `/api/tables/{tableId}/webhooks/{webhookName}/test`       | Send a test delivery  |
| `GET`  | `/api/tables/{tableId}/webhooks/{webhookName}/deliveries` | List deliveries       |
| `GET`  | `.../deliveries/{deliveryId}`                             | Get one delivery      |
| `POST` | `.../deliveries/{deliveryId}/retry`                       | Retry a delivery      |

## Records

Full CRUD, batch operations, soft-delete lifecycle, revision history, comments and realtime. See [Records Overview](/en/docs/records-overview) for the data model.

### CRUD

| Method   | Path                                       | Description      |
| -------- | ------------------------------------------ | ---------------- |
| `GET`    | `/api/tables/{tableId}/records`            | List records     |
| `POST`   | `/api/tables/{tableId}/records`            | Create a record  |
| `GET`    | `/api/tables/{tableId}/records/{recordId}` | Get record by ID |
| `PATCH`  | `/api/tables/{tableId}/records/{recordId}` | Update a record  |
| `DELETE` | `/api/tables/{tableId}/records/{recordId}` | Delete a record  |

`DELETE` soft-deletes by default; `?permanent=true` (admin only) and `?purge=true` hard-delete on the same route. Two form-post equivalents exist for HTML forms: `POST .../records/{recordId}/update` and `POST .../records/{recordId}/delete`.

### Batch operations

| Method   | Path                                          | Description                          |
| -------- | --------------------------------------------- | ------------------------------------ |
| `POST`   | `/api/tables/{tableId}/records/batch`         | Create multiple records (1–1000)     |
| `PATCH`  | `/api/tables/{tableId}/records/batch`         | Update multiple records (1–100)      |
| `DELETE` | `/api/tables/{tableId}/records/batch`         | Soft-delete multiple records (1–100) |
| `POST`   | `/api/tables/{tableId}/records/batch/delete`  | Soft-delete, alternate verb          |
| `POST`   | `/api/tables/{tableId}/records/batch/restore` | Restore multiple records (1–100)     |
| `POST`   | `/api/tables/{tableId}/records/upsert`        | Create or update records (1–100)     |

`POST .../records/batch-delete` is retained as a legacy alias, and `POST .../records/bulk-delete` / `bulk-update` back HTML form submissions.

### Trash & history

| Method | Path                                               | Description                 |
| ------ | -------------------------------------------------- | --------------------------- |
| `GET`  | `/api/tables/{tableId}/trash`                      | List trashed records        |
| `POST` | `/api/tables/{tableId}/records/{recordId}/restore` | Restore a deleted record    |
| `GET`  | `/api/tables/{tableId}/records/{recordId}/history` | Get record revision history |

### Comments

| Method   | Path                                                     | Description               |
| -------- | -------------------------------------------------------- | ------------------------- |
| `GET`    | `/api/tables/{tableId}/records/{recordId}/comments`      | List comments on a record |
| `POST`   | `/api/tables/{tableId}/records/{recordId}/comments`      | Add a comment             |
| `POST`   | `/api/tables/{tableId}/records/{recordId}/comments/read` | Mark comments read        |
| `GET`    | `.../{recordId}/comments/{commentId}`                    | Get comment by ID         |
| `PATCH`  | `.../{recordId}/comments/{commentId}`                    | Update a comment          |
| `DELETE` | `.../{recordId}/comments/{commentId}`                    | Delete a comment          |

### Realtime

| Method | Path                                  | Description                  |
| ------ | ------------------------------------- | ---------------------------- |
| `GET`  | `/api/tables/{tableId}/subscribe`     | Subscribe to record changes  |
| `GET`  | `/api/tables/{tableId}/subscribe/sse` | Server-sent events stream    |
| `GET`  | `/api/realtime/presence`              | Current presence information |

## Views

Pre-configured views that filter, sort and group records from a table.

| Method | Path                                           | Description                |
| ------ | ---------------------------------------------- | -------------------------- |
| `GET`  | `/api/tables/{tableId}/views`                  | List views for a table     |
| `GET`  | `/api/tables/{tableId}/views/{viewId}`         | Get view by ID             |
| `GET`  | `/api/tables/{tableId}/views/{viewId}/records` | Get records through a view |

Unlike `?view=` on the records list, this endpoint applies the view's **full** configuration including its field selection and grouping — see [Grouping & Saved Views](/en/docs/records-grouping-views).

## Activity

Audit log of data changes across all tables.

| Method | Path                         | Description           |
| ------ | ---------------------------- | --------------------- |
| `GET`  | `/api/activity`              | List activity entries |
| `GET`  | `/api/activity/{activityId}` | Get activity detail   |

## Analytics

Privacy-friendly, cookie-free usage analytics.

| Method | Path                       | Description               |
| ------ | -------------------------- | ------------------------- |
| `POST` | `/api/analytics/collect`   | Collect a page view event |
| `GET`  | `/api/analytics/overview`  | Get analytics overview    |
| `GET`  | `/api/analytics/pages`     | Get top pages             |
| `GET`  | `/api/analytics/referrers` | Get top referrers         |
| `GET`  | `/api/analytics/devices`   | Get device breakdown      |
| `GET`  | `/api/analytics/campaigns` | Get campaign stats        |
| `GET`  | `/api/analytics/events`    | Get custom events         |

## Authentication

Authentication is handled by Better Auth and mounted at `/api/auth/*` — email/password, social OAuth, sessions, password reset, email verification, two-factor, magic links, email OTP, organizations, and admin user management. See [Authentication Overview](/en/docs/auth-overview) for setup.

A few routes are served directly rather than by Better Auth:

| Method  | Path                                     | Description                       |
| ------- | ---------------------------------------- | --------------------------------- |
| `PATCH` | `/api/auth/user/update`                  | Update the current user's profile |
| `POST`  | `/api/auth/session/refresh`              | Refresh the active session        |
| `PATCH` | `/api/auth/admin/users/{id}`             | Admin-update a user               |
| `GET`   | `/api/auth/organization/list-teams`      | List teams in an organization     |
| `POST`  | `/api/auth/organization/add-team-member` | Add a member to a team            |

Admins can browse the full machine-readable surface at `/api/scalar` and fetch the raw OpenAPI documents — see [OpenAPI](/en/docs/openapi).

## Related Pages

- [REST API Overview](/en/docs/api-reference) — authentication, the error contract, cross-cutting rules.
- [Create, Read & Update](/en/docs/records-crud) — request and response bodies for the records routes.
- [Filtering, Sorting & Pagination](/en/docs/records-filtering-sorting) — the list query grammar.
- [OpenAPI](/en/docs/openapi) — the generated document and the Scalar browser.
- [Table Webhooks](/en/docs/table-webhooks) — configuring the webhook routes above.