Skip to content
Ricochet docs

API reference

The public API manages an environment's sources, destinations and connections, reads its events and metrics, and replays events. It is what the dashboard and the CLI use, under a stable path.

https://getricochet.dev/api/v1

The machine-readable description is at /api/v1/openapi.json(OpenAPI 3.1), for generating a client.

Authentication

Create an API key in the dashboard under Developers. A key is shown once, starts withrk_ and acts in one environment of one project. Send it as a bearer token:

Terminal window
curl https://getricochet.dev/api/v1/projects/prj_…/environments/env_…/sources \
  -H "Authorization: Bearer rk_…"

Every path starts with the project and environment IDs (prj_…, env_…), which the Developers page shows next to the key. A missing, invalid or revoked key gets 401; a key for another environment gets 404.

Requests and responses

  • Bodies are JSON (Content-Type: application/json), and so are answers.
  • IDs carry their kind as a prefix: src_, dst_, con_, evt_, dlv_.
  • Times are RFC 3339 in UTC.
  • Lists of events are paginated newest first: pass a page's next_cursor as cursor to get the next, older page. There is no next_cursor on the last page.
  • Secrets are write-only: they are accepted, but never returned, except a destination's signing secret when it is made.
  • Every answer carries an x-request-id header; quote it when you ask for help.

Errors

Errors are problem details (RFC 9457), with Content-Type: application/problem+json:

{
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Enter a valid URL."
}

detail is written for the person using your client, so it can be shown as is.

Rate limits

Each key may make a limited number of requests a minute (600 during the alpha). Over it the answer is429, with a Retry-After header in seconds.

Versioning

Version 1 only changes by adding: new operations, new fields in answers and new optional parameters. Ignore fields you don't know. The paths under /api/ without v1 are the dashboard's own and can change at any time; API keys are refused there.

Resources

  • Sources: Where webhooks come in (9 operations)
  • Destinations: Where events are delivered (18 operations)
  • Connections: Which destinations each source's events go to (6 operations)
  • Changes: Who changed which source, destination or connection (1 operation)
  • Events: Requests the gateway stored (10 operations)
  • Alerts: Rules an environment is watched for, and the alerts they raise (10 operations)
  • Metrics: Volume, delivery success and latency over time (1 operation)
  • Replays: Stored events sent again, one at a time or in bulk (7 operations)
  • Schemas: every object the operations take and return.