API reference

Every address in the contract registry — generated from @quickable/contract on every build, so it can never drift from the code.

Generated page. Rendered by apps/docs/scripts/generate-api-reference.mjs from expandRegistry() in @quickable/gateway — the same expansion the running gateway builds its REST routes and MCP tools from. Do not edit by hand; nothing here is hand-written (AG-2).

The one API

Every application operation is a typed NATS address — a subject plus zod request/reply schemas — in the api registry of @quickable/contract. The REST and MCP surfaces below are mechanical projections of that registry:

REST: every address is POST /v1/<subject with dots as slashes>. Pure-read addresses (flagged in the registry, never mutations) also get a GET alias whose query string becomes the request object. Wildcard subject tokens become path parameters (api.rt.*.intent → /v1/rt/:app/intent).
MCP: every address is one tool at POST /mcp (streamable HTTP, stateless). The tool name is the subject with dots as underscores, wildcard token dropped — it becomes an input field instead (api.rt.*.intent → api_rt_intent with an app property).

Both carry Authorization: Bearer <nats-user-jwt> — a bearer_token:true user JWT you already possess (see Auth & namespaces). The gateway opens a NATS connection as that caller; the broker enforces every permission. The single exception is api.signup: it is the pre-identity bootstrap and needs no bearer.

Reply envelope

Every reply — REST body, MCP tool text, native NATS — is the same discriminated envelope:

{ "ok": true, "data": { /* the address's reply shape */ } }

{ "ok": false, "error": { "code": "conflict", "message": "…", "correlationId": "…" } }

Error codes are a finite, classified set: invalid_input, denied, not_found, conflict, already_exists, invite_required, rate_limited, unavailable, timeout, internal. A wire reply never carries a raw internal exception.

REST example (curl)

# create an app (owner bearer), then patch material (material or owner bearer)
curl -s -X POST "$BASE/v1/app/create" \
  -H "Authorization: Bearer $BEARER" -H "Content-Type: application/json" \
  -d '{"name":"scoreboard"}'

curl -s -X POST "$BASE/v1/material/patch" \
  -H "Authorization: Bearer $BEARER" -H "Content-Type: application/json" \
  -d '{"app":"scoreboard","path":"App.tsx","baseRev":42,"ops":[
        {"op":"replace","b":"3f2a9c1d8e7b6a5f4c3d2e1f0a9b8c7d","src":"export const MAX = 10;"}]}'

MCP example (tool call)

Point an MCP client at https://<domain>/mcp with the same bearer header. Over raw streamable HTTP a tool call is one JSON-RPC POST:

curl -s -X POST "$BASE/mcp" \
  -H "Authorization: Bearer $BEARER" \
  -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
    "params": { "name": "api_app_create", "arguments": { "name": "scoreboard" } }
  }'

Parameterized tools take the path token as an input field, e.g. api_session_token with { "scope": "material" }.

Addresses

`api.signup`

Mint a namespace account + owner/material credentials.

Authorization: owner — owner credential only (bootstrap: served pre-identity, no bearer required)
REST: POST /v1/signup
MCP tool: api_signup

Request

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "handle": {
      "type": "string",
      "minLength": 3,
      "maxLength": 48,
      "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$"
    },
    "inviteToken": {
      "type": "string"
    },
    "ownerUserPublicKey": {
      "type": "string",
      "pattern": "^U[A-Z2-7]{55}$"
    },
    "materialUserPublicKey": {
      "type": "string",
      "pattern": "^U[A-Z2-7]{55}$"
    }
  },
  "required": [
    "ownerUserPublicKey"
  ]
}

Reply data (inside the ok: true envelope)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ns": {
      "type": "string",
      "minLength": 3,
      "maxLength": 48,
      "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$"
    },
    "accountPublicKey": {
      "type": "string"
    },
    "ownerUserJwt": {
      "type": "string"
    },
    "ownerInboxPrefix": {
      "type": "string"
    },
    "materialUserJwt": {
      "type": "string"
    },
    "materialInboxPrefix": {
      "type": "string"
    }
  },
  "required": [
    "ns",
    "accountPublicKey",
    "ownerUserJwt",
    "ownerInboxPrefix"
  ],
  "additionalProperties": false
}

`api.identity.whoami`

Echo the broker-captured caller identity.

Authorization: material — material or owner credential
REST: POST /v1/identity/whoami · GET /v1/identity/whoami (query string → request)
MCP tool: api_identity_whoami

Request

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {}
}

Reply data (inside the ok: true envelope)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "acctPub": {
      "type": "string"
    },
    "ns": {
      "type": "string",
      "minLength": 3,
      "maxLength": 48,
      "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$"
    }
  },
  "required": [
    "acctPub"
  ],
  "additionalProperties": false
}

`api.app.create`

Create an app in the caller's namespace (KV CAS).

Authorization: owner — owner credential only
REST: POST /v1/app/create
MCP tool: api_app_create

Request

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 32,
      "pattern": "^[a-z][a-z0-9-]*$"
    },
    "entry": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256
    },
    "settings": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "$ref": "#/$defs/__schema0"
      }
    }
  },
  "required": [
    "name"
  ],
  "$defs": {
    "__schema0": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/__schema0"
          }
        },
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema0"
          }
        }
      ]
    }
  }
}

Reply data (inside the ok: true envelope)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "app": {
      "type": "string",
      "minLength": 1,
      "maxLength": 32,
      "pattern": "^[a-z][a-z0-9-]*$"
    },
    "manifest": {
      "type": "object",
      "properties": {
        "app": {
          "type": "string",
          "minLength": 1,
          "maxLength": 32,
          "pattern": "^[a-z][a-z0-9-]*$"
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 32,
          "pattern": "^[a-z][a-z0-9-]*$"
        },
        "entry": {
          "type": "string",
          "minLength": 1,
          "maxLength": 256
        },
        "files": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512
          }
        },
        "currentBuildHash": {
          "type": "string"
        },
        "currentBuildRev": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "settings": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema0"
          }
        },
        "createdAt": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "updatedAt": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        }
      },
      "required": [
        "app",
        "name",
        "entry",
        "files",
        "settings",
        "createdAt",
        "updatedAt"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "app",
    "manifest"
  ],
  "additionalProperties": false,
  "$defs": {
    "__schema0": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/__schema0"
          }
        },
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema0"
          }
        }
      ]
    }
  }
}

`api.app.list`

List the caller namespace's apps.

Authorization: material — material or owner credential
REST: POST /v1/app/list · GET /v1/app/list (query string → request)
MCP tool: api_app_list

Request

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {}
}

Reply data (inside the ok: true envelope)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "apps": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "app": {
            "type": "string",
            "minLength": 1,
            "maxLength": 32,
            "pattern": "^[a-z][a-z0-9-]*$"
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 32,
            "pattern": "^[a-z][a-z0-9-]*$"
          },
          "entry": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "files": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 512
            }
          },
          "currentBuildHash": {
            "type": "string"
          },
          "currentBuildRev": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 9007199254740991
          },
          "settings": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "$ref": "#/$defs/__schema0"
            }
          },
          "createdAt": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          },
          "updatedAt": {
            "type": "integer",
            "minimum": 0,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "app",
          "name",
          "entry",
          "files",
          "settings",
          "createdAt",
          "updatedAt"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "apps"
  ],
  "additionalProperties": false,
  "$defs": {
    "__schema0": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/__schema0"
          }
        },
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema0"
          }
        }
      ]
    }
  }
}

`api.app.info`

Fetch one app's manifest.

Authorization: material — material or owner credential
REST: POST /v1/app/info · GET /v1/app/info (query string → request)
MCP tool: api_app_info

Request

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "app": {
      "type": "string",
      "minLength": 1,
      "maxLength": 32,
      "pattern": "^[a-z][a-z0-9-]*$"
    }
  },
  "required": [
    "app"
  ]
}

Reply data (inside the ok: true envelope)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "manifest": {
      "type": "object",
      "properties": {
        "app": {
          "type": "string",
          "minLength": 1,
          "maxLength": 32,
          "pattern": "^[a-z][a-z0-9-]*$"
        },
        "name": {
          "type": "string",
          "minLength": 1,
          "maxLength": 32,
          "pattern": "^[a-z][a-z0-9-]*$"
        },
        "entry": {
          "type": "string",
          "minLength": 1,
          "maxLength": 256
        },
        "files": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1,
            "maxLength": 512
          }
        },
        "currentBuildHash": {
          "type": "string"
        },
        "currentBuildRev": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        "settings": {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema0"
          }
        },
        "createdAt": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        },
        "updatedAt": {
          "type": "integer",
          "minimum": 0,
          "maximum": 9007199254740991
        }
      },
      "required": [
        "app",
        "name",
        "entry",
        "files",
        "settings",
        "createdAt",
        "updatedAt"
      ],
      "additionalProperties": false
    }
  },
  "required": [
    "manifest"
  ],
  "additionalProperties": false,
  "$defs": {
    "__schema0": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/__schema0"
          }
        },
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema0"
          }
        }
      ]
    }
  }
}

`api.app.delete`

Delete an app from the caller's namespace.

Authorization: owner — owner credential only
REST: POST /v1/app/delete
MCP tool: api_app_delete

Request

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "app": {
      "type": "string",
      "minLength": 1,
      "maxLength": 32,
      "pattern": "^[a-z][a-z0-9-]*$"
    }
  },
  "required": [
    "app"
  ]
}

Reply data (inside the ok: true envelope)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}

`api.app.settings.get`

Read an app's settings.

Authorization: material — material or owner credential
REST: POST /v1/app/settings/get · GET /v1/app/settings/get (query string → request)
MCP tool: api_app_settings_get

Request

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "app": {
      "type": "string",
      "minLength": 1,
      "maxLength": 32,
      "pattern": "^[a-z][a-z0-9-]*$"
    }
  },
  "required": [
    "app"
  ]
}

Reply data (inside the ok: true envelope)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "settings": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "$ref": "#/$defs/__schema0"
      }
    }
  },
  "required": [
    "settings"
  ],
  "additionalProperties": false,
  "$defs": {
    "__schema0": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/__schema0"
          }
        },
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema0"
          }
        }
      ]
    }
  }
}

`api.app.settings.set`

Replace an app's settings.

Authorization: owner — owner credential only
REST: POST /v1/app/settings/set
MCP tool: api_app_settings_set

Request

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "app": {
      "type": "string",
      "minLength": 1,
      "maxLength": 32,
      "pattern": "^[a-z][a-z0-9-]*$"
    },
    "settings": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "$ref": "#/$defs/__schema0"
      }
    }
  },
  "required": [
    "app",
    "settings"
  ],
  "$defs": {
    "__schema0": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/__schema0"
          }
        },
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema0"
          }
        }
      ]
    }
  }
}

Reply data (inside the ok: true envelope)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "settings": {
      "type": "object",
      "propertyNames": {
        "type": "string"
      },
      "additionalProperties": {
        "$ref": "#/$defs/__schema0"
      }
    }
  },
  "required": [
    "settings"
  ],
  "additionalProperties": false,
  "$defs": {
    "__schema0": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/__schema0"
          }
        },
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema0"
          }
        }
      ]
    }
  }
}

`api.material.list`

List an app's material file paths.

Authorization: material — material or owner credential
REST: POST /v1/material/list · GET /v1/material/list (query string → request)
MCP tool: api_material_list

Request

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "app": {
      "type": "string",
      "minLength": 1,
      "maxLength": 32,
      "pattern": "^[a-z][a-z0-9-]*$"
    }
  },
  "required": [
    "app"
  ]
}

Reply data (inside the ok: true envelope)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "files": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 256,
        "pattern": "^[A-Za-z0-9_][A-Za-z0-9._/-]*$"
      }
    }
  },
  "required": [
    "files"
  ],
  "additionalProperties": false
}

`api.material.get`

Read one material file, block-anchor annotated.

Authorization: material — material or owner credential
REST: POST /v1/material/get · GET /v1/material/get (query string → request)
MCP tool: api_material_get

Request

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "app": {
      "type": "string",
      "minLength": 1,
      "maxLength": 32,
      "pattern": "^[a-z][a-z0-9-]*$"
    },
    "path": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256,
      "pattern": "^[A-Za-z0-9_][A-Za-z0-9._/-]*$"
    }
  },
  "required": [
    "app",
    "path"
  ]
}

Reply data (inside the ok: true envelope)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "path": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256,
      "pattern": "^[A-Za-z0-9_][A-Za-z0-9._/-]*$"
    },
    "content": {
      "type": "string"
    },
    "baseRev": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "path",
    "content",
    "baseRev"
  ],
  "additionalProperties": false
}

`api.material.put`

Create or fully replace one material file.

Authorization: material — material or owner credential
REST: POST /v1/material/put
MCP tool: api_material_put

Request

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "app": {
      "type": "string",
      "minLength": 1,
      "maxLength": 32,
      "pattern": "^[a-z][a-z0-9-]*$"
    },
    "path": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256,
      "pattern": "^[A-Za-z0-9_][A-Za-z0-9._/-]*$"
    },
    "src": {
      "type": "string",
      "maxLength": 512000
    }
  },
  "required": [
    "app",
    "path",
    "src"
  ]
}

Reply data (inside the ok: true envelope)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "rev": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "rev"
  ],
  "additionalProperties": false
}

`api.material.patch`

Block-patch one material file (CAS on baseRev).

Authorization: material — material or owner credential
REST: POST /v1/material/patch
MCP tool: api_material_patch

Request

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "app": {
      "type": "string",
      "minLength": 1,
      "maxLength": 32,
      "pattern": "^[a-z][a-z0-9-]*$"
    },
    "path": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256,
      "pattern": "^[A-Za-z0-9_][A-Za-z0-9._/-]*$"
    },
    "baseRev": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "ops": {
      "minItems": 1,
      "maxItems": 64,
      "type": "array",
      "items": {
        "oneOf": [
          {
            "type": "object",
            "properties": {
              "op": {
                "type": "string",
                "const": "replace"
              },
              "b": {
                "type": "string",
                "pattern": "^[0-9a-f]{32}$"
              },
              "src": {
                "type": "string",
                "maxLength": 512000
              }
            },
            "required": [
              "op",
              "b",
              "src"
            ]
          },
          {
            "type": "object",
            "properties": {
              "op": {
                "type": "string",
                "const": "insert_after"
              },
              "b": {
                "type": "string",
                "pattern": "^[0-9a-f]{32}$"
              },
              "src": {
                "type": "string",
                "maxLength": 512000
              }
            },
            "required": [
              "op",
              "b",
              "src"
            ]
          },
          {
            "type": "object",
            "properties": {
              "op": {
                "type": "string",
                "const": "delete"
              },
              "b": {
                "type": "string",
                "pattern": "^[0-9a-f]{32}$"
              }
            },
            "required": [
              "op",
              "b"
            ]
          }
        ]
      }
    }
  },
  "required": [
    "app",
    "path",
    "baseRev",
    "ops"
  ]
}

Reply data (inside the ok: true envelope)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "anyOf": [
    {
      "type": "object",
      "properties": {
        "rev": {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        }
      },
      "required": [
        "rev"
      ],
      "additionalProperties": false
    },
    {
      "type": "object",
      "properties": {
        "conflict": {
          "type": "object",
          "properties": {
            "baseRev": {
              "type": "integer",
              "exclusiveMinimum": 0,
              "maximum": 9007199254740991
            },
            "currentRev": {
              "type": "integer",
              "exclusiveMinimum": 0,
              "maximum": 9007199254740991
            },
            "staleBlocks": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "b": {
                    "type": "string",
                    "pattern": "^[0-9a-f]{32}$"
                  },
                  "content": {
                    "type": "string"
                  }
                },
                "required": [
                  "b",
                  "content"
                ],
                "additionalProperties": false
              }
            },
            "unknownAnchors": {
              "type": "array",
              "items": {
                "type": "string",
                "pattern": "^[0-9a-f]{32}$"
              }
            }
          },
          "required": [
            "baseRev",
            "currentRev",
            "staleBlocks",
            "unknownAnchors"
          ],
          "additionalProperties": false
        }
      },
      "required": [
        "conflict"
      ],
      "additionalProperties": false
    }
  ]
}

`api.session.*.mint`

Mint an app-scoped bearer bridge session.

Authorization: owner — owner credential only
REST: POST /v1/session/:app/mint
MCP tool: api_session_mint (the app subject token is an input property)

Request

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ttlSeconds": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 3600
    },
    "app": {
      "type": "string",
      "pattern": "^[a-z0-9-]{1,32}$",
      "description": "the app subject token"
    }
  },
  "required": [
    "app"
  ]
}

Reply data (inside the ok: true envelope)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "app": {
      "type": "string",
      "minLength": 1,
      "maxLength": 32,
      "pattern": "^[a-z][a-z0-9-]*$"
    },
    "bridgeJwt": {
      "type": "string"
    },
    "exp": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "inboxPrefix": {
      "type": "string"
    }
  },
  "required": [
    "app",
    "bridgeJwt",
    "exp",
    "inboxPrefix"
  ],
  "additionalProperties": false
}

`api.session.*.resume`

Resume an app-scoped bridge session.

Authorization: bridge — bridge (app session) credential
REST: POST /v1/session/:app/resume
MCP tool: api_session_resume (the app subject token is an input property)

Request

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "app": {
      "type": "string",
      "pattern": "^[a-z0-9-]{1,32}$",
      "description": "the app subject token"
    }
  },
  "required": [
    "app"
  ]
}

Reply data (inside the ok: true envelope)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "app": {
      "type": "string",
      "minLength": 1,
      "maxLength": 32,
      "pattern": "^[a-z][a-z0-9-]*$"
    },
    "acctPub": {
      "type": "string"
    }
  },
  "required": [
    "app",
    "acctPub"
  ],
  "additionalProperties": false
}

`api.session.token.*`

Mint a short-lived namespace bearer (scope = subject token).

Authorization: material — material or owner credential
REST: POST /v1/session/token/:scope
MCP tool: api_session_token (the scope subject token is an input property)

Request

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ttlSeconds": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 3600
    },
    "scope": {
      "type": "string",
      "pattern": "^[a-z0-9-]{1,32}$",
      "description": "the scope subject token"
    }
  },
  "required": [
    "scope"
  ]
}

Reply data (inside the ok: true envelope)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "scope": {
      "type": "string",
      "enum": [
        "owner",
        "material"
      ]
    },
    "bearerJwt": {
      "type": "string"
    },
    "exp": {
      "type": "integer",
      "minimum": -9007199254740991,
      "maximum": 9007199254740991
    },
    "inboxPrefix": {
      "type": "string"
    }
  },
  "required": [
    "scope",
    "bearerJwt",
    "exp",
    "inboxPrefix"
  ],
  "additionalProperties": false
}

`api.rt.*.intent`

Apply one server-authoritative intent (CAS, idempotent within the dedup window).

Authorization: bridge — bridge (app session) credential
REST: POST /v1/rt/:app/intent
MCP tool: api_rt_intent (the app subject token is an input property)

Request

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "cmdId": {
      "type": "string",
      "minLength": 8,
      "maxLength": 64,
      "pattern": "^[A-Za-z0-9_-]+$"
    },
    "type": {
      "type": "string",
      "minLength": 1,
      "maxLength": 32,
      "pattern": "^[a-z][a-z0-9_-]*$"
    },
    "payload": {
      "$ref": "#/$defs/__schema0"
    },
    "app": {
      "type": "string",
      "pattern": "^[a-z0-9-]{1,32}$",
      "description": "the app subject token"
    }
  },
  "required": [
    "cmdId",
    "type",
    "payload",
    "app"
  ],
  "$defs": {
    "__schema0": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/__schema0"
          }
        },
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema0"
          }
        }
      ]
    }
  }
}

Reply data (inside the ok: true envelope)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "rev": {
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "result": {
      "$ref": "#/$defs/__schema0"
    },
    "dedup": {
      "type": "boolean"
    }
  },
  "required": [
    "rev",
    "result",
    "dedup"
  ],
  "additionalProperties": false,
  "$defs": {
    "__schema0": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/__schema0"
          }
        },
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema0"
          }
        }
      ]
    }
  }
}

`api.rt.*.resume`

Fetch current rt state + deltas since fromRev.

Authorization: bridge — bridge (app session) credential
REST: POST /v1/rt/:app/resume
MCP tool: api_rt_resume (the app subject token is an input property)

Request

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "fromRev": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "app": {
      "type": "string",
      "pattern": "^[a-z0-9-]{1,32}$",
      "description": "the app subject token"
    }
  },
  "required": [
    "fromRev",
    "app"
  ]
}

Reply data (inside the ok: true envelope)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "state": {
      "$ref": "#/$defs/__schema0"
    },
    "rev": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "deltas": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "rev": {
            "type": "integer",
            "exclusiveMinimum": 0,
            "maximum": 9007199254740991
          },
          "cmdId": {
            "type": "string",
            "minLength": 8,
            "maxLength": 64,
            "pattern": "^[A-Za-z0-9_-]+$"
          },
          "type": {
            "type": "string",
            "minLength": 1,
            "maxLength": 32,
            "pattern": "^[a-z][a-z0-9_-]*$"
          },
          "payload": {
            "$ref": "#/$defs/__schema0"
          },
          "result": {
            "$ref": "#/$defs/__schema0"
          }
        },
        "required": [
          "rev",
          "cmdId",
          "type",
          "payload",
          "result"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "state",
    "rev",
    "deltas"
  ],
  "additionalProperties": false,
  "$defs": {
    "__schema0": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/__schema0"
          }
        },
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema0"
          }
        }
      ]
    }
  }
}

`api.rt.*.cursor`

Ephemeral cursor-class fanout (no KV write).

Authorization: bridge — bridge (app session) credential
REST: POST /v1/rt/:app/cursor
MCP tool: api_rt_cursor (the app subject token is an input property)

Request

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "payload": {
      "$ref": "#/$defs/__schema0"
    },
    "app": {
      "type": "string",
      "pattern": "^[a-z0-9-]{1,32}$",
      "description": "the app subject token"
    }
  },
  "required": [
    "payload",
    "app"
  ],
  "$defs": {
    "__schema0": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "number"
        },
        {
          "type": "boolean"
        },
        {
          "type": "null"
        },
        {
          "type": "array",
          "items": {
            "$ref": "#/$defs/__schema0"
          }
        },
        {
          "type": "object",
          "propertyNames": {
            "type": "string"
          },
          "additionalProperties": {
            "$ref": "#/$defs/__schema0"
          }
        }
      ]
    }
  }
}

Reply data (inside the ok: true envelope)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "ok": {
      "type": "boolean",
      "const": true
    }
  },
  "required": [
    "ok"
  ],
  "additionalProperties": false
}

On this page