API documentation

Authentication

The proposed API uses Authorization: Bearer YOUR_API_KEY, with application-scoped keys. Keep keys on the server. The browser demonstration uses bundled public samples, not an authenticated API.

Versioning

The API is proposed under /v1/. Stable major versions would accept additive optional fields; clients must ignore unknown fields. The draft contract can still change.

GET /v1/search

Find candidates by capability and location. Booking and payment happen directly with an endpoint after appropriate user authorization; the index is a discovery API.

Illustrative request:

GET /v1/search?capability=home.exterior&location=spokane-wa&level_min=1&limit=10 HTTP/1.1
Host: api.agentendpoints.org
Authorization: Bearer YOUR_API_KEY

Illustrative summary response. Search summaries are index projections, not complete Service Records. Fields such as probe latency and ranking explanations are index metadata.

{
  "query": {"capability": "home.exterior", "location": "spokane-wa", "level_min": 1, "limit": 10, "offset": 0},
  "ranking": "level_desc, verified_outcomes_desc, probe_p95_asc, price_fit, endpoint_id_asc",
  "total": 2,
  "results": [
    {
      "endpoint_id": "com.stainmydeck",
      "name": "StainMyDeck",
      "capability": "home.exterior.deck_staining",
      "coverage": {"type": "metro", "areas": ["spokane-wa"]},
      "level": 3,
      "status": "verified",
      "completion_rate_90d": null,
      "probe_p95_ms": 340,
      "why_ranked": "Illustrative L3; no independently verified outcome data",
      "record_url": "https://agentendpoints.org/records/com.stainmydeck"
    },
    {
      "endpoint_id": "com.getmygutters",
      "name": "GetMyGutters",
      "capability": "home.exterior.gutter_cleaning",
      "coverage": {"type": "metro", "areas": ["spokane-wa"]},
      "level": 2,
      "status": "probed",
      "completion_rate_90d": null,
      "probe_p95_ms": 410,
      "why_ranked": "Illustrative L2; no independently verified outcome data",
      "record_url": "https://agentendpoints.org/records/com.getmygutters"
    }
  ],
  "disclaimer": "Sample response — demonstration only. No live inventory."
}

This two-result response is an abbreviated API illustration, not the complete output of the browser dataset. Explore the complete local dataset.

GET /v1/records/

The planned retrieval call returns the complete Service Record: actions, coverage, pricing, verification, extensions, and any signed attestation. View the complete StainMyDeck sample or download its JSON.

GET /v1/records/com.stainmydeck HTTP/1.1
Host: api.agentendpoints.org
Authorization: Bearer YOUR_API_KEY

Errors

{
  "error": {
    "code": "invalid_capability",
    "message": "The requested capability is not a specified taxonomy node.",
    "hint": "Browse https://agentserviceschema.org/taxonomy",
    "request_id": "example-request-id",
    "documentation": "https://agentendpoints.org/docs#errors"
  }
}

Rate limits

Proposed, per-key quotas: Sandbox 1,000 requests/day; Builder 100,000/month; Scale 2,000,000/month; Enterprise custom. These are illustrative, not an SLA. Pricing and scope.

Code examples

These examples document the proposed API; it will not respond yet.

curl 'https://api.agentendpoints.org/v1/search?capability=home.exterior.deck_staining&location=spokane-wa' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Rust integration outline (reqwest and serde_json):

let client = reqwest::Client::new();
let response: serde_json::Value = client
    .get("https://api.agentendpoints.org/v1/search")
    .bearer_auth(std::env::var("AGENT_ENDPOINTS_API_KEY")?)
    .query(&[("capability", "home.exterior.deck_staining"),
             ("location", "spokane-wa")])
    .timeout(std::time::Duration::from_secs(10))
    .send().await?
    .error_for_status()?
    .json().await?;

Sponsored placement

Any future sponsored surface must disclose placement: "sponsored" and a visible Sponsored label. Payment does not change the ranking keys or conformance. Sponsorship is not sold in this preview.