Connection and authentication
The default base URL is http://127.0.0.1:4202. Start the service with npm start and distinct REMUS_CALLER_TOKEN and REMUS_REVIEWER_TOKEN values as documented in the package README. Requests require Authorization: Bearer <token>; writes use application/json.
The service binds to loopback. It rejects browser-origin requests and does not provide hosted endpoints or account provisioning. One fixed caller and one reviewer are supported.
Create a request — POST /v1/requests
Caller only. Supply action and resource, plus amountCents for payments.refund. Supply an Idempotency-Key header (1–128 letters, digits, underscores or hyphens). SDK: client.request(input, { idempotencyKey }).
The same key and input return the existing request. A changed payload with the same key returns 409. Keep the key stable across network retries. The response includes id, requestHash, decision, rule and status.
crm.read_customer on cus_1042 is allowed. Refunds on charge_0821 up to 2500 cents are allowed, 2501–10000 require review, and larger valid amounts are denied. Unknown actions and out-of-scope resources are denied. Malformed requests return 400.
{
"action": "payments.refund",
"resource": "charge_0821",
"amountCents": 4900
}Inspect — GET /v1/requests/:id
Caller or reviewer. SDK: client.getRequest(id). Read the immutable request, its decision, status and saved result. There is no endpoint to edit a request after review.
Review — POST /v1/requests/:id/review
Reviewer only. Send requestHash and decision: approve or reject. SDK: reviewer.approve(id, { requestHash }) or reviewer.reject(id, { requestHash }).
Only pending review requests can be reviewed. The hash must match exactly. The default approval lifetime is five minutes; configure REMUS_APPROVAL_TTL_MS on the service. An expired approval requires a new request. The caller credential cannot approve its own action.
{
"requestHash": "<hash returned by the API>",
"decision": "approve"
}Execute — POST /v1/requests/:id/execute
Caller only. Send an empty JSON object. SDK: client.execute(id). The service rechecks policy and any approval before executing the local adapter.
Tool execution, result storage and audit commit share a SQLite transaction. Repeating execution of an executed request returns its saved result. Concurrent calls cannot create a second ledger entry for that request.
The refund adapter also enforces the remaining $120 charge balance. This transactional guarantee applies to the local SQLite adapter; an external provider needs its own idempotency and reconciliation design.
Audit and ledger
GET /v1/requests/:id/audit returns ordered events. SDK: client.audit(id). GET /v1/ledger/refunds returns ledger entries and totalCents. SDK: client.refunds(). Both authenticated roles can inspect these local records.
GET /health is unauthenticated and reports local-developer-preview mode.
Errors and limits
SDK failures throw RemusError with status, code and message. Typical responses: 400 invalid input, 401 missing/invalid credentials, 403 denied or wrong role, 404 missing request, 409 conflicting key or missing/expired approval, 413 body over 16 KiB, and 415 incorrect content type.
This preview has fixed example grants and a local ledger. It does not provide tenant isolation, a configurable policy service, an approval UI, external payment adapters or production deployment support. Keep it on your machine.