``GET /api/internal/search/?q=<text>&limit=<n>`` for the platform shell.
Contract: planning/cross-app-search-contract.md. The platform calls every app in parallel and merges the results; this returns ``{data: [{type, type_label, id, title, subtitle, path}], meta: {query, count}}`` for spaces, projects, tasks and files.
Identity comes from the internal headers through the same helpers every other internal endpoint uses (email first, X-Internal-User-Id required). X-Internal-Org-Id is required (403 without it) and limits the search to that organization's spaces; X-Internal-Workspace-Id, when sent, limits it to that one workspace. Inside those spaces the project ACL applies exactly as in the app (private projects and folders, ProjectMember role='none'), and tasks and files follow their project. q under two characters returns empty data, never a 400. limit (default 8, clamped to 1..20) caps the whole response; each type contributes up to limit candidates and they are interleaved best-first so one type cannot crowd out the rest.
URL
- Service tierhttps://productivity.mattering.io/api/internal/search/
Query parameters
| Name | Default |
|---|---|
limit | none |
q | none |
Responses
200 bare JSON object (no envelope)
{
"data": [
{
"type": "...",
"type_label": "...",
"id": "...",
"title": "...",
"subtitle": "...",
"path": "..."
}
],
"meta": {
"query": "...",
"count": 0
}
}
Field names come from the code; values are placeholders (... is a string, 0 a number, dates are ISO 8601).
Errors
| Status | Code |
|---|---|
| 401 | missing_actor |
| 401 | unauthorized |
| 403 | forbidden |
Example
curl -X GET "https://productivity.mattering.io/api/internal/search/?limit=...&q=..." \ -H "X-Internal-Secret: $MATTERING_INTERNAL_API_SECRET" \ -H "X-Internal-Org-Id: $ORG_ID" \ -H "X-Internal-User-Email: you@example.com"
Source: MatteringPMCore/internal_api.py (internal_api.internal_search)