DevelopersPre-alpha

JSON-RPC API

Endpoint shape, authentication, common methods and error patterns.

Endpoints

Method / path	Auth	Purpose
`GET /api/health`	None	Liveness `{"ok":true}`
`POST /api/rpc`	Session cookie or API key	Model RPC

Health check

health check

$curl -s http://localhost:8080/api/health

Authentication

Use the sumeru_session cookie from /web/login, or send X-API-Key: sk_... (also Authorization: Bearer sk_...).

Request shape

Flat Sumeru JSON:

JSON

json

1{2  "model": "my.module",3  "method": "search_read",4  "args": [[], ["id", "name"]],5  "kwargs": {"limit": 50, "offset": 0}6}

A nested JSON-RPC params wrapper is also accepted. Responses use {ok, result, error}.

Methods

Method	args	kwargs	result
`search`	`[domain?]`	`limit`, `offset`	List of records
`search_read`	`[domain, fields]`	`limit`, `offset`	Projected records
`read`	`[ids, fields?]`	-	Records; missing ids -> `NOT_FOUND`
`read_group`	`[spec]`	-	Grouped rows (sum/count)
`call`	`[id, method, vals?]`	-	`true` or `{redirect}`
`create`	`[values]`	-	New id
`write`	`[ids, values]`	-	`true`
`unlink`	`[ids]`	-	`true`
`create_many`	`[[values], ...]`	-	List of ids
`write_many`	`[ids, values]`	-	`true`
`unlink_many`	`[ids]`	-	`true`

read_group spec includes domain, groupby, and fields with measure (sum or count). call invokes RegisterObjectAction handlers (same as form object buttons). See JSON-RPC reference.

call

text

1curl -s http://localhost:8080/api/rpc \2  -H 'Content-Type: application/json' \3  -H 'X-API-Key: sk_YOUR_KEY' \4  -d '{5    "model": "core.user",6    "method": "call",7    "args": [42, "action_reset_password", {}]8  }'

search_read

text

1curl -s http://localhost:8080/api/rpc \2  -H 'Content-Type: application/json' \3  -H 'X-API-Key: sk_YOUR_KEY' \4  -d '{5    "model": "my.module",6    "method": "search_read",7    "args": [[], ["id", "name", "active"]],8    "kwargs": {"limit": 50, "offset": 0}9  }

create

text

1curl -s http://localhost:8080/api/rpc \2  -H 'Content-Type: application/json' \3  -H 'X-API-Key: sk_YOUR_KEY' \4  -d '{5    "model": "my.module",6    "method": "create",7    "args": [{"name": "From API", "active": true}],8    "kwargs": {}9  }

Limits. Default kwargs.limit is 500 (hard cap). Deep offsets are clamped.

Compile and run

Terminal

shell

$make run$curl -s http://localhost:8080/api/health

What not to do

Do not put API keys in query strings or non-HttpOnly storage.
Do not call mutating methods without understanding group ACLs for the key's user.
Do not treat pre-alpha error codes as a frozen public contract.

Next step

Verify behaviour in Testing, or create keys via API keys.