Agent Kai API

Data & Resources

Understand PKM domains, scope discovery, and consent-aware payload shape.

This page belongs to the Kai runtime lane: PKM, consent approval inside Kai, REST, and MCP. The separate Agentic APIs lane covers A2A, MuleSoft, and browser-proxy flows.

PKM domains

The public developer surface is PKM-first. You do not start from a hardcoded global catalog of business objects. You discover what exists for a specific user, then request access to the exact branch you need.

Tool and scope grammar

These tool names and scope patterns are the public contract today.

discover_user_domains
request_consent
check_consent_status
get_scoped_data
validate_token
list_scopes

pkm.read
pkm.write
attr.{domain}.*
attr.{domain}.{subintent}.*
attr.{domain}.{path}

Payload expectations

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 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 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
}

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

PreviousAgent Kai API Reference