Developers

One consent-first developer surface

Build against Hushh with one canonical workflow: discover dynamic PKM scopes, request consent inside Kai, then read the approved slice through the same developer contract across REST and MCP.

Start Building API Reference

Start here

Use the typed runtime and the live docs together

Start Here

Intro, environment URLs, and the quickest path into the contract.

Overview

Trust model, environment URLs, and the one scalable developer story.

Choose Mode

Pick remote MCP, the REST API, or the npm bridge based on your host.

Dynamic Scopes

Scopes come from the user’s indexed Personal Knowledge Model, not a hardcoded list.

Consent Flow

Discover, request, approve in Kai, then read approved scoped data.

MCP

Remote MCP and npm launcher guidance for external agents.

Environment

Current runtime targets

Environment

Local

App URL

http://localhost:3000

API Base

http://127.0.0.1:8000/api/v1

MCP URL

http://127.0.0.1:8000/mcp

npm Package

@hushh/mcp@beta

Integration mode

Remote MCP

Point remote-capable hosts at the MCP endpoint and append ?token=<developer-token> to the URL.

Integration mode

REST API

Use the versioned developer API for dynamic scope discovery, consent requests, and status polling.

Integration mode

npm Bridge

Use the npm launcher when the host still expects a local stdio MCP process instead of HTTP MCP.

Documentation

Canonical guides and reference

Open developer console

Start Here

Getting Started

Begin your first Hushh developer integration with the consent-first API flow.

Open guide

Start Here

Developer Console Setup

Open guide

Reference

Agentic Endpoints

Explore the live test surface and production endpoint contract.

Open guide

Reference

Data & Resources

Understand how Hushh organizes consented data and access patterns.

Open guide

Guides

Use Cases

See how luxury, retail, and platform teams use the Hushh developer APIs.

Open guide

Reference

Support

Know what to send the Hushh team when troubleshooting an integration.

Open guide

Consent flow

Discover, request, approve, read

Step 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.

Step 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.

Step 3

Approve

The user reviews the request inside Kai, where your app display name and policy/support links are shown.

Step 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.

Public contract

Tools and scope grammar

Tools

discover_user_domainsrequest_consentcheck_consent_statusget_scoped_datavalidate_tokenlist_scopes

Scopes

pkm.readpkm.writeattr.{domain}.*attr.{domain}.{subintent}.*attr.{domain}.{path}

Scope notes

Scopes are still evolving as Kai adds richer PKM coverage and tighter domain metadata.
Discover available scopes per user at runtime instead of hardcoding a fixed universal list.
The current Kai test-user shape is mostly financial, so early community integrations should expect financial-first examples.
A broader active grant can satisfy a narrower request, but a narrower active grant never auto-upgrades to a broader parent scope.
The /developers surface stays technical. A separate consumer-facing PKM transparency view now lives in PKM Agent Lab.

REST quickstart

Versioned API entry points

MethodPathPurpose

GET/api/v1Top-level versioned contract summary and portal entry points.

GET/api/v1/list-scopesCanonical dynamic scope grammar and discovery guidance.

GET/api/v1/tool-catalogCurrent tool visibility for public beta or a specific developer app.

GET/api/v1/user-scopes/{user_id}Discovered scope strings and available domains for a specific user.

GET/api/v1/consent-statusPoll the latest status for a scope or request id.

POST/api/v1/request-consentCreate or reuse a consent request for one discovered scope.

Quick snippets

REST and MCP starter commands

Discover scopes

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

Request consent

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 agent",
    "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>"

Remote MCP

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

npm bridge

{
  "mcpServers": {
    "hushh-consent": {
      "command": "npx",
      "args": ["-y", "@hushh/mcp@beta"],
      "env": {
        "CONSENT_API_URL": "http://127.0.0.1:8000",
        "HUSHH_DEVELOPER_TOKEN": "<developer-token>"
      }
    }
  }
}

Developer access

Workspace guardrails

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 agent id.

FAQ

Common integration questions

Are scopes fixed?

No. Scopes are discovered per user from the indexed Personal Knowledge Model. Always discover first, then request one of the returned scope strings.

Does developer login grant data access?

No. Login enables your developer workspace and app token. User data still requires a separate consent decision inside Kai.

What is the one scalable read path?

Use get_scoped_data after approval. The public developer contract does not expose named data getter variants.

What happens if I ask for a narrower scope while I already have a broader one?

Hushh reuses the existing broader active grant and returns it immediately, but you should still pass the narrower scope as expected_scope when reading so the payload stays sliced to the narrower branch you asked for.

What happens if I ask for a broader scope while I already have a narrower one?

That is a privilege increase, so it still requires fresh user approval in Kai. After approval, the broader token becomes canonical and the older narrower token is superseded in the audit trail.

Where does consent approval happen?

Inside Kai. Your external agent requests consent, but the user approves or denies it in the Hushh product surface.

Do raw REST callers need to send a connector key?

Yes. The raw HTTP developer API requires connector_public_key, connector_key_id, and connector_wrapping_alg so Hushh can wrap the export key back to your client. The MCP tool hides that detail because the Hushh MCP server manages the connector keypair for you.

When should I use remote MCP versus npm?

Use remote MCP when your host supports HTTP MCP directly. Use the npm bridge for hosts that still require a local stdio process.

Sample payload

Sample discovery response

Sanitized example based on the current Kai-style test user. Right now the discovered surface is primarily financial.

{
  "user_id": "kai_test_user",
  "available_domains": ["financial"],
  "scopes": [
    "pkm.read",
    "attr.financial.*",
    "attr.financial.portfolio.*",
    "attr.financial.profile.*",
    "attr.financial.documents.*",
    "attr.financial.analysis_history.*",
    "attr.financial.runtime.*",
    "attr.financial.analysis.decisions.*"
  ],
  "source": "pkm_index_v2 + manifest-backed scope discovery"
}

Sample payload

Sample scoped data response

Illustrative `get_scoped_data` shape for an approved `attr.financial.*` grant, using the current financial summary fields we have now.

{
  "status": "success",
  "user_id": "kai_test_user",
  "scope": "attr.financial.*",
  "consent_verified": true,
  "data": {
    "financial": {
      "intent_map": [
        "portfolio",
        "profile",
        "documents",
        "analysis_history",
        "runtime",
        "analysis.decisions"
      ],
      "item_count": 19,
      "risk_score": 4,
      "risk_bucket": "aggressive",
      "risk_profile": "balanced",
      "active_source": "statement",
      "holdings_count": 19,
      "documents_count": 1,
      "profile_completed": true,
      "portfolio_risk_bucket": "aggressive",
      "investable_positions_count": 19,
      "last_statement_total_value": 6951964.54,
      "domain_contract_version": 1
    }
  },
  "top_level_keys": ["financial"],
  "zero_knowledge": true
}

Sample payload

Sample reused broader grant

If the app already holds a broader active grant and asks for a narrower branch, the request is reused immediately and the response tells you which broader scope is covering the ask.

{
  "status": "already_granted",
  "scope": "attr.financial.analytics.quality_metrics",
  "requested_scope": "attr.financial.analytics.quality_metrics",
  "granted_scope": "attr.financial.analytics.*",
  "coverage_kind": "superset",
  "covered_by_existing_grant": true,
  "consent_token": "HCT:...",
  "expires_at": 1760000000000
}