API overview

Base URL, authentication, request format, errors and rate limits shared by every endpoint.

Base URL

Every endpoint in this reference is relative to your RideWiseCore API base URL. The examples call it RWC_API_URL:

export RWC_API_URL="https://<your-ridewisecore-api-host>"
export RWC_API_KEY="rwc_…"

The real-time socket connects to the same host. See Real-time events.

Send an API key as a Bearer token on every request:

Authorization: Bearer rwc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

See Authentication for details.

Request bodies are JSON. Send Content-Type: application/json.
Responses are JSON. Timestamps are ISO-8601 strings in UTC, for example 2026-09-23T08:15:02.114Z.
Match IDs are UUIDs.

Every error uses the same envelope:

{
  "error": {
    "message": "Match not found",
    "statusCode": 404
  }
}

Status	Meaning
`400 Bad Request`	The body or a parameter failed validation. `message` describes what's wrong
`401 Unauthorized`	Missing, invalid or revoked API key
`402 Payment Required`	No payment method on file and no free trial running. Matching and tracking are locked
`403 Forbidden`	Subscription cancelled, suspended for non-payment, or disabled
`404 Not Found`	The resource doesn't exist for your tenant
`409 Conflict`	The resource is in a state that doesn't allow the action, for example cancelling a finished match
`429 Too Many Requests`	Rate limit exceeded
`5xx`	Something went wrong at RideWiseCore. Safe to retry with backoff

You can only ever see your own resources. A match ID that belongs to another tenant returns 404, exactly as if it didn't exist.

300 requests per minute per API key, across all REST endpoints. Each response includes:

Header	Meaning
`x-ratelimit-limit`	Requests allowed per window
`x-ratelimit-remaining`	Requests left in the current window
`x-ratelimit-reset`	Seconds until the window resets
`retry-after`	Sent with `429`: seconds to wait before retrying

Socket events (agent:location, ride:respond) don't count toward this limit. Use the socket, not polling, for high-frequency traffic.

Method	Path	Description
`POST`	`/matches`	Request an agent for a pickup
`GET`	`/matches/{matchId}`	Get a match's current state
`POST`	`/matches/{matchId}/cancel`	Cancel a match that's still searching
`WS`	Socket.IO `/`	Agent locations, ride offers, match updates

Account, API key, usage and billing management is done in the dashboard. Your application doesn't need any other endpoints.

Method	Path	Description
`GET`	`/health`	Service liveness: `{ "status": "ok" }`