Référence de l'API

Search API

Transforme une description de tâche en candidats classés. Les capacités bloquées sont renvoyées avec leurs motifs, afin que les agents comprennent ce qui a été filtré et pourquoi.

POST/v1/capabilities/search

Corps de la requête

Champ	Description
query	Description de la tâche en langage naturel.
agent_runtime	Environnement d'exécution appelant, par exemple claude-code, cursor. Utilisé pour un classement tenant compte de l'environnement d'exécution.
locale	Locale préférée, par exemple en, zh-CN.
risk_tolerance	read_only \| write \| destructive. Les candidats dépassant ce risque sont exclus ou rétrogradés.
latency_budget_ms	Écarter les candidats dont la latence attendue dépasse le budget.
require_freshness_seconds	Exiger des preuves de sonde plus récentes que cette fenêtre.
limit	Nombre maximal de candidats, 1–50. 10 par défaut.

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

Réponse

Trois catégories : recommended (à appeler), fallbacks (à utiliser en cas d'échec des recommandés) et blocked (exclus, avec codes de motif). Chaque élément noté comporte confidence, evidence_level et valid_until — un score sans provenance n'est jamais renvoyé.

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