Quick start

Three calls take you from credentials to a live AI-priced ride quote. Each step shows the request shape and a truncated response. Replace pgw_… and <your-secret> with the values your account manager sent you.

1. Exchange credentials for a JWT

Every quoting call carries a short-lived JWT. Mint one with your API key + secret. Tokens default to 24h TTL (configurable per account, max 366 days).

curl -XPOST https://api.obifareai.com/v1/auth/token \
  -H "X-API-KEY: pgw_..." \
  -H "X-API-SECRET: <your-secret>"

{
  "token":      "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "jti":        "48e86a73-9e90-4c50-a634-a6f7ab47e583",
  "expiresAt":  "2026-05-19T16:03:39.701484Z",
  "ttlSeconds": 86400
}

2. Get a quote

Submit a pickup, destination, and the trip's route metadata. The response carries per-(provider, service-level) market prices plus engine-recommended price points keyed by service level.

curl -XPOST https://api.obifareai.com/v1/quote \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{
    "pickup":          {"latitude": 40.7580, "longitude": -73.9855},
    "destination":     {"latitude": 40.6413, "longitude": -73.7781},
    "distanceKm":      24.1,
    "durationMinutes": 45
  }'

{
  "requestId":       "7ddbdafd-1791-48a3-8fd0-aba74211531c",
  "mode":            "Realtime",
  "currency":        "USD",
  "distanceKm":      24.1,
  "durationMinutes": 45,
  "recommendations": {
    "Standard": [
      { "price": 92.75, "label": "balanced" }
    ]
  },
  "marketPrices": {
    "UBER/Standard": { "p5": 98.10, "p25": 105.20, "p50": 109.00, "p75": 116.40, "p95": 122.55 },
    "LYFT/Standard": { "p5": 96.40, "p25": 102.80, "p50": 108.50, "p75": 114.90, "p95": 121.30 }
  }
}

distanceKm and durationMinutes auto-compute when both are omitted — supply both to bypass the gateway's route resolver, or both will be inferred from pickup/destination. Supplying exactly one returns 400 result:route-metadata-incomplete.

Trips at least 30 minutes in the future (via the optional scheduledAt ISO-8601 field) are priced as Scheduled; sooner trips and trips without a scheduledAt are Realtime.

3. Audit your recent requests (optional)

Every /v1/quote is recorded server-side; pull the last few for sanity, debugging, or to round-trip a request ID into your own logs.

curl https://api.obifareai.com/v1/audit/recent \
  -H "Authorization: Bearer eyJ..."

The response is an array of recent entries; each carries the original requestId plus the pricing decision it produced. See the API reference for the full shape, including the optional after-id / after-received-at pagination cursors and the from / to time-range filters.

What's next

See the full API surface in the API reference.
Learn the auth model in detail on the Authentication page.
Understand error responses on the Errors page.

Your account ships with a sensible default pricing behavior. Operators can opt into additional pricing behaviors — talk to us if you want to explore the catalog.