API contracts

Call an operation over HTTP, MCP, or the CLI with the same arguments and receive the same result and errors.

Docs menu

Each operation has a reference entry describing its arguments, result, and errors. HTTP, MCP, the CLI, and the SDK call the same operation. Here is function.invoke using three transports:

curl -s -X POST "$SUBSTRIO_URL/v1/functions/hello/_invoke" \
  -H "Authorization: Bearer $SUBSTRIO_KEY" -d '{"name":"world"}'

curl -s "$SUBSTRIO_URL/mcp" -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"substrio_function_invoke","arguments":{"name":"hello","event":{"name":"world"}}}}'

substrio invoke hello name=world

All three validate the key and the arguments against the operation's schema before the call runs. A refused call returns the same code on every transport.

Retries and races

Send Idempotency-Key on a write you may retry. A retry with the same key returns the first result again (HTTP API).
If a write guarded by an expected version (if: { _version }) conflicts with another write, read again before the next attempt.
DUPLICATE_RUN, SCHEDULER_FULL, DEADLINE_EXPIRED, CANCELLED and RATE_LIMITED are distinct outcomes, not variations on one error: branch on the code (see Errors).

Error model

Errors have stable, typed codes grouped into families: lifecycle, storage, memory, transaction and concurrency, key-value, cursor, graph, dimensional, schema, API, quota and rate, auth, query, app, and resource. An operation can add error-specific guidance for the next call. Branch on the stable code and use the message text only for display. See Errors for the envelope and full code table, and HTTP API for its HTTP format.

Versioning

The registry version is 1. A new field is added so older clients ignore it safely, and an operation name or tool name is never reused for something else.