---
title: "JSON-RPC reference"
description: "Curated method reference for the local JSON-RPC control plane."
source: https://carina.nebutra.com/api/json-rpc/
---

# JSON-RPC reference

> Curated method reference for the local JSON-RPC control plane.

Local clients speak JSON-RPC 2.0 against the daemon socket (`~/.carina/daemon.sock`) or stdio.

Authoritative registry: `protocol/jsonrpc/methods.json`.  
Schemas: `protocol/schemas/`.  
Narrative source: `docs/rpc-api.md`.

## session.create

Create a session bound to a workspace and permission profile.

{/* Two-column: params/result | sticky sample. Method jumps live in On this page. */}

## Gateway / daemon

| Method | Purpose |
| --- | --- |
| `runtime.initialize` | Client identity + projection version negotiation |
| `runtime.capabilities` | Advertised runtime capabilities |
| `gateway.hello` | Contract snapshot (role, scopes, features, method catalog) |
| `gateway.methods` | Live method catalog with scope / remote / stream flags |
| `gateway.token.issue` | Local-only scoped token issuer (signing key required) |
| `daemon.status` / `metrics` / `doctor` | Process health |
| `daemon.remote.disable` | Remote kill-switch |
| `daemon.reload` | Reload configuration |

## Session & task

| Method | Purpose |
| --- | --- |
| `session.create` / `get` / `list` / `close` | Lifecycle |
| `session.pause` / `resume` | Suspend / continue |
| `session.replay` / `items` / `review` | History and projections |
| `session.events.stream` | Live event notifications |
| `execution.start` / `cancel` / `status` | Task control |
| `governance.action.approve` / `deny` | Resolve approvals |

## Workspace

| Method | Purpose |
| --- | --- |
| `workspace.tree` | File tree via `carina-scan` |
| `workspace.search` | Structured search via `carina-grep` |
| `workspace.file.get` | Read a clean relative UTF-8 file up to 1 MiB (`FileRead`) |
| `workspace.diff` | Tracked/untracked changes (capped; binary omitted) |
| `workspace.patch.propose` / `apply` / `rollback` | Transactional patches |
| `worktree.create` / `list` / `enter` / … | Isolated worktree lifecycle |

## Memory

| Method | Purpose |
| --- | --- |
| `memory.list` | List entries for `target=memory` or `target=user` |
| `memory.context` | Fenced recalled-memory block for the session |
| `memory.status` | Local authority, external recall health, identity scope |
| `memory.write` | add/replace/remove/batch via `MemoryWrite` capability |
| `memory.projection.authorize` / `retry` / `reseed` | Optional HMS projection control |

`memory.write` is local-only and control-plane-write. Built-in policy defaults `MemoryWrite` to `requires_approval`. Audit records target/scope/action, operation count, and content hash — **not** raw memory text.

## Worker

`worker.register` · `worker.heartbeat` · `worker.list` · `worker.revoke` · `work.poll` / `renew` / `report` · `backpressure.report` / `status`

`worker.register` returns worker_id + worker_credential pair **once**. The daemon stores only the credential hash. Every successful `work.poll` returns a `lease_generation` fencing token that must be echoed on renew/report.

## Context engine (local-only)

| Method | Scope | Purpose |
| --- | --- | --- |
| `context.status` | `read` | Configured and effective local engine state |
| `context.doctor` | `read` | Health probe used by `daemon.doctor` |
| `context.stats` | `read` | Compression counters |
| `context.compress` | `write` | Diagnostic compression (not agent transcript path) |

Carina does not bundle or start an external compression runtime. Auto mode resolves to the local no-op implementation.

## Operator inspection highlights

- **`workspace.diff`** — Git with locks/fsmonitor/external diff/textconv disabled; 256 KiB per textual diff; 1 MiB response cap
- **`mcp.inventory`** — public MCP server names, tool names, prompt counts, connection health (no process args/env/schemas)

## Example exchange

```json title="request.json"
// response
{"jsonrpc":"2.0","id":1,
 "result":{"session_id":"sess_01J...","workspace_id":"ws_01J...","profile":"safe-edit"}}

// event notification
{"jsonrpc":"2.0","method":"event",
 "params":{"event_id":"evt_...","session_id":"sess_...","type":"CommandStarted",
           "timestamp":"2026-07-03T12:00:00Z","payload":{"command":"npm test"},
           "permission_decision_id":"perm_..."}}
```

  Groups not fully expanded here include `agent.*`, `session.checkpoint.*`, `workflow.*`, `schedule.*`, `channel.*`, `extension.*`, `usage.*` / `telemetry.*`, and `work.*`. See the protocol registry.

## Source of truth

- Registry: `protocol/jsonrpc/methods.json` · narrative: `docs/rpc-api.md`
- Dual catalogs: `apps/docs` → `pnpm sync-protocol` · [Method catalog](/api/methods/)
- Related: [API overview](/api/overview/) · [API versions](/api/versions/) · [Sessions](/api/sessions/)

## Next

- [Method catalog](/api/methods/) — full list + Try it playground
- [Sessions](/api/sessions/) — session lifecycle methods

---
Source: https://carina.nebutra.com/api/json-rpc/
Markdown: https://carina.nebutra.com/api/json-rpc/index.md