API Reference
The Servelo REST API lets you integrate ticket and client data with external tools. All API requests are scoped to a tenant and require authentication.
Authentication
The API uses short-lived JWT access tokens (15-minute TTL) and long-lived refresh tokens (30-day TTL). Obtain tokens by signing in with a password or via magic link verification.
POST /api/auth/login
Content-Type: application/json
{ "email": "admin@yourdomain.com", "password": "your-password" }
Include the access token in all subsequent requests:
Authorization: Bearer <accessToken>
When the access token expires, refresh it:
POST /api/auth/refresh
{ "refreshToken": "<refreshToken>" }
โ { "accessToken": "..." }
Tenant resolution
The API resolves the tenant from the request hostname. Use your tenant subdomain as the base URL:
https://your-company.serveloapp.com/api/...
Auth
| Method | Endpoint | Auth | Description |
|---|---|---|---|
| POST | /api/auth/login | None | Sign in with email and password. Returns access + refresh tokens. |
| POST | /api/auth/magic-link/request | None | Request a magic link for an email address. |
| GET | /api/auth/magic-link/verify | None | Verify a magic link token. Returns access + refresh tokens. |
| POST | /api/auth/refresh | None | Exchange a refresh token for a new access token. |
| POST | /api/auth/logout | None | Revoke a refresh token. |
| GET | /api/auth/me | Required | Get the current user's profile. Includes has_password boolean. |
Users
All user endpoints require a valid access token. Role requirements are noted per route.
| Method | Endpoint | Role | Description |
|---|---|---|---|
| GET | /api/users | Admin | List all users in the org with role, status, and auth provider. |
| POST | /api/users/invite | Admin | Invite a new user. Sends a 7-day magic link invite email. |
| GET | /api/users/technicians | Any | List active users available for ticket assignment. |
| GET | /api/users/preferences | Any | Get the current user's preferences. |
| PUT | /api/users/preferences | Any | Merge-update the current user's preferences. |
| POST | /api/users/me/avatar | Any | Upload a profile photo for the current user. |
| POST | /api/users/me/set-password | Any | Set a password on the current user's account (no existing password required). Body: { password }. |
| POST | /api/users/me/change-password | Any | Change the current user's password. Body: { currentPassword, newPassword }. |
| PUT | /api/users/:id | Admin | Update a user's name, role, phone, notes, or avatar URL. |
| POST | /api/users/:id/set-password | Admin | Force-set a password for any user in the org. Body: { password }. Minimum 8 characters. |
| POST | /api/users/:id/send-login-link | Admin | Send a 24-hour magic link to a user. |
| PUT | /api/users/:id/deactivate | Admin | Deactivate a user. They cannot log in until reactivated. |
| PUT | /api/users/:id/reactivate | Admin | Reactivate a previously deactivated user. |
| DELETE | /api/users/:id | Admin | Permanently delete a user. |
Tickets
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/tickets | List all tickets |
| GET | /api/tickets/:id | Get a single ticket |
| POST | /api/tickets | Create a ticket |
| PUT | /api/tickets/:id | Update a ticket |
| DELETE | /api/tickets/:id | Move a ticket to Trash (admin only) |
| GET | /api/tickets/:id/comments | List comments on a ticket |
| POST | /api/tickets/:id/comments | Add a comment |
| POST | /api/tickets/:id/photos | Upload a photo to a ticket |
| DELETE | /api/tickets/:id/photos/:photoId | Delete a ticket photo |
scheduled_at and due_date take an ISO timestamp. One without a timezone is read in the tenant's timezone: 2026-10-01T18:00 is 6 PM local, a date-only due date is due at 11:59 PM that day, and a date-only visit is 9:00 AM. Values with Z or an offset are stored as given.
Clients
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/customers | List all clients |
| GET | /api/customers/:id | Get a single client |
| POST | /api/customers | Create a client |
| PUT | /api/customers/:id | Update a client |
| DELETE | /api/customers/:id | Delete a client (admin only) |
Quotes
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/quotes | List all quotes |
| GET | /api/quotes/:id | Get a single quote |
| POST | /api/quotes | Create a quote |
| PUT | /api/quotes/:id | Update a quote |
| POST | /api/quotes/:id/send | Email the quote to the client |
| DELETE | /api/quotes/:id | Delete a quote (admin only) |
Revenue & Expenses
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/revenue | List revenue entries |
| POST | /api/revenue | Create a revenue entry |
| PUT | /api/revenue/:id | Update a revenue entry |
| DELETE | /api/revenue/:id | Delete a revenue entry (admin only) |
| GET | /api/expenses | List expense entries |
| POST | /api/expenses | Create an expense entry |
| PUT | /api/expenses/:id | Update an expense entry |
| DELETE | /api/expenses/:id | Delete an expense entry (admin only) |
Settings
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/settings | Get all settings for the org |
| PUT | /api/settings | Update one or more settings (admin only) |
System Admin
These endpoints require the caller to be an admin in the SYSTEM_ADMIN_ORG tenant.
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/admin/orgs | List all tenants with user counts and plan info |
| PUT | /api/admin/orgs/:slug | Update an org (plan, name, active status) |
| DELETE | /api/admin/orgs/:slug | Permanently delete an org and all its data |
| GET | /api/admin/orgs/:slug/users | List all users in an org |
| PUT | /api/admin/orgs/:slug/users/:id | Update a user's role or active status in any org |
| POST | /api/admin/orgs/:slug/users/:id/set-password | Force-set a password for a user in any org. Body: { password }. |
| DELETE | /api/admin/orgs/:slug/users/:id | Permanently delete a user from any org |
AI assistant connector (MCP)
Servelo exposes a remote MCP server at https://serveloapp.com/mcp (Streamable HTTP, OAuth 2.1 with PKCE and dynamic client registration), so any AI assistant that supports remote MCP connectors (Claude, ChatGPT, Gemini, and others) can read and act on live Servelo data. Setup steps for each assistant are in AI Assistants.
- Add a custom connector (remote MCP server) in your assistant with the URL above
- The assistant registers itself and opens Servelo's sign-in (or your existing session) with a standard OAuth consent screen
- Approve the connection. The assistant can now call the tools below on your behalf
Every tool call is authenticated as you and enforces the same roles and validation as the equivalent page in the app; nothing is reimplemented or given broader access. Excluded from the tool surface entirely: org/user/billing/plan management, SSO/MFA settings, deletion, and password changes. Assistants that support MCP Apps also show Servelo's forms (open_form, prepare_close_ticket); the full command list is in AI Assistants.
| Area | Tools |
|---|---|
| Tickets | list, get, create, update, add comment, pin, prepare_close_ticket (with an interactive Close form in MCP Apps hosts), close_ticket |
| Forms | open_form and submit_form: 19 pick-and-fill actions (new ticket, log expense, send invoice, and more) shown as forms in MCP Apps hosts |
| Ticket AI | ask_job_planner, get_job_planner, apply_planner_suggestion, post_planner_reply, summarize_ticket_thread, draft_customer_reply, suggest_quote_items, fill_ticket_from_files |
| Customers | list, get, create, update |
| Quotes | list, get, create |
| Invoices | list, get, create |
| Technicians | list |
| Assets | list, get |
| Revenue & Expenses | list |
| Other | search, dashboard summary |
Admins manage all connections, including their own, and can limit connections to admins, turn them off for the whole tenant, or disconnect anyone's app from Global Settings > Integrations; anyone can also remove the connector in their assistant. Revoking immediately invalidates that connection's access. For the full user guide, see AI Assistants.
Error format
All error responses use the same shape:
{ "error": "Human-readable error message" }
Common status codes:
| Code | Meaning |
|---|---|
400 | Bad request. Missing or invalid input. |
401 | Unauthenticated. Token missing, invalid, or expired. |
403 | Forbidden. Authenticated but not allowed (wrong role, suspended org). |
404 | Resource not found. |
409 | Conflict. Typically a duplicate (e.g. email already exists). |
429 | Rate limited. Slow down and retry. |
500 | Server error. |