Service Discovery

Agents discover services by capability via GET /api/discover, public, no auth required, cached 60 seconds. Results include catalog signatures for trustless local verification.

··

The Discovery Endpoint

Authentication

None required

Fully public endpoint.

Cache TTL (time-to-live)

60 seconds

CDN-cached for performance.

Rate limit

None

No rate limiting on discovery.

bash

GET /api/discover?capability=flights:*&max_price_cents=100&min_uptime_bp=9990&sort=price_asc&limit=10

Query Parameters

Parameter	Type	Description
capability	string (required)	Permission key to search. Supports wildcards: flights:* matches flights:search, flights:book, etc.
max_price_cents	number	Maximum per-call price in cents. Filter out expensive services.
min_uptime_bp	number	Minimum uptime in basis points (9990 = 99.9%).
max_response_time_ms	number	Maximum P95 response time in milliseconds.
pricing_model	string	Filter by model: per_call, per_minute, subscription.
sort	string	Sort order: price_asc, price_desc, uptime_desc, response_asc.
limit	number	Max results (default 10, max 100).
offset	number	Pagination offset.

Response Format

Each result includes all the information an agent needs to verify terms locally and decide whether to request a passport:

GET /api/discover?capability=flights:*

{
  "results": [
    {
      "gate_id": "gate_acme-travel",
      "gate_name": "Acme Travel API",
      "permission_key": "flights:search",
      "description": "Search available flights",
      "pricing": {
        "per_call_cents": 2,
        "model": "per_call",
        "currency": "USD"
      },
      "sla": {
        "uptime_basis_points": 9990,
        "response_time_ms": 200
      },
      "platform_fee": {
        "basis_points": 250
      },
      "catalog_version": 3,
      "catalog_content_hash": "sha256:abc123def456...",
      "catalog_signature": "base64url:XYZ...",
      "signing_key_id": "key_01HXYZ...",
      "published_at": "2026-02-01T00:00:00Z"
    },
    {
      "gate_id": "gate_skytravel",
      "permission_key": "flights:search",
      "pricing": { "per_call_cents": 1, "model": "per_call" },
      "sla": { "uptime_basis_points": 9950, "response_time_ms": 400 },
      "catalog_content_hash": "sha256:789xyz...",
      "catalog_signature": "base64url:ABC..."
    }
  ],
  "total": 2,
  "cached_at": "2026-02-24T14:30:00Z"
}

Trustless verification

Agents should never trust discovery results blindly. Verify each result locally before requesting a passport:

Python SDK helpers for commerce are coming soon. Use the REST API above until modei.commerce ships.

To verify a discovery result locally: fetch the catalog at GET /api/v1/gates/{gate_id}/catalog/{catalog_version}, recompute the SHA-256 content hash, check the Ed25519 catalog signature, and confirm tenant binding. Skip any result whose recomputed hash does not match the one returned by /api/v1/discover.

MCP: discover_services

Claude and other MCP-enabled agents can use the discover_services tool directly:

MCP tool call

{
  "tool": "discover_services",
  "arguments": {
    "capability": "flights:*",
    "max_price_cents": 100,
    "min_uptime_bp": 9990,
    "sort": "price_asc",
    "limit": 5
  }
}

Making your gate discoverable

Gates are only discoverable if is_discoverable: true and have a published catalog. The discovery index is automatically rebuilt whenever you publish a new catalog version.