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) use GET. Pass input as query parameters, or POST with a JSON body — both work.
  • Mutating actions use POST, PATCH, or DELETE with 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.