{"openapi":"3.1.0","info":{"title":"Cabgo API v1","version":"1.0.0","description":"# Cabgo API v1\n\nThe Cabgo API lets agents and integrators act on behalf of operators and\nend-users (riders and drivers) through OAuth 2.0 / OIDC. The API is\nmulti-tenant: every token is bound to one Cabgo tenant (`tenant_id` JWT\nclaim) and that scope is enforced on every request — a token for tenant A\ncan never read tenant B's data.\n\n## Quick start\n\n```bash\n# 1. Register a client (or use an existing one)\ncurl -X POST https://www.cabgo.app/oauth/register \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"client_name\": \"My integration\",\n    \"redirect_uris\": [\"http://127.0.0.1:8080/callback\"],\n    \"token_endpoint_auth_method\": \"none\",\n    \"audiences\": [\"dashboard\"],\n    \"scope\": \"openid tenant.trips:read\"\n  }'\n\n# 2. Operator runs the authorization_code + PKCE flow in their browser\n#    https://www.cabgo.app/oauth/authorize?response_type=code&client_id=...\n\n# 3. Exchange the code for tokens\ncurl -X POST https://www.cabgo.app/oauth/token \\\n  -H \"Content-Type: application/x-www-form-urlencoded\" \\\n  -d \"grant_type=authorization_code&code=...&redirect_uri=...&client_id=...&code_verifier=...\"\n\n# 4. Use the access token\ncurl https://www.cabgo.app/api/v1/me \\\n  -H \"Authorization: Bearer $ACCESS_TOKEN\"\n```\n\n## Two-tier access\n\n| Audience | Actor | Used for |\n| --- | --- | --- |\n| `dashboard` | Operator (User + Membership in the tenant) | Whole-fleet operations: list trips, manage drivers, change tariffs, generate reports. Scopes start with `tenant.`. |\n| `rider` | Customer | Their own account: request a ride, list trips, save addresses, read wallet. Scopes start with `rider.`. |\n| `driver` | Driver | Their own work: go online, accept / complete trips, read wallet. Scopes start with `driver.`. |\n\n## Defense in depth\n\nEvery `/api/v1/*` request goes through `authorizeRequest()`, which checks:\n\n1. The JWT signature against the local JWKS.\n2. The audit row in `OAuthAccessToken` — a revoked token gets `401` even\n   if the JWT is still cryptographically valid.\n3. The endpoint's audience requirement (a rider token can't read `/api/v1/trips`).\n4. The endpoint's scope requirement (insufficient → `403 insufficient_scope`).\n5. **Operator only:** the `Permission` is still granted on the\n   `MembershipPermission` row — re-checked at every request, not just at\n   token issuance. If an admin removes `VIEW_TRIPS` from a teammate,\n   their tokens stop working on `/api/v1/trips` immediately.\n6. **End-user only:** the tenant feature flag the scope depends on is\n   still enabled (`taxiEnabled` for `rider.trips:create`,\n   `deliveryEnabled` for `rider.orders:*`). Disabling delivery from the\n   operator dashboard invalidates rider `orders` scopes in real time.\n\n## Errors\n\nAll errors follow this shape:\n\n```json\n{\n  \"error\": \"insufficient_scope\",\n  \"error_description\": \"missing scopes: tenant.trips:read\",\n  \"scope\": \"tenant.trips:read\"\n}\n```\n\n| Status | `error` | Meaning |\n| --- | --- | --- |\n| 401 | `unauthorized` | Token missing, invalid, or revoked. |\n| 403 | `insufficient_scope` | Token doesn't carry the required scope. |\n| 403 | `forbidden` | Operator's `Permission` was removed. |\n| 403 | `feature_disabled` | The tenant has the required feature off (`taxiEnabled` / `deliveryEnabled`). |\n| 404 | — | Resource missing OR present in another tenant (we don't distinguish to avoid leaking IDs). |\n| 409 | `invalid_state` | Trip is in a status that disallows this action. |\n\n## More\n\n* [Interactive playground](/api-docs) — try every endpoint in the browser.\n* [Auth + scope reference](/docs/api) — full OAuth flow walkthrough + scope catalog by audience.\n* [MCP server](/docs/api/mcp) — install `cabgo-mcp` and let Claude Desktop / Cursor / Continue call the API directly.\n* [Markdown for LLMs](/api-docs/llms.txt) — single-file dump of the API surface optimised for LLM ingestion.\n\n","contact":{"name":"Cabgo","url":"https://www.cabgo.app"},"license":{"name":"Proprietary"}},"servers":[{"url":"https://www.cabgo.app"}],"tags":[{"name":"Operator — Trips","description":"Trips across the tenant's whole fleet. Token audience must be `dashboard` and the actor must hold the corresponding `Permission` (re-checked at request time)."},{"name":"Operator — Drivers","description":"List + read driver records, live status, and location."},{"name":"Operator — Customers","description":"Search and read riders (customers) registered against the tenant."},{"name":"Operator — Settings","description":"Tenant configuration — pricing mode, service types, zones, branding, feature flags."},{"name":"Operator — Delivery","description":"Delivery businesses + food orders. All endpoints require `tenant.deliveryEnabled = true`."},{"name":"Operator — Wallets & Reports","description":"Aggregated wallet balances + tenant KPI summaries."},{"name":"Rider","description":"End-user (customer) actions: profile, trips, addresses, orders, payment methods, wallet. Token audience must be `rider` and access is scoped to the authenticated customer's own records."},{"name":"Driver","description":"Driver actions: profile, status toggle, trip lifecycle (accept → arrived → start → complete), wallet. Token audience must be `driver` and access is scoped to the authenticated driver."}],"paths":{"/api/v1/me":{"get":{"operationId":"cabgo_me","tags":["Rider"],"summary":"Read your profile","description":"Polymorphic profile endpoint. Returns the operator's User + active Membership, the rider's Customer record, or the driver's Driver record — chosen automatically based on the token's `aud` claim.","security":[{"OAuth2":["rider.profile:read","driver.profile:read"]}],"x-cabgo-scopes":["rider.profile:read","driver.profile:read"],"x-cabgo-audiences":["dashboard","rider","driver"],"responses":{"200":{"description":"Profile object — shape varies by audience.","content":{"application/json":{"example":{"actor":"customer","id":"cust_2P...","firstName":"María","lastName":"García","email":"maria@example.com","phone":"+525500001234","totalTrips":47,"rating":4.85}}}},"401":{"description":"Unauthorized — missing / invalid / revoked bearer token","content":{"application/json":{"example":{"error":"unauthorized","error_description":"invalid_token"}}}},"403":{"description":"Forbidden — missing scope, permission, or tenant feature disabled","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"missing scopes: tenant.trips:read"}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -H \"Authorization: Bearer $CABGO_TOKEN\" \\\n  https://www.cabgo.app/api/v1/me"},{"lang":"JavaScript","label":"JavaScript","source":"const res = await fetch(\"https://www.cabgo.app/api/v1/me\", { headers: { Authorization: `Bearer ${CABGO_TOKEN}` } });\nconst data = await res.json();"},{"lang":"Python","label":"Python","source":"import requests\nres = requests.get(\n    \"https://www.cabgo.app/api/v1/me\",\n    headers={\"Authorization\": f\"Bearer {CABGO_TOKEN}\"},\n)\ndata = res.json()"}]}},"/api/v1/trips":{"get":{"operationId":"cabgo_list_trips","tags":["Operator — Trips"],"summary":"List tenant trips","description":"Paginated list of trips in the active tenant. The token's `tenant_id` claim is enforced — a token bound to tenant A can never list tenant B's trips. Use `from` / `to` (ISO 8601) to scope a date range, and follow `next_cursor` to walk the rest of the result set.","security":[{"OAuth2":["tenant.trips:read"]}],"x-cabgo-scopes":["tenant.trips:read"],"x-cabgo-permission":"VIEW_TRIPS","x-cabgo-audiences":["dashboard"],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["PENDING","SEARCHING","ASSIGNED","DRIVER_ARRIVED","IN_PROGRESS","COMPLETED","CANCELLED"]},"description":"Filter by trip status."},{"name":"driverId","in":"query","schema":{"type":"string"},"description":"Restrict to trips assigned to a specific driver."},{"name":"customerId","in":"query","schema":{"type":"string"},"description":"Restrict to trips requested by a specific rider."},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO 8601 lower bound on `requestedAt`.","example":"2026-05-01T00:00:00Z"},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO 8601 upper bound on `requestedAt`."},{"name":"limit","in":"query","schema":{"type":"integer"},"description":"1..200. Default 50."},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pass `next_cursor` from the previous page."}],"responses":{"200":{"description":"Items array + `next_cursor` (null when no more pages).","content":{"application/json":{"example":{"items":[{"id":"tr_01HK9F2ZTYP3JK4QXX7BD2N3V8","tripCode":"T-A1B2C3","status":"COMPLETED","driverId":"drv_8H...","customerId":"cust_2P...","originAddress":"Av. Reforma 222, Cuauhtémoc, CDMX","destAddress":"Aeropuerto CDMX T1","estimatedFare":245.5,"finalFare":250,"currency":"MXN","requestedAt":"2026-05-10T18:22:10.000Z","acceptedAt":"2026-05-10T18:22:35.000Z","completedAt":"2026-05-10T18:54:22.000Z"}],"next_cursor":"tr_01HK9F2ZTYP3JK4QXX7BD2N3V8"}}}},"401":{"description":"Unauthorized — missing / invalid / revoked bearer token","content":{"application/json":{"example":{"error":"unauthorized","error_description":"invalid_token"}}}},"403":{"description":"Forbidden — missing scope, permission, or tenant feature disabled","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"missing scopes: tenant.trips:read"}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -H \"Authorization: Bearer $CABGO_TOKEN\" \\\n  https://www.cabgo.app/api/v1/trips?status=COMPLETED&from=2026-05-01T00:00:00Z&limit=50"},{"lang":"JavaScript","label":"JavaScript","source":"const params = new URLSearchParams({ status: \"COMPLETED\", limit: \"50\" });\nconst res = await fetch(\"https://www.cabgo.app/api/v1/trips?${params}\", { headers: { Authorization: `Bearer ${CABGO_TOKEN}` } });\nconst data = await res.json();"},{"lang":"Python","label":"Python","source":"import requests\nres = requests.get(\n    \"https://www.cabgo.app/api/v1/trips\",\n    headers={\"Authorization\": f\"Bearer {CABGO_TOKEN}\"},\n    params={\"status\": \"COMPLETED\", \"limit\": 50},\n)\ndata = res.json()\nfor trip in data[\"items\"]:\n    print(trip[\"tripCode\"], trip[\"finalFare\"])"}]}},"/api/v1/trips/{id}":{"get":{"operationId":"cabgo_get_trip","tags":["Operator — Trips"],"summary":"Read a single trip","description":"Full trip detail including the assigned driver, the rider, and the last 100 trip-log events.","security":[{"OAuth2":["tenant.trips:read"]}],"x-cabgo-scopes":["tenant.trips:read"],"x-cabgo-permission":"VIEW_TRIPS","x-cabgo-audiences":["dashboard"],"parameters":[{"name":"id","in":"path","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Trip object with Driver, Customer, TripLog included.","content":{"application/json":{"example":{"id":"tr_01HK9F2ZTYP3JK4QXX7BD2N3V8","tripCode":"T-A1B2C3","status":"COMPLETED","driverId":"drv_8H...","customerId":"cust_2P...","originAddress":"Av. Reforma 222, Cuauhtémoc, CDMX","destAddress":"Aeropuerto CDMX T1","estimatedFare":245.5,"finalFare":250,"currency":"MXN","requestedAt":"2026-05-10T18:22:10.000Z","acceptedAt":"2026-05-10T18:22:35.000Z","completedAt":"2026-05-10T18:54:22.000Z"}}}},"401":{"description":"Unauthorized — missing / invalid / revoked bearer token","content":{"application/json":{"example":{"error":"unauthorized","error_description":"invalid_token"}}}},"403":{"description":"Forbidden — missing scope, permission, or tenant feature disabled","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"missing scopes: tenant.trips:read"}}}},"404":{"description":"Trip not found in this tenant."}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -H \"Authorization: Bearer $CABGO_TOKEN\" \\\n  https://www.cabgo.app/api/v1/trips/tr_01HK9F2ZTYP3JK4QXX7BD2N3V8"},{"lang":"JavaScript","label":"JavaScript","source":"const res = await fetch(\"https://www.cabgo.app/api/v1/trips/${tripId}\", { headers: { Authorization: `Bearer ${CABGO_TOKEN}` } });\nconst data = await res.json();"},{"lang":"Python","label":"Python","source":"import requests\nres = requests.get(\n    \"https://www.cabgo.app/api/v1/trips/{trip_id}\",\n    headers={\"Authorization\": f\"Bearer {CABGO_TOKEN}\"},\n)\ndata = res.json()"}]}},"/api/v1/drivers":{"get":{"operationId":"cabgo_list_drivers","tags":["Operator — Drivers"],"summary":"List tenant drivers","description":"Drivers in the active tenant with live status and last-known location. Use `status=ONLINE` for the live-dispatch view.","security":[{"OAuth2":["tenant.drivers:read"]}],"x-cabgo-scopes":["tenant.drivers:read"],"x-cabgo-permission":"VIEW_DRIVERS","x-cabgo-audiences":["dashboard"],"parameters":[{"name":"status","in":"query","schema":{"type":"string","enum":["OFFLINE","ONLINE","BUSY"]}},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"items + next_cursor","content":{"application/json":{"example":{"items":[{"id":"drv_8H4F9PNXVMK7Q5RW2L0DZB1AC3","firstName":"Juan","lastName":"Pérez","email":"juan@example.com","phone":"+525500000000","photoUrl":"https://...","status":"ONLINE","rating":4.92,"totalTrips":1248,"vehiclePlate":"ABC-123","vehicleModel":"Nissan Versa","vehicleColor":"Gris","currentLat":19.4326,"currentLng":-99.1332,"locationUpdatedAt":"2026-05-10T18:55:00.000Z"}],"next_cursor":null}}}},"401":{"description":"Unauthorized — missing / invalid / revoked bearer token","content":{"application/json":{"example":{"error":"unauthorized","error_description":"invalid_token"}}}},"403":{"description":"Forbidden — missing scope, permission, or tenant feature disabled","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"missing scopes: tenant.trips:read"}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -H \"Authorization: Bearer $CABGO_TOKEN\" \\\n  https://www.cabgo.app/api/v1/drivers?status=ONLINE"},{"lang":"JavaScript","label":"JavaScript","source":"const res = await fetch(\"https://www.cabgo.app/api/v1/drivers?status=ONLINE\", { headers: { Authorization: `Bearer ${CABGO_TOKEN}` } });\nconst data = await res.json();"},{"lang":"Python","label":"Python","source":"import requests\nres = requests.get(\n    \"https://www.cabgo.app/api/v1/drivers?status=ONLINE\",\n    headers={\"Authorization\": f\"Bearer {CABGO_TOKEN}\"},\n)\ndata = res.json()"}]}},"/api/v1/customers":{"get":{"operationId":"cabgo_list_customers","tags":["Operator — Customers"],"summary":"List + search customers","description":"Cursor-paginated customer list. `q` matches substring against name, first name, last name, phone, or email (case-insensitive).","security":[{"OAuth2":["tenant.customers:read"]}],"x-cabgo-scopes":["tenant.customers:read"],"x-cabgo-permission":"VIEW_CUSTOMERS","x-cabgo-audiences":["dashboard"],"parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Search substring (name / phone / email).","example":"maria"},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"items + next_cursor"},"401":{"description":"Unauthorized — missing / invalid / revoked bearer token","content":{"application/json":{"example":{"error":"unauthorized","error_description":"invalid_token"}}}},"403":{"description":"Forbidden — missing scope, permission, or tenant feature disabled","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"missing scopes: tenant.trips:read"}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -H \"Authorization: Bearer $CABGO_TOKEN\" \\\n  https://www.cabgo.app/api/v1/customers?q=maria"},{"lang":"JavaScript","label":"JavaScript","source":"const res = await fetch(\"https://www.cabgo.app/api/v1/customers?q=maria\", { headers: { Authorization: `Bearer ${CABGO_TOKEN}` } });\nconst data = await res.json();"},{"lang":"Python","label":"Python","source":"import requests\nres = requests.get(\n    \"https://www.cabgo.app/api/v1/customers?q=maria\",\n    headers={\"Authorization\": f\"Bearer {CABGO_TOKEN}\"},\n)\ndata = res.json()"}]}},"/api/v1/settings":{"get":{"operationId":"cabgo_get_settings","tags":["Operator — Settings"],"summary":"Read tenant settings","description":"Company branding metadata + CompanySettings (pricing, payments, dispatch flags, feature toggles like `taxiEnabled` / `deliveryEnabled`).","security":[{"OAuth2":["tenant.settings:read"]}],"x-cabgo-scopes":["tenant.settings:read"],"x-cabgo-permission":"VIEW_SETTINGS","x-cabgo-audiences":["dashboard"],"responses":{"200":{"description":"{ company, settings }"},"401":{"description":"Unauthorized — missing / invalid / revoked bearer token","content":{"application/json":{"example":{"error":"unauthorized","error_description":"invalid_token"}}}},"403":{"description":"Forbidden — missing scope, permission, or tenant feature disabled","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"missing scopes: tenant.trips:read"}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -H \"Authorization: Bearer $CABGO_TOKEN\" \\\n  https://www.cabgo.app/api/v1/settings"},{"lang":"JavaScript","label":"JavaScript","source":"const res = await fetch(\"https://www.cabgo.app/api/v1/settings\", { headers: { Authorization: `Bearer ${CABGO_TOKEN}` } });\nconst data = await res.json();"},{"lang":"Python","label":"Python","source":"import requests\nres = requests.get(\n    \"https://www.cabgo.app/api/v1/settings\",\n    headers={\"Authorization\": f\"Bearer {CABGO_TOKEN}\"},\n)\ndata = res.json()"}]}},"/api/v1/services":{"get":{"operationId":"cabgo_list_services","tags":["Operator — Settings"],"summary":"List tenant service types","description":"Active ServiceTypes (taxi standard, premium, courier, etc.). Use the `id` of one of these when calling `POST /api/v1/me/trips`.","security":[{"OAuth2":["tenant.settings:read"]}],"x-cabgo-scopes":["tenant.settings:read"],"x-cabgo-permission":"VIEW_SETTINGS","x-cabgo-audiences":["dashboard"],"responses":{"200":{"description":"items[]"},"401":{"description":"Unauthorized — missing / invalid / revoked bearer token","content":{"application/json":{"example":{"error":"unauthorized","error_description":"invalid_token"}}}},"403":{"description":"Forbidden — missing scope, permission, or tenant feature disabled","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"missing scopes: tenant.trips:read"}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -H \"Authorization: Bearer $CABGO_TOKEN\" \\\n  https://www.cabgo.app/api/v1/services"},{"lang":"JavaScript","label":"JavaScript","source":"const res = await fetch(\"https://www.cabgo.app/api/v1/services\", { headers: { Authorization: `Bearer ${CABGO_TOKEN}` } });\nconst data = await res.json();"},{"lang":"Python","label":"Python","source":"import requests\nres = requests.get(\n    \"https://www.cabgo.app/api/v1/services\",\n    headers={\"Authorization\": f\"Bearer {CABGO_TOKEN}\"},\n)\ndata = res.json()"}]}},"/api/v1/zones":{"get":{"operationId":"cabgo_list_zones","tags":["Operator — Settings"],"summary":"List dispatch zones","description":"List dispatch zones","security":[{"OAuth2":["tenant.settings:read"]}],"x-cabgo-scopes":["tenant.settings:read"],"x-cabgo-permission":"VIEW_SETTINGS","x-cabgo-audiences":["dashboard"],"responses":{"200":{"description":"items[]"},"401":{"description":"Unauthorized — missing / invalid / revoked bearer token","content":{"application/json":{"example":{"error":"unauthorized","error_description":"invalid_token"}}}},"403":{"description":"Forbidden — missing scope, permission, or tenant feature disabled","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"missing scopes: tenant.trips:read"}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -H \"Authorization: Bearer $CABGO_TOKEN\" \\\n  https://www.cabgo.app/api/v1/zones"},{"lang":"JavaScript","label":"JavaScript","source":"const res = await fetch(\"https://www.cabgo.app/api/v1/zones\", { headers: { Authorization: `Bearer ${CABGO_TOKEN}` } });\nconst data = await res.json();"},{"lang":"Python","label":"Python","source":"import requests\nres = requests.get(\n    \"https://www.cabgo.app/api/v1/zones\",\n    headers={\"Authorization\": f\"Bearer {CABGO_TOKEN}\"},\n)\ndata = res.json()"}]}},"/api/v1/branding":{"get":{"operationId":"cabgo_get_branding","tags":["Operator — Settings"],"summary":"Read tenant branding","description":"Logo, colors, theme, support / legal URLs.","security":[{"OAuth2":["tenant.settings:read"]}],"x-cabgo-scopes":["tenant.settings:read"],"x-cabgo-permission":"VIEW_BRANDING","x-cabgo-audiences":["dashboard"],"responses":{"200":{"description":"Branding object"},"401":{"description":"Unauthorized — missing / invalid / revoked bearer token","content":{"application/json":{"example":{"error":"unauthorized","error_description":"invalid_token"}}}},"403":{"description":"Forbidden — missing scope, permission, or tenant feature disabled","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"missing scopes: tenant.trips:read"}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -H \"Authorization: Bearer $CABGO_TOKEN\" \\\n  https://www.cabgo.app/api/v1/branding"},{"lang":"JavaScript","label":"JavaScript","source":"const res = await fetch(\"https://www.cabgo.app/api/v1/branding\", { headers: { Authorization: `Bearer ${CABGO_TOKEN}` } });\nconst data = await res.json();"},{"lang":"Python","label":"Python","source":"import requests\nres = requests.get(\n    \"https://www.cabgo.app/api/v1/branding\",\n    headers={\"Authorization\": f\"Bearer {CABGO_TOKEN}\"},\n)\ndata = res.json()"}]},"patch":{"operationId":"cabgo_update_branding","tags":["Operator — Settings"],"summary":"Update tenant branding","description":"Patches one or more of `appName`, `primaryColor`, `secondaryColor`, `iconBackgroundColor`, `themeMode`, `logoUrl`, `faviconUrl`, `supportUrl`, `termsUrl`, `privacyUrl`. Set a field to `null` to clear it.","security":[{"OAuth2":["tenant.branding:write"]}],"x-cabgo-scopes":["tenant.branding:write"],"x-cabgo-permission":"EDIT_BRANDING","x-cabgo-audiences":["dashboard"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"appName":{"type":"string"},"primaryColor":{"type":"string","example":"#FF5722"},"secondaryColor":{"type":"string"},"logoUrl":{"type":"string","format":"uri"}}},"example":{"primaryColor":"#FF5722","appName":"TaxisVip"}}}},"responses":{"200":{"description":"Updated branding object"},"401":{"description":"Unauthorized — missing / invalid / revoked bearer token","content":{"application/json":{"example":{"error":"unauthorized","error_description":"invalid_token"}}}},"403":{"description":"Forbidden — missing scope, permission, or tenant feature disabled","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"missing scopes: tenant.trips:read"}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X PATCH -H \"Authorization: Bearer $CABGO_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"primaryColor\":\"#FF5722\"}' \\\n  https://www.cabgo.app/api/v1/branding"},{"lang":"JavaScript","label":"JavaScript","source":"const res = await fetch(\"https://www.cabgo.app/api/v1/branding\", {\n  method: \"PATCH\",\n  headers: { \"Authorization\": `Bearer ${CABGO_TOKEN}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({ primaryColor: \"#FF5722\" }),\n});"},{"lang":"Python","label":"Python","source":"import requests\nres = requests.patch(\n    \"https://www.cabgo.app/api/v1/branding\",\n    headers={\"Authorization\": f\"Bearer {CABGO_TOKEN}\"},\n    json={\"primaryColor\": \"#FF5722\"},\n)"}]}},"/api/v1/reports/summary":{"get":{"operationId":"cabgo_reports_summary","tags":["Operator — Wallets & Reports"],"summary":"Tenant KPI summary","description":"Trip counts by status, completed-trip revenue, count of currently-active drivers, total customers. Window defaults to the last 30 days.","security":[{"OAuth2":["tenant.reports:read"]}],"x-cabgo-scopes":["tenant.reports:read"],"x-cabgo-permission":"VIEW_REPORTS","x-cabgo-audiences":["dashboard"],"parameters":[{"name":"from","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO 8601 — default `now - 30d`."},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"},"description":"ISO 8601 — default `now`."}],"responses":{"200":{"description":"Aggregated KPI bundle.","content":{"application/json":{"example":{"window":{"from":"2026-04-11T00:00:00Z","to":"2026-05-11T00:00:00Z"},"tripsByStatus":{"COMPLETED":1248,"CANCELLED":31},"completedTrips":1248,"revenue":312440.5,"activeDrivers":27,"totalCustomers":4521}}}},"401":{"description":"Unauthorized — missing / invalid / revoked bearer token","content":{"application/json":{"example":{"error":"unauthorized","error_description":"invalid_token"}}}},"403":{"description":"Forbidden — missing scope, permission, or tenant feature disabled","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"missing scopes: tenant.trips:read"}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -H \"Authorization: Bearer $CABGO_TOKEN\" \\\n  https://www.cabgo.app/api/v1/reports/summary"},{"lang":"JavaScript","label":"JavaScript","source":"const res = await fetch(\"https://www.cabgo.app/api/v1/reports/summary\", { headers: { Authorization: `Bearer ${CABGO_TOKEN}` } });\nconst data = await res.json();"},{"lang":"Python","label":"Python","source":"import requests\nres = requests.get(\n    \"https://www.cabgo.app/api/v1/reports/summary\",\n    headers={\"Authorization\": f\"Bearer {CABGO_TOKEN}\"},\n)\ndata = res.json()"}]}},"/api/v1/wallets":{"get":{"operationId":"cabgo_wallet_totals","tags":["Operator — Wallets & Reports"],"summary":"Read wallet totals","description":"Default response is aggregated `drivers` + `customers` totals. Pass `?type=driver|customer&detail=1` for per-actor listings (top by balance, paginated).","security":[{"OAuth2":["tenant.wallets:read"]}],"x-cabgo-scopes":["tenant.wallets:read"],"x-cabgo-permission":"VIEW_WALLETS","x-cabgo-audiences":["dashboard"],"parameters":[{"name":"type","in":"query","schema":{"type":"string","enum":["driver","customer"]}},{"name":"detail","in":"query","schema":{"type":"string","enum":["1"]}},{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"Totals or items[]"},"401":{"description":"Unauthorized — missing / invalid / revoked bearer token","content":{"application/json":{"example":{"error":"unauthorized","error_description":"invalid_token"}}}},"403":{"description":"Forbidden — missing scope, permission, or tenant feature disabled","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"missing scopes: tenant.trips:read"}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -H \"Authorization: Bearer $CABGO_TOKEN\" \\\n  https://www.cabgo.app/api/v1/wallets"},{"lang":"JavaScript","label":"JavaScript","source":"const res = await fetch(\"https://www.cabgo.app/api/v1/wallets\", { headers: { Authorization: `Bearer ${CABGO_TOKEN}` } });\nconst data = await res.json();"},{"lang":"Python","label":"Python","source":"import requests\nres = requests.get(\n    \"https://www.cabgo.app/api/v1/wallets\",\n    headers={\"Authorization\": f\"Bearer {CABGO_TOKEN}\"},\n)\ndata = res.json()"}]}},"/api/v1/businesses":{"get":{"operationId":"cabgo_list_businesses","tags":["Operator — Delivery"],"summary":"List delivery businesses","description":"Returns active businesses in the tenant. Requires `tenant.deliveryEnabled = true`; otherwise responds with `403 feature_disabled`.","security":[{"OAuth2":["tenant.businesses:read"]}],"x-cabgo-scopes":["tenant.businesses:read"],"x-cabgo-permission":"VIEW_BUSINESSES","x-cabgo-tenant-feature":"deliveryEnabled","x-cabgo-audiences":["dashboard"],"responses":{"200":{"description":"items + next_cursor"},"401":{"description":"Unauthorized — missing / invalid / revoked bearer token","content":{"application/json":{"example":{"error":"unauthorized","error_description":"invalid_token"}}}},"403":{"description":"Forbidden — missing scope, permission, or tenant feature disabled","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"missing scopes: tenant.trips:read"}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -H \"Authorization: Bearer $CABGO_TOKEN\" \\\n  https://www.cabgo.app/api/v1/businesses"},{"lang":"JavaScript","label":"JavaScript","source":"const res = await fetch(\"https://www.cabgo.app/api/v1/businesses\", { headers: { Authorization: `Bearer ${CABGO_TOKEN}` } });\nconst data = await res.json();"},{"lang":"Python","label":"Python","source":"import requests\nres = requests.get(\n    \"https://www.cabgo.app/api/v1/businesses\",\n    headers={\"Authorization\": f\"Bearer {CABGO_TOKEN}\"},\n)\ndata = res.json()"}]}},"/api/v1/orders":{"get":{"operationId":"cabgo_list_orders","tags":["Operator — Delivery"],"summary":"List delivery orders","description":"FoodOrders across the tenant. Filterable by status, business, customer. Requires `tenant.deliveryEnabled = true`.","security":[{"OAuth2":["tenant.delivery:read"]}],"x-cabgo-scopes":["tenant.delivery:read"],"x-cabgo-permission":"VIEW_FOOD_ORDERS","x-cabgo-tenant-feature":"deliveryEnabled","x-cabgo-audiences":["dashboard"],"parameters":[{"name":"status","in":"query","schema":{"type":"string"}},{"name":"businessId","in":"query","schema":{"type":"string"}},{"name":"customerId","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer"}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"items + next_cursor"},"401":{"description":"Unauthorized — missing / invalid / revoked bearer token","content":{"application/json":{"example":{"error":"unauthorized","error_description":"invalid_token"}}}},"403":{"description":"Forbidden — missing scope, permission, or tenant feature disabled","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"missing scopes: tenant.trips:read"}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -H \"Authorization: Bearer $CABGO_TOKEN\" \\\n  https://www.cabgo.app/api/v1/orders"},{"lang":"JavaScript","label":"JavaScript","source":"const res = await fetch(\"https://www.cabgo.app/api/v1/orders\", { headers: { Authorization: `Bearer ${CABGO_TOKEN}` } });\nconst data = await res.json();"},{"lang":"Python","label":"Python","source":"import requests\nres = requests.get(\n    \"https://www.cabgo.app/api/v1/orders\",\n    headers={\"Authorization\": f\"Bearer {CABGO_TOKEN}\"},\n)\ndata = res.json()"}]}},"/api/v1/me/trips":{"get":{"operationId":"cabgo_my_trips","tags":["Rider"],"summary":"List your trips","description":"Rider: trips you requested. Driver: trips assigned to you. Operator audience returns 400 — use `/api/v1/trips` instead.","security":[{"OAuth2":["rider.trips:read","driver.trips:read"]}],"x-cabgo-scopes":["rider.trips:read","driver.trips:read"],"x-cabgo-audiences":["rider","driver"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"items[]"},"401":{"description":"Unauthorized — missing / invalid / revoked bearer token","content":{"application/json":{"example":{"error":"unauthorized","error_description":"invalid_token"}}}},"403":{"description":"Forbidden — missing scope, permission, or tenant feature disabled","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"missing scopes: tenant.trips:read"}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -H \"Authorization: Bearer $CABGO_TOKEN\" \\\n  https://www.cabgo.app/api/v1/me/trips"},{"lang":"JavaScript","label":"JavaScript","source":"const res = await fetch(\"https://www.cabgo.app/api/v1/me/trips\", { headers: { Authorization: `Bearer ${CABGO_TOKEN}` } });\nconst data = await res.json();"},{"lang":"Python","label":"Python","source":"import requests\nres = requests.get(\n    \"https://www.cabgo.app/api/v1/me/trips\",\n    headers={\"Authorization\": f\"Bearer {CABGO_TOKEN}\"},\n)\ndata = res.json()"}]},"post":{"operationId":"cabgo_request_ride","tags":["Rider"],"summary":"Request a ride","description":"Creates a PENDING trip for the authenticated rider. Requires `tenant.taxiEnabled = true`. `paymentType` defaults to `CASH` and `serviceTypeId` is optional — when omitted the tenant's default service is used.","security":[{"OAuth2":["rider.trips:create"]}],"x-cabgo-scopes":["rider.trips:create"],"x-cabgo-tenant-feature":"taxiEnabled","x-cabgo-audiences":["rider"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["originAddress","originLat","originLng"],"properties":{"originAddress":{"type":"string"},"originLat":{"type":"number"},"originLng":{"type":"number"},"destAddress":{"type":"string"},"destLat":{"type":"number"},"destLng":{"type":"number"},"serviceTypeId":{"type":"string"},"paymentType":{"type":"string","enum":["CASH","CARD","WALLET"]},"notes":{"type":"string"}}},"example":{"originAddress":"Av. Reforma 222, Cuauhtémoc, CDMX","originLat":19.4326,"originLng":-99.1332,"destAddress":"Aeropuerto CDMX T1","destLat":19.4361,"destLng":-99.0727,"paymentType":"CARD"}}}},"responses":{"201":{"description":"Trip object (status=PENDING)","content":{"application/json":{"example":{"id":"tr_01HK9F2ZTYP3JK4QXX7BD2N3V8","tripCode":"T-A1B2C3","status":"PENDING","driverId":"drv_8H...","customerId":"cust_2P...","originAddress":"Av. Reforma 222, Cuauhtémoc, CDMX","destAddress":"Aeropuerto CDMX T1","estimatedFare":245.5,"finalFare":250,"currency":"MXN","requestedAt":"2026-05-10T18:22:10.000Z","acceptedAt":"2026-05-10T18:22:35.000Z","completedAt":"2026-05-10T18:54:22.000Z"}}}},"401":{"description":"Unauthorized — missing / invalid / revoked bearer token","content":{"application/json":{"example":{"error":"unauthorized","error_description":"invalid_token"}}}},"403":{"description":"Forbidden — missing scope, permission, or tenant feature disabled","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"missing scopes: tenant.trips:read"}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST -H \"Authorization: Bearer $CABGO_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"originAddress\":\"Reforma 222\",\"originLat\":19.4326,\"originLng\":-99.1332,\"paymentType\":\"CARD\"}' \\\n  https://www.cabgo.app/api/v1/me/trips"},{"lang":"JavaScript","label":"JavaScript","source":"const res = await fetch(\"https://www.cabgo.app/api/v1/me/trips\", {\n  method: \"POST\",\n  headers: { \"Authorization\": `Bearer ${CABGO_TOKEN}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({\n    originAddress: \"Reforma 222\",\n    originLat: 19.4326,\n    originLng: -99.1332,\n    paymentType: \"CARD\",\n  }),\n});\nconst trip = await res.json();"},{"lang":"Python","label":"Python","source":"import requests\nres = requests.post(\n    \"https://www.cabgo.app/api/v1/me/trips\",\n    headers={\"Authorization\": f\"Bearer {CABGO_TOKEN}\"},\n    json={\"originAddress\":\"Reforma 222\",\"originLat\":19.4326,\"originLng\":-99.1332,\"paymentType\":\"CARD\"},\n)\ndata = res.json()"}]}},"/api/v1/me/trips/{id}/cancel":{"post":{"operationId":"cabgo_cancel_my_trip","tags":["Rider"],"summary":"Cancel your trip","description":"Cancels a trip you requested. Only valid for statuses PENDING / SEARCHING / ASSIGNED / DRIVER_ARRIVED / WAITING_CUSTOMER / SCHEDULED. Once `IN_PROGRESS`, the operator must intervene. Cancellation penalties (where configured) are assessed in the legacy flow and not by this endpoint.","security":[{"OAuth2":["rider.trips:cancel"]}],"x-cabgo-scopes":["rider.trips:cancel"],"x-cabgo-audiences":["rider"],"parameters":[{"name":"id","in":"path","schema":{"type":"string"},"required":true}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string"}}},"example":{"reason":"Cambio de planes"}}}},"responses":{"200":{"description":"{ id, status, updatedAt }"},"401":{"description":"Unauthorized — missing / invalid / revoked bearer token","content":{"application/json":{"example":{"error":"unauthorized","error_description":"invalid_token"}}}},"403":{"description":"Forbidden — missing scope, permission, or tenant feature disabled","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"missing scopes: tenant.trips:read"}}}},"409":{"description":"Trip is in a status that doesn't allow cancellation."}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST -H \"Authorization: Bearer $CABGO_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"reason\":\"Cambio de planes\"}' \\\n  https://www.cabgo.app/api/v1/me/trips/{id}/cancel"},{"lang":"JavaScript","label":"JavaScript","source":"const res = await fetch(\"https://www.cabgo.app/api/v1/me/trips/${tripId}/cancel\", { method: \"POST\", headers: { Authorization: `Bearer ${CABGO_TOKEN}`, \"Content-Type\": \"application/json\" }, body: JSON.stringify({ reason: \"Cambio de planes\" }) });\nconst data = await res.json();"},{"lang":"Python","label":"Python","source":"import requests\nres = requests.post(\n    \"https://www.cabgo.app/api/v1/me/trips/{id}/cancel\",\n    headers={\"Authorization\": f\"Bearer {CABGO_TOKEN}\"},\n    json={\"reason\":\"Cambio de planes\"},\n)\ndata = res.json()"}]}},"/api/v1/me/addresses":{"get":{"operationId":"cabgo_list_addresses","tags":["Rider"],"summary":"List saved addresses","description":"Rider's saved addresses, sorted by most-recently used.","security":[{"OAuth2":["rider.profile:read"]}],"x-cabgo-scopes":["rider.profile:read"],"x-cabgo-audiences":["rider"],"responses":{"200":{"description":"items[]"},"401":{"description":"Unauthorized — missing / invalid / revoked bearer token","content":{"application/json":{"example":{"error":"unauthorized","error_description":"invalid_token"}}}},"403":{"description":"Forbidden — missing scope, permission, or tenant feature disabled","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"missing scopes: tenant.trips:read"}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -H \"Authorization: Bearer $CABGO_TOKEN\" \\\n  https://www.cabgo.app/api/v1/me/addresses"},{"lang":"JavaScript","label":"JavaScript","source":"const res = await fetch(\"https://www.cabgo.app/api/v1/me/addresses\", { headers: { Authorization: `Bearer ${CABGO_TOKEN}` } });\nconst data = await res.json();"},{"lang":"Python","label":"Python","source":"import requests\nres = requests.get(\n    \"https://www.cabgo.app/api/v1/me/addresses\",\n    headers={\"Authorization\": f\"Bearer {CABGO_TOKEN}\"},\n)\ndata = res.json()"}]},"post":{"operationId":"cabgo_save_address","tags":["Rider"],"summary":"Save a new address","description":"Idempotent on `(lat, lng)` — saving the same coordinate again bumps `usageCount` and `lastUsedAt` instead of creating a duplicate. `label` and `notes` are optional and overwrite on collision.","security":[{"OAuth2":["rider.addresses:write"]}],"x-cabgo-scopes":["rider.addresses:write"],"x-cabgo-audiences":["rider"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["address","lat","lng"],"properties":{"address":{"type":"string"},"lat":{"type":"number"},"lng":{"type":"number"},"label":{"type":"string"},"notes":{"type":"string"}}},"example":{"address":"Av. Reforma 222, Cuauhtémoc, CDMX","lat":19.4326,"lng":-99.1332,"label":"Casa"}}}},"responses":{"201":{"description":"CustomerAddress object"},"401":{"description":"Unauthorized — missing / invalid / revoked bearer token","content":{"application/json":{"example":{"error":"unauthorized","error_description":"invalid_token"}}}},"403":{"description":"Forbidden — missing scope, permission, or tenant feature disabled","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"missing scopes: tenant.trips:read"}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST -H \"Authorization: Bearer $CABGO_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"address\":\"Reforma 222\",\"lat\":19.4326,\"lng\":-99.1332,\"label\":\"Casa\"}' \\\n  https://www.cabgo.app/api/v1/me/addresses"},{"lang":"JavaScript","label":"JavaScript","source":"const res = await fetch(\"https://www.cabgo.app/api/v1/me/addresses\", { method: \"POST\", headers: { Authorization: `Bearer ${CABGO_TOKEN}`, \"Content-Type\": \"application/json\" }, body: JSON.stringify({ address: \"Reforma 222\", lat: 19.4326, lng: -99.1332, label: \"Casa\" }) });\nconst data = await res.json();"},{"lang":"Python","label":"Python","source":"import requests\nres = requests.post(\n    \"https://www.cabgo.app/api/v1/me/addresses\",\n    headers={\"Authorization\": f\"Bearer {CABGO_TOKEN}\"},\n    json={\"address\":\"Reforma 222\",\"lat\":19.4326,\"lng\":-99.1332,\"label\":\"Casa\"},\n)\ndata = res.json()"}]}},"/api/v1/me/wallet":{"get":{"operationId":"cabgo_my_wallet","tags":["Rider"],"summary":"Read your wallet balance","description":"Returns the wallet balance and the last 20 transactions. Works for both rider and driver tokens — the right wallet is chosen automatically from the `aud` claim.","security":[{"OAuth2":["rider.wallet:read","driver.wallet:read"]}],"x-cabgo-scopes":["rider.wallet:read","driver.wallet:read"],"x-cabgo-audiences":["rider","driver"],"responses":{"200":{"description":"{ balance, transactions[] }","content":{"application/json":{"example":{"balance":480.5,"transactions":[{"id":"wtx_...","type":"TRIP_PAYMENT","amount":-180,"description":"Viaje T-A1B2C3","createdAt":"2026-05-10T18:54:22.000Z"}]}}}},"401":{"description":"Unauthorized — missing / invalid / revoked bearer token","content":{"application/json":{"example":{"error":"unauthorized","error_description":"invalid_token"}}}},"403":{"description":"Forbidden — missing scope, permission, or tenant feature disabled","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"missing scopes: tenant.trips:read"}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -H \"Authorization: Bearer $CABGO_TOKEN\" \\\n  https://www.cabgo.app/api/v1/me/wallet"},{"lang":"JavaScript","label":"JavaScript","source":"const res = await fetch(\"https://www.cabgo.app/api/v1/me/wallet\", { headers: { Authorization: `Bearer ${CABGO_TOKEN}` } });\nconst data = await res.json();"},{"lang":"Python","label":"Python","source":"import requests\nres = requests.get(\n    \"https://www.cabgo.app/api/v1/me/wallet\",\n    headers={\"Authorization\": f\"Bearer {CABGO_TOKEN}\"},\n)\ndata = res.json()"}]}},"/api/v1/me/payment-methods":{"get":{"operationId":"cabgo_list_payment_methods","tags":["Rider"],"summary":"List saved payment methods","description":"List saved payment methods","security":[{"OAuth2":["rider.payments:read"]}],"x-cabgo-scopes":["rider.payments:read"],"x-cabgo-audiences":["rider"],"responses":{"200":{"description":"items[]"},"401":{"description":"Unauthorized — missing / invalid / revoked bearer token","content":{"application/json":{"example":{"error":"unauthorized","error_description":"invalid_token"}}}},"403":{"description":"Forbidden — missing scope, permission, or tenant feature disabled","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"missing scopes: tenant.trips:read"}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -H \"Authorization: Bearer $CABGO_TOKEN\" \\\n  https://www.cabgo.app/api/v1/me/payment-methods"},{"lang":"JavaScript","label":"JavaScript","source":"const res = await fetch(\"https://www.cabgo.app/api/v1/me/payment-methods\", { headers: { Authorization: `Bearer ${CABGO_TOKEN}` } });\nconst data = await res.json();"},{"lang":"Python","label":"Python","source":"import requests\nres = requests.get(\n    \"https://www.cabgo.app/api/v1/me/payment-methods\",\n    headers={\"Authorization\": f\"Bearer {CABGO_TOKEN}\"},\n)\ndata = res.json()"}]}},"/api/v1/me/orders":{"get":{"operationId":"cabgo_my_orders","tags":["Rider"],"summary":"List your delivery orders","description":"Requires `tenant.deliveryEnabled = true`. Returns up to `limit` (default 30) of the rider's most recent orders.","security":[{"OAuth2":["rider.orders:read"]}],"x-cabgo-scopes":["rider.orders:read"],"x-cabgo-tenant-feature":"deliveryEnabled","x-cabgo-audiences":["rider"],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer"}}],"responses":{"200":{"description":"items[]"},"401":{"description":"Unauthorized — missing / invalid / revoked bearer token","content":{"application/json":{"example":{"error":"unauthorized","error_description":"invalid_token"}}}},"403":{"description":"Forbidden — missing scope, permission, or tenant feature disabled","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"missing scopes: tenant.trips:read"}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -H \"Authorization: Bearer $CABGO_TOKEN\" \\\n  https://www.cabgo.app/api/v1/me/orders"},{"lang":"JavaScript","label":"JavaScript","source":"const res = await fetch(\"https://www.cabgo.app/api/v1/me/orders\", { headers: { Authorization: `Bearer ${CABGO_TOKEN}` } });\nconst data = await res.json();"},{"lang":"Python","label":"Python","source":"import requests\nres = requests.get(\n    \"https://www.cabgo.app/api/v1/me/orders\",\n    headers={\"Authorization\": f\"Bearer {CABGO_TOKEN}\"},\n)\ndata = res.json()"}]}},"/api/v1/me/status":{"patch":{"operationId":"cabgo_set_driver_status","tags":["Driver"],"summary":"Update driver status","description":"Toggle online / offline. The body accepts either `{ online: true|false }` (convenience) or `{ status: 'ONLINE'|'OFFLINE'|'BUSY' }` (explicit). Side-effect free at this layer: location pings and dispatch enrollment still happen in the mobile-app path.","security":[{"OAuth2":["driver.status:write"]}],"x-cabgo-scopes":["driver.status:write"],"x-cabgo-audiences":["driver"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"online":true}}}},"responses":{"200":{"description":"{ id, status, updatedAt }"},"401":{"description":"Unauthorized — missing / invalid / revoked bearer token","content":{"application/json":{"example":{"error":"unauthorized","error_description":"invalid_token"}}}},"403":{"description":"Forbidden — missing scope, permission, or tenant feature disabled","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"missing scopes: tenant.trips:read"}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X PATCH -H \"Authorization: Bearer $CABGO_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"online\":true}' \\\n  https://www.cabgo.app/api/v1/me/status"},{"lang":"JavaScript","label":"JavaScript","source":"await fetch(\"https://www.cabgo.app/api/v1/me/status\", {\n  method: \"PATCH\",\n  headers: { \"Authorization\": `Bearer ${CABGO_TOKEN}`, \"Content-Type\": \"application/json\" },\n  body: JSON.stringify({ online: true }),\n});"},{"lang":"Python","label":"Python","source":"import requests\nrequests.patch(\n    \"https://www.cabgo.app/api/v1/me/status\",\n    headers={\"Authorization\": f\"Bearer {CABGO_TOKEN}\"},\n    json={\"online\": True},\n)"}]}},"/api/v1/me/trips/{id}/accept":{"post":{"operationId":"cabgo_accept_trip","tags":["Driver"],"summary":"Accept an open trip","description":"Driver takes ownership of a PENDING / SEARCHING / COLLECTING_OFFERS trip in their tenant. Transitions the trip to ASSIGNED and sets `acceptedAt`. Returns 409 if the trip is already assigned to a different driver.","security":[{"OAuth2":["driver.trips:accept"]}],"x-cabgo-scopes":["driver.trips:accept"],"x-cabgo-audiences":["driver"],"parameters":[{"name":"id","in":"path","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"{ id, status, driverId, acceptedAt }"},"401":{"description":"Unauthorized — missing / invalid / revoked bearer token","content":{"application/json":{"example":{"error":"unauthorized","error_description":"invalid_token"}}}},"403":{"description":"Forbidden — missing scope, permission, or tenant feature disabled","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"missing scopes: tenant.trips:read"}}}},"409":{"description":"Trip is no longer acceptable (different driver / wrong status)."}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST -H \"Authorization: Bearer $CABGO_TOKEN\" \\\n  https://www.cabgo.app/api/v1/me/trips/{id}/accept"},{"lang":"JavaScript","label":"JavaScript","source":"await fetch(\"https://www.cabgo.app/api/v1/me/trips/\" + tripId + \"/accept\", {\n  method: \"POST\",\n  headers: { \"Authorization\": `Bearer ${CABGO_TOKEN}` },\n});"},{"lang":"Python","label":"Python","source":"import requests\nres = requests.post(\n    \"https://www.cabgo.app/api/v1/me/trips/{id}/accept\",\n    headers={\"Authorization\": f\"Bearer {CABGO_TOKEN}\"},\n)"}]}},"/api/v1/me/trips/{id}/arrived":{"post":{"operationId":"cabgo_mark_arrived","tags":["Driver"],"summary":"Mark as arrived at pickup","description":"Mark as arrived at pickup","security":[{"OAuth2":["driver.trips:complete"]}],"x-cabgo-scopes":["driver.trips:complete"],"x-cabgo-audiences":["driver"],"parameters":[{"name":"id","in":"path","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"{ id, status, arrivedAt }"},"401":{"description":"Unauthorized — missing / invalid / revoked bearer token","content":{"application/json":{"example":{"error":"unauthorized","error_description":"invalid_token"}}}},"403":{"description":"Forbidden — missing scope, permission, or tenant feature disabled","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"missing scopes: tenant.trips:read"}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST -H \"Authorization: Bearer $CABGO_TOKEN\" \\\n  https://www.cabgo.app/api/v1/me/trips/{id}/arrived"},{"lang":"JavaScript","label":"JavaScript","source":"const res = await fetch(\"https://www.cabgo.app/api/v1/me/trips/${tripId}/arrived\", { method: \"POST\", headers: { Authorization: `Bearer ${CABGO_TOKEN}` } });\nconst data = await res.json();"},{"lang":"Python","label":"Python","source":"import requests\nres = requests.post(\n    \"https://www.cabgo.app/api/v1/me/trips/{id}/arrived\",\n    headers={\"Authorization\": f\"Bearer {CABGO_TOKEN}\"},\n)"}]}},"/api/v1/me/trips/{id}/start":{"post":{"operationId":"cabgo_start_trip","tags":["Driver"],"summary":"Start the trip","description":"Marks a DRIVER_ARRIVED trip as IN_PROGRESS (rider boarded).","security":[{"OAuth2":["driver.trips:complete"]}],"x-cabgo-scopes":["driver.trips:complete"],"x-cabgo-audiences":["driver"],"parameters":[{"name":"id","in":"path","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"{ id, status, startedAt }"},"401":{"description":"Unauthorized — missing / invalid / revoked bearer token","content":{"application/json":{"example":{"error":"unauthorized","error_description":"invalid_token"}}}},"403":{"description":"Forbidden — missing scope, permission, or tenant feature disabled","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"missing scopes: tenant.trips:read"}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST -H \"Authorization: Bearer $CABGO_TOKEN\" \\\n  https://www.cabgo.app/api/v1/me/trips/{id}/start"},{"lang":"JavaScript","label":"JavaScript","source":"const res = await fetch(\"https://www.cabgo.app/api/v1/me/trips/${tripId}/start\", { method: \"POST\", headers: { Authorization: `Bearer ${CABGO_TOKEN}` } });\nconst data = await res.json();"},{"lang":"Python","label":"Python","source":"import requests\nres = requests.post(\n    \"https://www.cabgo.app/api/v1/me/trips/{id}/start\",\n    headers={\"Authorization\": f\"Bearer {CABGO_TOKEN}\"},\n)"}]}},"/api/v1/me/trips/{id}/complete":{"post":{"operationId":"cabgo_complete_trip","tags":["Driver"],"summary":"Complete the trip","description":"Marks an IN_PROGRESS trip COMPLETED. Optional body overrides estimate-time values with measured ones — `finalFare` (number, currency units), `actualDistance` (km), `actualDuration` (seconds). Receipt + commission settlement happen in downstream listeners on the existing mobile path.","security":[{"OAuth2":["driver.trips:complete"]}],"x-cabgo-scopes":["driver.trips:complete"],"x-cabgo-audiences":["driver"],"parameters":[{"name":"id","in":"path","schema":{"type":"string"},"required":true}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"finalFare":{"type":"number"},"actualDistance":{"type":"number"},"actualDuration":{"type":"number"}}},"example":{"finalFare":250,"actualDistance":12.3,"actualDuration":1920}}}},"responses":{"200":{"description":"{ id, status, completedAt, finalFare, actualDistance, actualDuration }"},"401":{"description":"Unauthorized — missing / invalid / revoked bearer token","content":{"application/json":{"example":{"error":"unauthorized","error_description":"invalid_token"}}}},"403":{"description":"Forbidden — missing scope, permission, or tenant feature disabled","content":{"application/json":{"example":{"error":"insufficient_scope","error_description":"missing scopes: tenant.trips:read"}}}}},"x-codeSamples":[{"lang":"curl","label":"curl","source":"curl -X POST -H \"Authorization: Bearer $CABGO_TOKEN\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"finalFare\":250}' \\\n  https://www.cabgo.app/api/v1/me/trips/{id}/complete"},{"lang":"JavaScript","label":"JavaScript","source":"const res = await fetch(\"https://www.cabgo.app/api/v1/me/trips/${tripId}/complete\", { method: \"POST\", headers: { Authorization: `Bearer ${CABGO_TOKEN}`, \"Content-Type\": \"application/json\" }, body: JSON.stringify({ finalFare: 250 }) });\nconst data = await res.json();"},{"lang":"Python","label":"Python","source":"import requests\nres = requests.post(\n    \"https://www.cabgo.app/api/v1/me/trips/{id}/complete\",\n    headers={\"Authorization\": f\"Bearer {CABGO_TOKEN}\"},\n    json={\"finalFare\":250},\n)\ndata = res.json()"}]}}},"components":{"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","example":"insufficient_scope"},"error_description":{"type":"string"},"scope":{"type":"string"},"permission":{"type":"string"},"feature":{"type":"string"}}}},"securitySchemes":{"OAuth2":{"type":"oauth2","description":"OAuth 2.0 with multiple grant types. `authorization_code` + PKCE is the default for browser clients; `client_credentials` for tenant-bound server integrations; `refresh_token` to rotate.","flows":{"authorizationCode":{"authorizationUrl":"https://www.cabgo.app/oauth/authorize","tokenUrl":"https://www.cabgo.app/oauth/token","refreshUrl":"https://www.cabgo.app/oauth/token","scopes":{"openid":"OIDC authentication","profile":"Read profile claims","email":"Read email claim","tenant.trips:read":"List and read trips for the tenant","tenant.trips:write":"Create and update trips for the tenant","tenant.trips:delete":"Delete trips for the tenant","tenant.drivers:read":"List and read driver profiles","tenant.drivers:write":"Create and update drivers","tenant.customers:read":"List and read customer profiles","tenant.customers:write":"Create and update customers","tenant.settings:read":"Read tenant settings (pricing, zones, services)","tenant.settings:write":"Update tenant settings","tenant.reports:read":"Read reports and analytics","tenant.reports:export":"Export reports","tenant.businesses:read":"List businesses (delivery module)","tenant.businesses:write":"Create and update businesses","tenant.delivery:read":"List food orders","tenant.delivery:write":"Update food orders","tenant.wallets:read":"Read driver / customer wallet balances","tenant.wallets:write":"Adjust wallets and approve withdrawals","tenant.branding:write":"Update branding (logos, colors, copy)","rider.profile:read":"Read your profile","rider.profile:write":"Update your profile","rider.trips:read":"Read your trips","rider.trips:create":"Request a ride","rider.trips:cancel":"Cancel a trip you requested","rider.orders:read":"Read your delivery orders","rider.orders:create":"Place a delivery order","rider.addresses:write":"Manage your saved addresses","rider.payments:read":"List your payment methods","rider.wallet:read":"Read your wallet balance","driver.profile:read":"Read your driver profile","driver.status:write":"Go online or offline","driver.trips:read":"Read your assigned trips","driver.trips:accept":"Accept incoming ride offers","driver.trips:complete":"Mark trips as arrived / started / completed","driver.wallet:read":"Read your earnings and wallet","driver.documents:read":"Read the status of your uploaded documents"}},"clientCredentials":{"tokenUrl":"https://www.cabgo.app/oauth/token","scopes":{"openid":"OIDC authentication","profile":"Read profile claims","email":"Read email claim","tenant.trips:read":"List and read trips for the tenant","tenant.trips:write":"Create and update trips for the tenant","tenant.trips:delete":"Delete trips for the tenant","tenant.drivers:read":"List and read driver profiles","tenant.drivers:write":"Create and update drivers","tenant.customers:read":"List and read customer profiles","tenant.customers:write":"Create and update customers","tenant.settings:read":"Read tenant settings (pricing, zones, services)","tenant.settings:write":"Update tenant settings","tenant.reports:read":"Read reports and analytics","tenant.reports:export":"Export reports","tenant.businesses:read":"List businesses (delivery module)","tenant.businesses:write":"Create and update businesses","tenant.delivery:read":"List food orders","tenant.delivery:write":"Update food orders","tenant.wallets:read":"Read driver / customer wallet balances","tenant.wallets:write":"Adjust wallets and approve withdrawals","tenant.branding:write":"Update branding (logos, colors, copy)","rider.profile:read":"Read your profile","rider.profile:write":"Update your profile","rider.trips:read":"Read your trips","rider.trips:create":"Request a ride","rider.trips:cancel":"Cancel a trip you requested","rider.orders:read":"Read your delivery orders","rider.orders:create":"Place a delivery order","rider.addresses:write":"Manage your saved addresses","rider.payments:read":"List your payment methods","rider.wallet:read":"Read your wallet balance","driver.profile:read":"Read your driver profile","driver.status:write":"Go online or offline","driver.trips:read":"Read your assigned trips","driver.trips:accept":"Accept incoming ride offers","driver.trips:complete":"Mark trips as arrived / started / completed","driver.wallet:read":"Read your earnings and wallet","driver.documents:read":"Read the status of your uploaded documents"}},"urn:ietf:params:oauth:grant-type:device_code":{"tokenUrl":"https://www.cabgo.app/oauth/token","scopes":{"openid":"OIDC authentication","profile":"Read profile claims","email":"Read email claim","tenant.trips:read":"List and read trips for the tenant","tenant.trips:write":"Create and update trips for the tenant","tenant.trips:delete":"Delete trips for the tenant","tenant.drivers:read":"List and read driver profiles","tenant.drivers:write":"Create and update drivers","tenant.customers:read":"List and read customer profiles","tenant.customers:write":"Create and update customers","tenant.settings:read":"Read tenant settings (pricing, zones, services)","tenant.settings:write":"Update tenant settings","tenant.reports:read":"Read reports and analytics","tenant.reports:export":"Export reports","tenant.businesses:read":"List businesses (delivery module)","tenant.businesses:write":"Create and update businesses","tenant.delivery:read":"List food orders","tenant.delivery:write":"Update food orders","tenant.wallets:read":"Read driver / customer wallet balances","tenant.wallets:write":"Adjust wallets and approve withdrawals","tenant.branding:write":"Update branding (logos, colors, copy)","rider.profile:read":"Read your profile","rider.profile:write":"Update your profile","rider.trips:read":"Read your trips","rider.trips:create":"Request a ride","rider.trips:cancel":"Cancel a trip you requested","rider.orders:read":"Read your delivery orders","rider.orders:create":"Place a delivery order","rider.addresses:write":"Manage your saved addresses","rider.payments:read":"List your payment methods","rider.wallet:read":"Read your wallet balance","driver.profile:read":"Read your driver profile","driver.status:write":"Go online or offline","driver.trips:read":"Read your assigned trips","driver.trips:accept":"Accept incoming ride offers","driver.trips:complete":"Mark trips as arrived / started / completed","driver.wallet:read":"Read your earnings and wallet","driver.documents:read":"Read the status of your uploaded documents"}}}}}}}