Getting Started

What you need

The live developer story is intentionally narrow: your app discovers user-specific PKM scopes, requests consent inside Kai, and reads only the slice the user approved. Start with the current runtime URLs, confirm your app identity in the developer console, and keep your integration scoped to one use case at a time.

• Kai app URL: https://uat.hushh.ai
• REST base URL: https://api.kai.hushh.ai/api/v1
• MCP URL: https://api.kai.hushh.ai/mcp
• npm bridge: @hushh/mcp@beta

Pick your runtime path

Use REST when you want an explicit HTTP workflow. Use remote MCP when your host supports it directly. Use the npm bridge when the host still expects a local stdio process.

REST quickstart

curl -s \
  "https://api.kai.hushh.ai/api/v1/user-scopes/user_123?token=<developer-token>"

Remote MCP quickstart

{
  "mcpServers": {
    "hushh-consent-remote": {
      "url": "https://api.kai.hushh.ai/mcp?token=<developer-token>"
    }
  }
}

Follow the consent flow

1. Discover. Call discover_user_domains or GET /api/v1/user-scopes/{user_id} to inspect the exact scopes available for this user right now.
2. Request. Send one discovered scope at a time to POST /api/v1/request-consent?token=... with your developer token and connector public-key bundle so Hushh can wrap the export key for client-side decryption.
3. Approve. The user reviews the request inside Kai, where your app display name and policy/support links are shown.
4. Read. After approval, use get_scoped_data and pass the original requested scope as expected_scope so the returned payload stays pinned to the slice you asked for.

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"
  }' \
  "https://api.kai.hushh.ai/api/v1/request-consent?token=<developer-token>"

Move into the console

After the runtime is wired, use the developer console to complete app identity, rotate tokens, and keep your support metadata current before asking real users for consent.

• One developer app is created per signed-in Kai account.
• One active developer token is kept at a time. Rotate it whenever you need a fresh credential.
• Consent prompts show your app identity, not a raw token or opaque runtime id.