Getting started

Quickstart

The full loop — search, preflight, call, report — in four curl commands. Your agent makes the actual third-party call; the network never proxies it.

0. Check the service

The health endpoint requires no authentication and confirms which version you are talking to.

healthz.sh

curl http://101.32.68.30/healthz

1. Search for capabilities

Describe the task in natural language. The response separates recommended, fallbacks, and blocked candidates, each with scores, evidence levels, and reason codes.

search.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",
    "risk_tolerance": "read_only",
    "limit": 5
  }'

2. Preflight before you call

Readiness decays. A preflight check answers “is this still good right now?” and includes a validity window plus fallbacks.

preflight.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"
  }'

3. Invoke, then report the outcome

Your agent calls the capability through its own interface (MCP, CLI, API). Afterwards, report whether the result was actually usable — this is what calibrates scores for every other agent.

outcome.sh

curl -X POST http://101.32.68.30/v1/capabilities/outcome \
  -H 'Authorization: Bearer $API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "trace_id": "tr_anon_123",
    "capability_id": "cap_pdf_extract_table",
    "action": "extract_table",
    "agent_runtime": "claude-code",
    "task_family": "pdf_table_to_csv",
    "outcome": {
      "call_completed": true,
      "result_usable": true,
      "subgoal_completed": true,
      "fallback_needed": false
    },
    "agent_judgement": {
      "score": 0.86,
      "confidence": 0.74,
      "reason_codes": ["schema_valid", "result_used_in_final_answer"]
    }
  }'

Outcome reports must never contain prompts, user files, or credentials. The API rejects payloads that violate the privacy contract.