API Reference

Register a new session in the hub. Returns the created session object with its assigned ID.

Request Body

{
  "name": "my-agent",
  "kind": "interactive",
  "realm": "default",
  "capabilities": [
    "memory.read",
    "memory.write",
    "delegate.receive"
  ],
  "public_key": "ed25519:MCowBQYDK2VwAyEA..."
}

Response (200)

{
  "id": "sess_01HX9J2N3PQRSTVWXYZ",
  "name": "my-agent",
  "kind": "interactive",
  "realm": "default",
  "status": "active",
  "created_at": "2026-04-06T09:00:00Z"
}

List all active sessions in the authenticated session's realm. Supports ?kind= and ?status= query parameters for filtering.

Response (200)

{
  "sessions": [
    {
      "id": "sess_01HX9J2N3PQRSTVWXYZ",
      "name": "my-agent",
      "kind": "interactive",
      "status": "active"
    },
    {
      "id": "sess_02HX9J2N3PQRSTVWXYZ",
      "name": "worker",
      "kind": "executor",
      "status": "active"
    }
  ],
  "total": 2
}

Fetch the full details of a single session including its manifest, capabilities, and current status.

Response (200)

{
  "id": "sess_01HX9J2N3PQRSTVWXYZ",
  "name": "my-agent",
  "kind": "interactive",
  "realm": "default",
  "status": "active",
  "capabilities": [
    "memory.read",
    "memory.write"
  ],
  "public_key": "ed25519:MCowBQYDK2VwAyEA...",
  "created_at": "2026-04-06T09:00:00Z",
  "last_seen": "2026-04-06T09:05:00Z"
}

Deregister a session from the hub. The session must be owned by the authenticated caller. All pending messages in the inbox are discarded.

Response (200)

{
  "message": "Session deregistered."
}

Send a liveness ping to a session. The hub forwards the ping and waits up to 5 seconds for a pong response.

Request Body

{
  "nonce": "abc123"
}

Response (200)

{
  "status": "alive",
  "latency_ms": 2,
  "nonce": "abc123"
}

Send an AISP message to one or more sessions. The payload must be a valid AISP envelope. The hub validates the category and routes accordingly.

Request Body

{
  "aisp": "0.1",
  "from": "sess_01HX...",
  "to": "sess_02HX...",
  "realm": "default",
  "category": "delegate",
  "payload": {
    "task": "summarize",
    "input": {
      "file": "README.md"
    }
  }
}

Response (200)

{
  "message_id": "msg_01HX9J2N3PQRSTVWXYZ",
  "status": "queued",
  "delivered": false
}

Poll the authenticated session's inbox. Returns unread messages. Supports ?category= and ?since= (ISO timestamp) for filtering. Messages are marked as read after retrieval.

Response (200)

{
  "messages": [
    {
      "id": "msg_01HX...",
      "from": "sess_02HX...",
      "category": "delegate",
      "sent_at": "2026-04-06T09:01:00Z",
      "payload": {
        "task": "summarize",
        "input": {
          "file": "README.md"
        }
      }
    }
  ],
  "unread_count": 1
}

Open a Server-Sent Events (SSE) stream. The hub pushes messages to the client in real-time as they arrive. The connection stays open indefinitely. Use X-Last-Event-ID for resumption.

Response (200)

{
  "event: message": {},
  "data": "{\"id\":\"msg_01HX...\",\"category\":\"ping\",\"payload\":{\"nonce\":\"xyz\"}}"
}

Read memory entries from the realm store. Supports ?namespace= for prefix filtering (e.g., ?namespace=project). Requires a valid read grant for keys not owned by the session.

Response (200)

{
  "entries": [
    {
      "key": "project.name",
      "value": "My Project",
      "owner": "sess_01HX...",
      "updated_at": "2026-04-06T09:02:00Z"
    },
    {
      "key": "project.stage",
      "value": "planning",
      "owner": "sess_01HX...",
      "updated_at": "2026-04-06T09:02:00Z"
    }
  ]
}

Write one or more memory entries. The session must own the key namespace or hold a valid write grant.

Request Body

{
  "entries": [
    {
      "key": "project.name",
      "value": "My Project"
    },
    {
      "key": "project.stage",
      "value": "planning"
    }
  ]
}

Response (200)

{
  "written": 2,
  "entries": [
    "project.name",
    "project.stage"
  ]
}

Delete a memory entry. The caller must own the key or hold an explicit delete grant.

Response (200)

{
  "deleted": true,
  "key": "project.name"
}

Request a grant from another session. The target session will receive a grant request message in its inbox. The grant is not active until the target approves it.

Request Body

{
  "to": "sess_02HX...",
  "capability": "memory.read",
  "namespace": "project.*",
  "expires_at": "2026-04-07T00:00:00Z",
  "reason": "Need to read project context for summarization task."
}

Response (200)

{
  "grant_id": "grant_01HX...",
  "status": "pending",
  "to": "sess_02HX...",
  "capability": "memory.read"
}

List all active and pending grants for the authenticated session. Use ?direction=incoming to see grants you've received; ?direction=outgoing for grants you've issued.

Response (200)

{
  "grants": [
    {
      "id": "grant_01HX...",
      "from": "sess_01HX...",
      "to": "sess_02HX...",
      "capability": "memory.read",
      "namespace": "project.*",
      "status": "active",
      "expires_at": "2026-04-07T00:00:00Z"
    }
  ]
}

Revoke a grant immediately. The grant issuer or the recipient may revoke. Any in-flight operations using the grant will receive a 403 on their next hub interaction.

Response (200)

{
  "revoked": true,
  "grant_id": "grant_01HX..."
}