Agent Kai API Reference

Overview

Agent Kai is the canonical developer reference for consent-first reads from the Personal Knowledge Model. The important pattern is stable: discover scopes from the live PKM runtime, request one scope at a time, wait for approval inside Kai, then read only the slice the user approved.

This page translates the runtime fact sheet into developer language. It is intentionally documentation-only: enough schema and flow detail to explain endpoint behavior, without exposing secrets, row data, or operational internals that do not belong on a public site.

Runtime architecture

Kai sits between the user-facing approval experience and the PKM runtime. The public API surface is small on purpose: the app, REST base, and MCP endpoint all describe the same consent-first system from different integration angles.

Core PKM data plane

These tables explain discovery, manifests, scope exposure, and encrypted segment storage. They are the canonical data plane behind Kai scope discovery.

Shared app records that matter to developers

Developers do not interact with these tables directly, but they explain why approval, export wrapping, and runtime identity behave the way they do.

Legacy transition tables

Consent and IAM model

Kai uses separate layers for developer identity, user approval, and export readiness. A developer token proves who is asking. Consent records prove what the user approved. Vault-related records determine whether the approved payload can be wrapped back to the requesting connector safely.

• Developer app state. developer_applications, developer_apps, and developer_tokens describe app identity and token posture.
• Consent state. consent_audit, consent_exports, and template records explain whether a scope was granted, reused, or expired.
• Vault readiness. vault_key_wrappers and vault_keys explain whether export wrapping and onboarding state are ready.
• Runtime posture. runtime_persona_state explains persona and readiness context when Kai behavior depends on the active runtime state.

Endpoint flow and order of operations

The Kai path should be treated as ordered operations, not a collection of unrelated endpoints. Start with discovery, move into a narrow consent request, poll for approval, then decide whether the rest of your integration should stay in REST or move into MCP.

{
  "mcpServers": {
    "hushh-consent-remote": {
      "url": "http://127.0.0.1:8000/mcp?token=<developer-token>"
    }
  }
}

curl -s \
  "http://127.0.0.1:8000/api/v1/user-scopes/user_123?token=<developer-token>"

curl -s -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_123",
    "scope": "attr.financial.*",
    "expiry_hours": 24,
    "approval_timeout_minutes": 60,
    "reason": "Show portfolio-aware insights inside the user's external app",
    "connector_public_key": "<base64-encoded-x25519-public-key>",
    "connector_key_id": "connector-key-1",
    "connector_wrapping_alg": "X25519-AES256-GCM"
  }' \
  "http://127.0.0.1:8000/api/v1/request-consent?token=<developer-token>"

curl -s \
  "http://127.0.0.1:8000/api/v1/consent-status?user_id=user_123&scope=attr.financial.*&token=<developer-token>"

Database and runtime factors that matter

Developers do not need raw table access, but they do need to understand why scope discovery, approval, export wrapping, and onboarding readiness behave differently across users and environments.

Browser-safe vs backend-only boundaries

Browser-safe testing ends where developer tokens, connector wrapping metadata, or direct financial aggregation begin. Keep the developer-facing proxy for guided testing, but keep consent creation and financial reads on your backend.

Examples and common failure points

The most common integration issues come from skipping discovery, over-requesting scopes, or treating migration-era surfaces as if they were canonical. Use the runtime sequence below as the baseline for reviews and troubleshooting.

• Discover first. Do not hardcode universal scopes when the runtime exposes them per user.
• Request one scope at a time so approval language and audit state stay understandable.
• Do not treat legacy transition tables as destinations for new data flows or exports.
• Keep connector wrapping fields present on request-consent or your export handoff will fail later even if the approval is granted.
• Keep A2A and MuleSoft guidance in the separate Agentic APIs track.