Core DevPre-alpha

JSON-RPC

Endpoint: POST /api/rpc

Source: sumeru/core/server/api/dispatch.go

Sumeru exposes JSON-RPC only at this endpoint. There is no alternate RPC transport.

SWC (Sumeru Web Client) is the primary consumer for workspace CRUD, read_group, and call. Browser code sends X-CSRF-Token from window.__SWC_BOOTSTRAP__.

Authentication

Method	Header / cookie
Session	Cookie `sumeru_session` (from `/web/login`)
API key	`X-API-Key: sk_…` or `Authorization: Bearer sk_…`

Unauthenticated requests receive error code UNAUTHORIZED.

Request shape

Flat Sumeru format:

{
  "model": "core.user",
  "method": "search_read",
  "args": [[["active", "=", true]], ["id", "login"]],
  "kwargs": { "limit": 50, "offset": 0 }
}

wrapper (also supported):

{
  "params": {
    "model": "core.user",
    "method": "search",
    "args": [[]],
    "kwargs": {}
  }
}

Response envelope

Success:

{ "ok": true, "result": <data>, "error": null }

Error:

{
  "ok": false,
  "result": null,
  "error": {
    "code": "ACCESS_DENIED",
    "message": "...",
    "details": {}
  }
}

Every response includes X-Request-ID when provided on the request.

Public methods

Method	args	kwargs	result
`search`	`[domain?]`	`limit`, `offset`	`[{record}, …]`
`search_read`	`[domain, fields]`	`limit`, `offset`	Projected records
`read`	`[ids, fields?]`	—	Records; missing ids → `NOT_FOUND`
`read_group`	`[spec]`	—	Grouped aggregation rows
`call`	`[id, method, vals?]`	—	`true` or `{redirect: "…"}`
`create`	`[values]`	—	New id (int)
`write`	`[ids, values]`	—	`true`
`unlink`	`[ids]`	—	`true`
`create_many`	`[[values], …]`	—	`[id, …]`
`write_many`	`[ids, values]`	—	`true`
`unlink_many`	`[ids]`	—	`true`

Default kwargs.limit is 500 (hard cap). Offset is applied in SQL via SearchPage.

read_group

args[0] is a spec object:

{
  "domain": [["state", "=", "sale"]],
  "groupby": ["partner_id"],
  "fields": [
    {"name": "amount_total", "field": "amount_total", "measure": "sum"},
    {"name": "__count", "field": "id", "measure": "count"}
  ]
}

Measures: sum, count. Uses the same ACL and record rules as search.

call

Invokes a handler registered with orm.RegisterObjectAction (same as form object buttons):

{
  "model": "crm.lead",
  "method": "call",
  "args": [42, "action_merge_wizard", { "active_ids": "3,7" }]
}

args[0] is the record id, args[1] the object-action name. Optional args[2] is a string map passed through to orm.RunObjectAction (used for list multi-select active_ids).

Read replica

When db_read_replica_dsn is configured, search, search_read, and list workspace loads prefer the read replica connection.

Security

RPC uses the same ACL and record rules as the web UI. The authenticated user id is taken from the session or API key owner and passed in the ORM context.

Observability

Prometheus metrics: sumeru_rpc_requests_total, sumeru_rpc_duration_seconds (see GET /metrics).