Server surface, exposed domains and integrations
API and endpoints
Xedul exposes a surface of server endpoints organised by domain, under /api. This page describes the shape of it; it is not an exhaustive field-by-field reference.
Principles
- One domain, one endpoint group. The route structure mirrors the application domains.
- Logic in controllers. Route handlers stay thin; business logic lives in dedicated controllers.
- Always authenticated. Every work endpoint requires a valid session; the user's organisation determines the data scope.
- End-to-end typing. Responses are typed from the database through to the client.
Exposed domains
| Group | Scope |
|---|---|
| `auth` | Session, sign-in, password recovery |
| `organization` | Practice details and settings |
| `users` | Organisation user management |
| `invite-user` | Inviting new people |
| `employees` | The practice's people records |
| `customers` | Clients |
| `contacts` | Contacts and leads |
| `projects` / `deals` | Cases and their pipeline |
| `tasks` | Tasks |
| `statuses` | Configurable states |
| `documents` | Documents and attachments |
| `comments` | Comments on work entities |
| `mentions` | Mentions of people in comments |
| `notifications` | Notifications |
| `reminders` | Reminders and recurrence |
| `reference-data` | Sectors, lead sources, sizes |
| `health` | Service status |
Email integration endpoints
The integrations have their own endpoint group, because their authentication model is distinct from the web application's.
Gmail
| Endpoint | Role |
|---|---|
| `gmail/auth/login` | Sign in to Xedul from the extension or add-on |
| `gmail/auth/refresh` | Silent refresh of the integration session |
| `gmail/draft` | Save and read the temporary draft |
| `gmail/draft/import` | Deferred attachment import |
The draft read endpoint does not return the authorisation block used to access attachments: that data is server-side only.
Outlook
The outlook group handles authentication from the task pane and the lifecycle of the draft generated by the add-in.
The lifecycle of a draft
Both integrations share the same shape:
- The mail client collects the message data.
- It sends them to Xedul as a temporary draft, avoiding carrying everything in the URL.
- Xedul opens the tasks page with a reference to the draft.
- The browser requests attachment import, where applicable.
- The form appears pre-filled; the user confirms.
- The task is created.
The draft is deliberately temporary: it isn't a task, doesn't appear in lists and raises no notifications. It becomes real work only on the user's confirmation.
Realtime
Alongside the endpoints, the client subscribes to changes through Supabase Realtime. The two paths are complementary: the API serves explicit operations, subscriptions keep open views aligned.
Notes for integrators
- Data scope is not passed as a parameter: it derives from the session. There is no way to request another organisation's data.
- Email integration sessions are separate from web application sessions: authenticating in one does not authenticate the other.
- Uploadable file types are subject to an allowlist, which also applies to automatic imports.
This page describes the shape of the system, not a stable public contract. For a third-party integration, agree the endpoints and their guarantees before building on them.