API reference

Search API

Turns a task description into ranked candidates. Blocked capabilities are returned with reasons, so agents understand what was filtered and why.

POST/v1/capabilities/search

Request body

Field	Description
query	Natural-language task description.
agent_runtime	Calling runtime, e.g. claude-code, cursor. Used for runtime-aware ranking.
locale	Preferred locale, e.g. en, zh-CN.
risk_tolerance	read_only \| write \| destructive. Candidates above this risk are excluded or demoted.
latency_budget_ms	Drop candidates whose expected latency exceeds the budget.
require_freshness_seconds	Require probe evidence newer than this window.
limit	Max candidates, 1–50. Default 10.

request.sh

curl -X POST http://101.32.68.30/v1/capabilities/search \
  -H 'Authorization: Bearer $API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "extract tables from a PDF into CSV",
    "agent_runtime": "claude-code",
    "locale": "en",
    "risk_tolerance": "read_only",
    "latency_budget_ms": 10000,
    "limit": 10
  }'

Response

Three buckets: recommended (call these), fallbacks (use when recommended fail), and blocked (excluded, with reason codes). Every scored item carries confidence, evidence_level and valid_until — a score without provenance is never returned.

response.json

{
  "query_id": "q_123",
  "recommended": [
    {
      "capability_id": "cap_pdf_extract_table",
      "action": "extract_table",
      "interface_type": "mcp_remote",
      "invoke_now_score": 0.87,
      "task_success_score": 0.82,
      "confidence": 0.76,
      "status": "routeable",
      "valid_until": "2026-06-10T12:31:00Z",
      "evidence_level": "E4_protocol_probe_passed",
      "risk_level": "read_only",
      "requires_user_confirmation": false,
      "reason_codes": ["recent_probe_ok", "static_audit_passed"],
      "warnings": ["low_real_invocation_sample"]
    }
  ],
  "fallbacks": [
    {
      "capability_id": "cap_slow_but_local_cli",
      "action": "extract_table",
      "interface_type": "cli",
      "invoke_now_score": 0.61,
      "confidence": 0.70,
      "status": "fallback",
      "evidence_level": "E3_sandbox_install_passed",
      "reason_codes": ["local_execution_available"],
      "warnings": ["high_latency_observed"]
    }
  ],
  "blocked": [
    {
      "capability_id": "cap_prompt_injection_skill",
      "reason_codes": ["prompt_injection_detected"]
    }
  ]
}