Using the API
Every platform action is reachable through one universal endpoint: the invoke dispatcher. There's no per-feature REST surface to learn — you call an action by its registry name.
Request shape
POST /api/invoke/<action.name>
Authorization: Bearer <api-key>
Content-Type: application/json
{ ...action input... }
The path segment is the dotted action name (missions.create,
contacts.update, …). The JSON body is the action's input, validated against
its Zod schema. For example:
curl -X POST https://<host>/api/invoke/missions.create \
-H "Authorization: Bearer $NIHMBUS_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "subjectId": "sub_123", "name": "Spring launch" }'{ "mission": { "id": "msn_…", "name": "Spring launch", "status": "planning" } }GET vs POST
- Read-only actions (
*.list,*.get,*.search) useGET. Pass input as query parameters, orPOSTwith a JSON body — both work. - Mutating actions use
POST,PATCH, orDELETEwith a JSON body.
The Reference lists the method and mutating flag for every
action.
Validation & errors
- Input is validated against the action's schema. Invalid input is rejected before the handler runs.
- Role gates (
requiresRole) are checked first; unauthorized callers get a permission error. - Handler errors are surfaced with the real underlying cause. Database constraint violations are unwrapped to a readable message (e.g. a foreign-key or unique violation) instead of a raw SQL dump.
Extension actions
Extensions contribute actions under the ext. prefix:
POST /api/invoke/ext.<extension>.<action>
They're validated against the extension's own input schema and gated by its
granted permissions. Extensions can also expose a full HTTP namespace at
/api/ext/<name>/*. See Extensions.
The mirror
For complex authenticated reads, the platform queries a local mirror of the gateway's org/workspace data rather than the gateway directly — and org writes hit the mirror identically whether you're in auth-bypass dev mode or real auth. This keeps reads fast and behavior consistent across environments.