Service tier and migration backlog
How Mattering's own apps call each other, which endpoints exist only on that tier, and how far each app is from the shared API standard. Written for operators; customers do not need this page.
The service tier
Every app mounts its route list a second time under its service prefix (/api/internal/ or /api/internal/v1/). Requests there carry the shared secret and the acting identity in headers instead of a token:
X-Internal-Secret: <MATTERING_INTERNAL_API_SECRET>
X-Internal-Org-Id: <organization uuid>
X-Internal-User-Email: <acting user's email>
X-Internal-User-Id: <auth-side user id, audit only>
The view is the same function that serves the User API, so request and response shapes are identical. Identity is resolved from the email header (the auth-side id is never a local key). The secret is not available outside Mattering's own services; it is documented so the behaviour of the MCP gateway, Agents and Automations, all of which call this tier on a person's behalf, can be read in one place.
A few endpoints exist only here, because exposing them to a token holder would let one caller read or act on another person's data (for example the Comms unread summary, which takes an explicit email). They are marked Service tier on their resource pages and listed per app below.
Base API Template scorecard
Measured by the generator from each app's URL tables and views, not asserted. An app converges on the standard whenever its API is next touched; this table is the backlog.
| App | User tier | Versioned | One list | Envelope | Pagination | Error codes | Score |
|---|---|---|---|---|---|---|---|
| Productivity | Yes | No | No | No | No | No | 1 / 6 |
| Sales | Yes | No | Yes | No | No | Yes | 3 / 6 |
| Automations | Yes | No | No | No | No | No | 1 / 6 |
| Agents | No | Yes | No | No | No | Yes | 2 / 6 |
| Comms | Yes | Yes | No | Yes | No | Yes | 4 / 6 |
| Forms | Yes | No | No | No | No | No | 1 / 6 |
| QR | Yes | No | No | No | No | Yes | 2 / 6 |
| Calendar | Yes | Yes | Yes | No | No | Yes | 4 / 6 |
| Contracts | Yes | No | Yes | No | No | Yes | 3 / 6 |
| Analytics | Yes | Yes | Yes | No | No | Yes | 4 / 6 |
| Networking | Yes | Yes | Yes | Yes | No | Yes | 5 / 6 |
| Mastery | Yes | Yes | Yes | No | No | No | 3 / 6 |
| Platform | Yes | No | No | No | No | No | 1 / 6 |
| Auth | No | No | No | No | No | No | 0 / 6 |
| Website | Yes | Yes | Yes | Yes | No | Yes | 5 / 6 |
User tier: User tier mounted (/api/user/v1/).
Versioned: Internal tier versioned (/api/internal/v1/).
One list: One api_urls.py included on both tiers.
Envelope: Responses use the {data, meta} envelope.
Pagination: Collection reads paginate with meta.total.
Error codes: Errors carry a snake_case code and a detail.
Known gaps, per app
What a caller runs into today. These notes live in the generator's app registry so they are reviewed whenever the reference is rebuilt.
Mattering Productivity
- Most responses are bare dictionaries, not the {data, meta} envelope. Collection reads return the collection key plus count, and mutations return success plus the affected object.
- Every endpoint, including reads, is POST with a JSON body. Pass space_id, project_id or widget_id in the body, never as a query string.
- Identity guard: a body user_id that disagrees with the token subject is rejected.
- Unpaginated reads with a hard cap:
batch-fields/update/ (8),custom-field-presets/manage/ (8),custom-fields/manage/ (8),folders/manage/ (8),kb/manage/ (8),notifications/send/ (8),projects/manage/ (8),projects/{project_id}/canvas/ (8),query/kb/ (8),query/task/ (8),search/ (8),seed-demo/ (8),spaces/ (8),spaces/{space_id}/custom-field-presets/list/ (8),spaces/{space_id}/members/ (8),spaces/{space_id}/overview/ (8),spaces/{space_id}/status-presets/list/ (8),status-presets/manage/ (8),tabs/manage/ (8),tasks/create-bulk/ (8),tasks/create-with-subtasks/ (8),tasks/create/ (8),tasks/delete-bulk/ (8),tasks/manage/ (8),tasks/serialize/{task_id}/ (8),tasks/update-bulk/ (8),tasks/{task_id}/assign/ (8),tasks/{task_id}/attachments/request-upload/ (12),tasks/{task_id}/attachments/upload/ (8),tasks/{task_id}/comment/ (8),tasks/{task_id}/custom-field/ (180),tasks/{task_id}/move/ (8),tasks/{task_id}/subtask/ (8),tasks/{task_id}/tags/add/ (8),tasks/{task_id}/tags/remove/ (8),tasks/{task_id}/update/ (8),templates/deploy/ (8),user-spaces/ (8),widgets/attach-backing-list/ (8),widgets/configure-view-bulk/ (8),widgets/configure-view/ (8),widgets/manage-bulk/ (8),widgets/manage/ (8),workspace-data/{space_id}/ (8). - Service-tier-only resources: Org erasure, Org export, Search, Usage, User erasure, User export.
Mattering Sales
- Create and update ignore body keys that are not in the documented field list. A misspelled key is dropped silently and the write still returns 200 or 201, so compare the returned record against what you sent.
- Record list routes (businesses, contacts, deals) return their collection key beside data while the SALES_API_LEGACY_KEYS transition is on. Read data; the duplicate top-level keys go away when the setting is turned off.
- Deal payloads carry pipe, stage, status and owner_email names as well as ids since 2026-11-08.
- Unpaginated reads with a hard cap:
businesses/bulk/ (200),businesses/upsert/ (200),businesses/{business_id}/ (200),contacts/bulk/ (200),contacts/upsert/ (200),contacts/{contact_id}/ (200),deals/{deal_id}/ (10),email-events/inbound/ (255),files/upload/finalize/ (255),files/upload/init/ (127),files/{file_id}/ (255),notes/{note_id}/ (80),objects/{object_key}/records/{record_id}/ (2),tasks/{task_id}/ (255).
Mattering Automations
- The user tier is deliberately narrow: workspaces, Data Studio and read-only node execution (query nodes only). Action nodes, secrets and connector management stay on the service tier.
- Routes are registered by hand in the project urls.py rather than one api_urls.py mounted twice, and the versioned /api/internal/v1/ prefix is not used yet.
- Unpaginated reads with a hard cap:
automations/ (200),canvas-ai/create/ (2000),canvas-ai/node-types/ (117),canvas-ai/{automation_id}/configure-node/ (10),canvas-ai/{automation_id}/run/ (40),canvas-ai/{automation_id}/runs/ (10),connectors/v1/credentials/ (64),connectors/v1/instances/manage/ (64),connectors/v1/instances/{instance_id}/disconnect/ (64),data-studio/datatables/{datatable_id}/entries/bulk/ (100),node-exec/ (40),telephony/v1/numbers/buy/ (120),telephony/v1/numbers/search/ (10),telephony/v1/numbers/{public_id}/assign/ (120). - Service-tier-only resources: Agent routines, Automations, Canvas builder, Connectors, Org erasure, Org export, Search, Secrets, Telephony, User erasure, User export.
Mattering Agents
- No /api/user/v1/ mount exists yet. The MCP gateway reaches these routes with the internal secret and injects the caller's identity headers, so the tool surface is what external callers get today.
- Unpaginated reads with a hard cap:
agents/{public_id}/ (300),agents/{public_id}/call-invite/ (200),agents/{public_id}/call-review/ (300),agents/{public_id}/call-transcript/ (4),agents/{public_id}/knowledge/ (200),agents/{public_id}/triggers/ (120),agents/{public_id}/voice-turn/ (300),browser-runtimes/heartbeat/ (80),voice-runtimes/heartbeat/ (80). - Service-tier-only resources: Agents, Browser, Inbox, Knowledge, Org erasure, Org export, Runs, Schedules, Search, Triggers, User erasure, User export, Voice.
Mattering Comms
- Unpaginated reads with a hard cap:
calls/{channel_public_id}/guest-link/ (32),calls/{channel_public_id}/presence/ (32),calls/{channel_public_id}/recording/ (32),calls/{channel_public_id}/screen-share/ (8),channels/create/ (120),channels/resolve/ (500),channels/{channel_public_id}/delete/ (32),channels/{channel_public_id}/members/ (32). - Service-tier-only resources: Calls, Org erasure, Org export, Unread summary, User erasure, User export.
Mattering Forms
- Service-tier-only resources: Custom fields.
Mattering QR
- Service-tier-only resources: Custom fields.
Mattering Calendar
- Service-tier-only resources: Org erasure, Org export, Sync, User erasure, User export.
Mattering Analytics
- Unpaginated reads with a hard cap:
datasets/{public_id}/publish (20).
Mattering Networking
- Unpaginated reads with a hard cap:
debriefs/ (160),prompts/ (300),prompts/{code}/ (300),prompts/{code}/answers/ (300),rules/ (300),settings/ (300),stories/ (300),topics/ (300). - Service-tier-only resources: Org erasure, Org export, User erasure, User export.
Mattering Platform
- On the user tier every lookup is scoped to the caller's organization and the raw storage path surfaces (register, serve-by-path) answer 403 internal_only.
- Unpaginated reads with a hard cap:
files/create/ (120),files/google/ (100),files/manage/ (255),files/native/image/ (200),files/native/model/ (500),files/people/ (50),files/shares/manage/ (160),files/upload/finish/ (200),files/upload/session/ (200),files/upload/start/ (200),files/versions/manage/ (255),files/{file_id}/ops/ (120),folders/manage/ (255). - Service-tier-only resources: V1.
Mattering Auth
- Auth is the grandfathered Django REST Framework service. Its public tier lives at /api/ (no v1 segment) and accepts a Bearer JWT, a mat_ organization key, an OAuth2 token, or the X-API-Key / X-API-Secret pair on the public app directory.
- Response bodies are DRF serializer output, not the {data, meta} envelope. Errors are {error: message} without a stable code.
- Unpaginated reads with a hard cap:
workspaces/{public_id}/agents/set/ (30). - Service-tier-only resources: Service.
Mattering Website
- Unpaginated reads with a hard cap:
connector-pages/delete (254),connector-pages/doc (60),connector-pages/mcp (60),learn/articles/manage (200).
Keeping this current
Run the generator after any change to an api_urls.py, a view module it points at, or a gateway tool module, and commit the data files with the code:
python tools/build_api_docs.py
The lint-api-docs workflow runs the same script with --check on every push and fails when the committed data differs from what the code produces. Section 13 of templates/BASE_API_TEMPLATE.md explains what to write in a view so that it documents well: a first-line docstring, body keys read through data.get() or a field list, a serializer helper for the response, and err(code, detail) for errors.