API concepts
A concept map for integrators of the Axuz API, covering domain hierarchy, ids, teamId in the path, multi-tenancy, hosts per service, the /v1 prefix and what is public versus internal.
Before calling the API, it helps to understand how the Axuz domain is organized and how routes reflect that organization.
Domain hierarchy
company → team (workspace) → project (optional) → channel | timeline | task board | wiki | file
| Concept | What it is | Note for integrators |
|---|---|---|
| company | Organization grouping teams | company roles take precedence over team roles |
| team (workspace) | The tenancy unit; almost every route starts at /teams/{teamId}/... | it is the data isolation boundary |
| project | Optional layer between team and content | resources accept a null project_id (“no project”) |
| channel | Container for conversation, tasks, files and wiki | called Channel in the UI; in the database and some field names it is timeline |
| timeline | The workspace’s social feed (rich posts) | in the API, feeds and feed_posts; do not confuse it with the channel |
| board | Task board (Kanban, list, Gantt, calendar over the same data) | board ids appear in /teams/{teamId}/boards/{id} |
Identifiers
Resource ids are UUIDs. Path parameters ({teamId}, {id}, {shareId}…) are validated as UUIDs and a malformed value usually results in 400. Dates are timestamptz in RFC 3339. Large lists use cursor pagination (never OFFSET). E-mail and phone are not user identifiers; always use the id.
teamId in the path and multi-tenancy
The API is multi-tenant over a shared database. Every domain table carries team_id and every query is scoped by it. In practice:
teamIdcomes from the path and is checked against your membership; it is never accepted from the request body;- being a member of another team grants nothing: the resource answers
404, not403, so the id’s existence is not confirmed; - the check order is: session (
401) → membership (403) → resource (404) → role/scope (403) → validation (400/422); - inside a team, access is resolved from narrowest to broadest: company role, team role, project scope and channel scope.
Hosts per service
Each service has its own host: https://<subdomain>.<domain>, where the domain is axuz.net (staging) or axuz.club (production). The specification servers follow this pattern (https://api.{domain}, etc.).
| API host | Service | Matching product interface |
|---|---|---|
api | Main backend: workspace, tasks, search, notifications, integrations | workspace, hub, app |
auth-api | Login, sign-up, sessions, OAuth | auth (login), admin, backoffice |
api-workspace | Tasks, notes, feeds, timelines, wiki, public board | workspace |
api-billing | Subscriptions, invoices, payables/receivables | financer |
api-calendar | Events, recurrence, invitations | calendar |
api-flow | Flowcharts, versions, sharing | flow |
api-forms | Forms and responses | forms |
files-api | Files and share links | drive |
mail-api | E-mail (SMTP/IMAP) | mail |
meet-api | Meeting rooms | meet |
messaging-api | Web Push and message delivery | (no UI of its own) |
Each operation in the reference states the right server; calling the wrong host results in 404. Routes of the same resource may live on different hosts while services are gradually extracted: always use the server listed on the operation.
Versions and /v1
The specification documents paths without a prefix. The workspace, forms and flow services also mount the same routes under /v1 (mirror), and the main backend has routes explicitly under /v1, such as /v1/integration-scopes. There is no published policy for parallel versions (v2) yet; breaking changes will be announced in Releases. Prefer the path exactly as in the reference.
Authentication, in one line
Session (HTTP-only cookie or Authorization: Bearer), personal token axp_, integration token axz_bot_ and OAuth 2.1. Details in Authentication. Each reference operation has an access class: public, public-signed (token in the URL), authenticated, team-member, team-admin, permission and scope.
What is public and what is internal
- Public: everything in the reference. That is the contract we maintain.
/platform/*routes (platform operations, backoffice) are not public API: they require platform roles and are not in the specification./internal/*routes serve service-to-service communication (authenticated with an internal key) and are not public API; they may change or vanish without notice. Do not call them.- Routes without login exist on purpose (public links, forms, guest rooms). See Public area and external assignees.
Errors and format
Services answer errors as JSON {"error": "<message>"}; some add fields (fields on validation, retry_after on 429). Expect 429 with Retry-After on rate-limited routes and honor it.