Make a first call

The base URL is https://api.gridrouter.io. Send your key as a bearer token and a JSON body whose input matches the endpoint's input schema. Money is always integer micro-USD (1,000,000 = $1).

Call one endpointCopy Anchor Link

POST /v1/call/{provider}/{endpoint} runs exactly the endpoint you name. This one is Hunter's email finder, so add a Hunter key first.

curl https://api.gridrouter.io/v1/call/hunter/email.find \
  -H "Authorization: Bearer $GRID_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: lead-8841" \
  -d '{"input": {"first_name": "Ada", "last_name": "Lovelace", "domain": "example.com"}}'

The response is a call object:

{
  "object": "call",
  "id": "call_…",
  "endpoint_id": "hunter/email.find",
  "provider": "hunter",
  "status": "succeeded",
  "hit": true,
  "cost_micro": 0,
  "latency_ms": 640,
  "credential": "byok",
  "data": { "email": "ada@example.com", "confidence": 94 },
  "attempts": [
    { "endpoint_id": "hunter/email.find", "provider": "hunter", "outcome": "hit", "cost_micro": 0, "latency_ms": 640 }
  ]
}

• status is whether the vendor answered; hit is whether it found what the capability promises (here an email). A miss is a successful call with hit: false, not an error.
• data holds the endpoint's normalized output fields. Add "include_raw": true for the vendor's own response in raw.
• cost_micro is what GridRouter charged: always 0 on your own key.
• The same Idempotency-Key with the same body replays the first answer; with a different body it is 422 idempotency_mismatch.

Let GridRouter pick the vendorCopy Anchor Link

POST /v1/run/{capability} takes the capability instead of one endpoint and tries the vendors you have connected until one hits. Every try is listed in attempts.

curl https://api.gridrouter.io/v1/run/people.email.find \
  -H "Authorization: Bearer $GRID_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Grid-Max-Cost: 0.05" \
  -d '{
    "input": {"first_name": "Ada", "last_name": "Lovelace", "domain": "example.com"},
    "provider": {"order": ["prospeo", "hunter"]}
  }'

X-Grid-Max-Cost is in USD (0.05 is 50,000 micro-USD); in the body the same cap is max_cost_micro. See routing for order, only, ignore, sort and fallbacks.

Find endpointsCopy Anchor Link

The catalog is public: GET /v1/catalog/endpoints?q=email searches it and GET /v1/catalog/endpoints/{provider}/{endpoint} returns one endpoint's input JSON Schema, price and quality. POST /v1/quote/{provider}/{endpoint} prices a call without making it.