API reference

Preflight API

Search results age. Preflight re-validates a specific action milliseconds before your agent calls it: live status, capacity, expected latency, and a bounded validity window.

POST/v1/capabilities/preflight

Request body

Field	Description
capability_id	Capability to check, from a search result.
action	The specific action to invoke. Scores are per action, not per service.
agent_runtime	Calling runtime identifier.
task_family	Task family for task-aware scoring, e.g. pdf_table_to_csv.
timeout_budget_ms	Your time budget; flagged if expected latency exceeds it.
risk_level	Risk you are willing to accept for this call.

request.sh

curl -X POST http://101.32.68.30/v1/capabilities/preflight \
  -H 'Authorization: Bearer $API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "capability_id": "cap_pdf_extract_table",
    "action": "extract_table",
    "agent_runtime": "claude-code",
    "task_family": "pdf_table_to_csv",
    "timeout_budget_ms": 10000,
    "risk_level": "read_only"
  }'

Response

status is one of ready, degraded, or blocked. Treat valid_for_seconds as a hard expiry: past it, preflight again instead of trusting a stale answer.

response.json

{
  "status": "ready",
  "invoke_now_score": 0.91,
  "confidence": 0.83,
  "valid_for_seconds": 45,
  "expected_p95_latency_ms": 3200,
  "capacity_state": "ok",
  "auth_state": "not_required",
  "warnings": [],
  "fallbacks": [
    {
      "capability_id": "cap_slow_but_local_cli",
      "reason": "local_execution_available"
    }
  ]
}