Schemas

The objects the API takes and returns. Fields that may be left out or be null are not marked required.

AccountExport

Field	Type	Description
exported_at required	string (date-time)
feedback required	ExportedFeedback[]
organizations required	ExportedOrganization[]
sessions required	ExportedSession[]
user required	ExportedUser

Actor

Field	Type	Description
id required	string	usr_ or key_ ID.
name required	string	The person's email, or the key's name.
type required	string	user or api_key.

AddSourceSecret

Field	Type	Description
overlap_seconds	integer (int32) | null	How long the previous secret keeps working, 0 to 2592000 seconds; a day when left out.
value required	string	The secret as the provider shows it, such as Stripe's whsec_....

Alert

Field	Type	Description
id required	string
kind required	AlertKind
opened_at required	string (date-time)
resolved_at	string (date-time) | null	None while it is open.
rule_id required	string
subject_id	string | null	The src_ or dst_ ID it is about; none for quota.
subject_name	string | null	Its name now; none once it is deleted.
summary required	string
value required	integer (int64)	What the rule measured when it opened: minutes, events, deliveries or a percentage.

AlertChannel

Field	Type	Description
created_at required	string (date-time)
id required	string
target required	string	The address, or the URL's scheme, host and first path segment: the rest of a webhook URL, often its secret, is never shown again.
type required	ChannelType

AlertKind

What a rule watches.

"destination_failing" | "verification_failures" | "dead_letters" | "quota" | "source_silent"

AlertRule

Field	Type	Description
created_at required	string (date-time)
destination_id	string | null	The one destination watched (destination_failing, dead_letters); none watches every destination of the environment.
enabled required	boolean	A disabled rule is not evaluated, and its open alerts resolve.
id required	string
kind required	AlertKind
minutes required	integer (int32)	The window, 1 to 1440; for destination_failing and source_silent, how long the condition must have held.
open_alerts required	integer (int64)	Its alerts open now.
source_id	string | null	The one source watched (verification_failures, source_silent); none watches every source of the environment.
threshold required	integer (int32)	Events or deliveries in the window (verification_failures, dead_letters), or a percentage of the month's events (quota).
updated_at required	string (date-time)

ApiKey

Field	Type	Description
created_at required	string (date-time)
hint required	string	The secret's first characters, to tell keys apart.
id required	string
kind required	string	personal, service, or a revoked, unclassified legacy credential.
last_used_at	string (date-time) | null
name required	string
owner_user_id	string | null	Human subject for personal keys; absent for service and legacy keys.
revoked_at	string (date-time) | null
role required	string	Original permission ceiling, not the personal owner's effective role.

Attempt

Field	Type	Description
duration_ms required	integer (int32)
error	AttemptError | null	Why it failed, explained; none when it was answered with a 2xx (P3-61).
number required	integer (int32)
remote_ip	string | null	The address it connected to, once TCP connected (P3-56).
started_at required	string (date-time)
status_code	integer (int32) | null	The destination's response status, or none if the request failed.

AttemptError

A failed attempt, explained. The fault and outcome are a best guess from how the attempt failed, never certain.

Field	Type	Description
fault required	string	Who is probably at fault: destination, network, ricochet or configuration.
hint required	string	What to do about it.
kind required	string	How it failed: dns, refused, connect_timeout, tls, send, response_timeout, closed_by_peer, blocked_target or other (which includes a response that was not a 2xx).
message required	string	What happened.
outcome required	string	Whether the destination got the request: not_received, unknown (it may have, so a retry can repeat it) or received.
phase	string | null	Where it failed: connect, tls, send, wait_first_byte, read_headers or read_body; none when no connection phase applies.

AttemptErrorGroup

Field	Type	Description
count required	integer (int64)	Failed attempts in the group.
key required	string	The failure kind, the dst_ ID, or the minute (2026-10-14T18:17:00Z).
name	string | null	The destination's name, when grouped by destination and it still exists.
slowest required	SlowestAttempt	The one that took longest.

AttemptErrors

Field	Type	Description
after required	string (date-time)
before required	string (date-time)
group_by required	string
groups required	AttemptErrorGroup[]	By count, largest first; by minute, oldest first. At most 500.
total required	integer (int64)	Failed attempts in the range, in every group.

AuditEntry

One line of the log.

Field	Type	Description
action required	string	<subject>.<verb>: source, destination or connection .created, .updated or .deleted; environment.created, .updated or .deleted; project.created, .renamed or .deleted; organization.renamed; member.joined, .role_changed, .removed or .left; invite.created, .revoked or .declined; api_key.created or .revoked; alert_rule.created, .updated or .deleted; alert_channel.created or .deleted; replay.created; replay_job.created, .started, .paused or .cancelled; event.resent or .released.
actor	Actor | null	Who did it; absent when it was not done through the API, or the person or key is gone.
actor_name	string | null	The person's email or the key's name when it was done, kept after they are gone.
at required	string (date-time)
details required	object	What changed, by action: fields for an update, from and to for a role, role for an invite or key; never secret values.
environment_id	string | null
id required	integer (int64)	Increases with each line; pass as before for older ones.
project_id	string | null
subject_id	string | null	What it was done to; it may no longer exist.
subject_name	string | null	Its name or address at the time.

AuditPage

One page of the log.

Field	Type	Description
data required	AuditEntry[]	Newest first.
next_before	integer (int64) | null	Pass as before for the next, older page; absent on the last page.

Body

Field	Type	Description
base64 required	string	The body's exact bytes.
text	string | null	The body as text, when it is valid UTF-8.

BuildUpdate

Field	Type	Description
subject required	string	The email's subject.
test	boolean	Send it only to OWNER_EMAIL, to read it first. Not recorded.
text required	string	The email's plain text; the unsubscribe link is added after it.

BuildUpdateSent

Field	Type	Description
recipients required	integer (int64)	The emails queued.
test required	boolean

Candidate

A waitlist signup that can be invited, with its survey answers.

Field	Type	Description
current_tool	string | null
email required	string
events	string | null
fit required	integer (int32)	Survey fit, 0 to 7; the order invites go out in.
providers	string[] | null
signed_up_at required	string (date-time)
team	string | null

Certificate

Field	Type	Description
expires_at required	string (date-time)
issuer required	string
subject required	string

ChallengeAnswer

Field	Type	Description
challenge required	string
code required	string	A code from the authenticator app, or a recovery code.

Change

One change.

Field	Type	Description
action required	string	created, updated or deleted.
actor	Actor | null	Who made it; absent when it was not made through the API, or the person or key is gone.
changed_at required	string (date-time)
fields required	string[]	For updated, what changed: column names such as url or paused, and secrets or credential. Never the values.
id required	integer (int64)	Increases with each change; pass as before for older ones.
name	string | null	Its name at the time; a connection's is its source's and destination's.
subject required	string	source, destination or connection.
subject_id required	string	Its src_, dst_ or con_ ID; it may no longer exist.

ChangePage

One page of changes.

Field	Type	Description
data required	Change[]	Newest first.
next_before	integer (int64) | null	Pass as before for the next, older page; absent on the last page.

ChannelType

"email" | "webhook"

CheckDestination

Field	Type	Description
method	CheckRequest

CheckRequest

What to send.

"head" | "options" | "event"

CheckSignature

Field	Type	Description
secret	string | null	A secret to check with, as the provider shows it; omitted, the source's current secrets.

CheckStep

One step of the request.

Field	Type	Description
detail	string | null	What it found: the address, the certificate, the status.
duration_ms	integer (int64) | null
name required	string	dns (the name lookup and the address rules), connect, tls, send, first_byte or status.
state required	string	ok, failed, skipped (TLS for an http URL) or not_run (after the step that failed).

CheckedWith

Which secret was checked.

"candidate" | "current"

Circuit

A destination's circuit breaker, as the gateway sees it now.

Field	Type	Description
consecutive_failures required	integer (int64)	Failed deliveries in a row.
in_flight required	integer (int64)	Requests to it in progress now.
opened_at	string (date-time) | null	When the circuit opened; null while closed.
retry_at	string (date-time) | null	When an open circuit lets a probe through.
state required	CircuitState

CircuitState

A circuit's state (P2-22).

"closed" | "open" | "half_open"

ClaimedInstant

Where a claimed URL now lives (P3-22).

Field	Type	Description
environment_id required	string	env_ ID.
project_id required	string	prj_ ID.
source_id required	string	src_ ID.

Code

A code from the authenticator app, or a recovery code.

Field	Type	Description
code required	string

Connection

Field	Type	Description
created_at required	string (date-time)
destination_id required	string
filter	object | null	Which events it takes; none takes them all. {"and": [...]}, {"or": [...]}, {"not": filter} or a condition {"path": path, <operator>: operand}, where a path is headers.<name>, body, body.<key>... or event_type (the provider's name for the event) and the operator is equals, one_of, exists, gt, gte, lt, lte or matches (a PCRE pattern). At most 8 levels and 100 nodes.
id required	string
paused required	boolean	A paused connection holds its deliveries until it is resumed.
source_id required	string
transformation	object[] | null	How the JSON body is reshaped for the destination; none sends it as stored. Up to 50 steps, in order: {"rename": path, "to": path}, {"drop": path}, {"add": path, "value": json}, {"add": path, "from": path} or {"map": path, "values": {...}, "default": json}, with paths into the body such as data.object.id.
updated_at required	string (date-time)

Count

Field	Type	Description
confirmed required	integer (int64)
key	string | null	The source or campaign; null when the signup had none.
submitted required	integer (int64)

CreateAlertChannel

Field	Type	Description
target	string	A member's email address, or the webhook's URL.
type	ChannelType	Read after the caller's access is checked.

CreateAlertRule

Field	Type	Description
destination_id	string | null	dst_ ID, for a destination rule; every destination when left out.
enabled	boolean | null
kind	AlertKind	Read after the caller's access is checked, so an unknown kind is a 422 only for someone who may make rules.
minutes	integer (int32) | null	Default 10 for destination_failing, 5 for verification_failures, 60 otherwise.
source_id	string | null	src_ ID, for a source rule; every source when left out.
threshold	integer (int32) | null	Default 10 for verification_failures, 1 for dead_letters, 80 for quota.

CreateApiKey

Field	Type	Description
kind	KeyKind	Defaults to personal. Service credentials require a human admin.
name required	string
role	string | null	Personal: optional ceiling, at most the caller's role (never owner). Service: required independent viewer or developer grant.

CreateConnection

Field	Type	Description
destination_id required	string
filter	object | null	As in Connection; every event when left out.
source_id required	string
transformation	object[] | null	As in Connection; the body as stored when left out.

CreateDestination

Field	Type	Description
name required	string
settings	DestinationSettings | null	The gateway's defaults when left out.
type	DestinationType | null	http when left out. A cli destination belongs to the caller (for an API key, the person who made it) and has no URL.
url	string | null	For an http destination: a public http or https URL.

CreateEnvironment

Field	Type	Description
kind required	string	staging or production (or dev, if it was deleted).

CreateInstant

Field	Type	Description
cli	boolean	From ricochet listen: the URL also gets a CLI destination to forward from.
turnstile_token	string | null	From the site's Turnstile widget: required unless cli, when the API checks Turnstile.

CreateReplayJob

Field	Type	Description
destination_environment_id	string | null	env_ ID of another of the project's environments the destination is in.
destination_id	string | null	dst_ ID to replay every event to; without one, each event goes to its original destinations.
rate_per_second	integer (int64) | null	Replays started per second, 1 to 100; default 10. The destination's own limits still apply.
selection required	Selection

CreateShare

Field	Type	Description
expires_in_hours	integer (int32) | null	How long the link works: 1 to 720 hours; 168 (a week) when left out.

CreateSource

Field	Type	Description
deduplication	Deduplication | null
handshake	Handshake | null	Defaults to none.
methods	Method[] | null	Defaults to ["POST"].
name required	string
response	SourceResponse | null	Defaults to 200 with an empty body.
search_fields	string[] | null	Up to 5 fields its events can be searched by; none by default.
verification	Verification | null	Defaults to {"method": "none"}: every request is accepted.

CreatedDestination

A new destination, with its first signing secret.

Destination & object

CredentialType

"bearer" | "basic" | "header"

Deduplication

Provider identity policy, independent of signature verification.

object | object | object

Delivery

Field	Type	Description
attempts required	Attempt[]	In order.
connection_id	string | null	The connection that routed it (con_ ID), which may since be deleted.
created_at required	string (date-time)
destination_id required	string
destination_name	string | null	The destination's name, unless it was deleted.
id required	string
status required	string	pending, delivered or dead.
updated_at required	string (date-time)

DeliveryStatus

A delivery's status.

"pending" | "delivered" | "dead"

Destination

Field	Type	Description
created_at required	string (date-time)
credential	DestinationCredential | null	The credential sent with each delivery, without its secret.
id required	string
name required	string
owner_id	string | null	The developer whose ricochet listen sessions a cli destination relays to.
owner_name	string | null	The owner's name, or email when they have none.
paused required	boolean	A paused destination holds its deliveries until it is resumed.
settings required	DestinationSettings	Retry policy, limits and header rules.
type required	DestinationType
updated_at required	string (date-time)
url	string | null	Where an http destination delivers.

DestinationCheck

Field	Type	Description
certificate	Certificate | null	The destination's TLS certificate, for an https URL.
duration_ms required	integer (int64)	The whole check.
error	AttemptError | null	How it failed and what to do, as for an attempt (P3-61); none when it was answered with a 2xx.
method required	string	HEAD, OPTIONS or POST.
remote_ip	string | null	The checked address it connected to.
request required	CheckRequest
started_at required	string (date-time)
status_code	integer (int32) | null	The response's status, if one came.
steps required	CheckStep[]	In order; each is ok until the one that failed.
url	string | null

DestinationCredential

What is shown of a credential; its secret never is.

Field	Type	Description
header	string | null	The header a header credential is sent in, lowercase.
type required	CredentialType
updated_at required	string (date-time)
username	string | null	A basic credential's username.

DestinationHealth

Field	Type	Description
after required	string (date-time)
before required	string (date-time)
errors required	ErrorGroup[]	The most frequent first; at most 10.
failed_attempts required	integer (int64)	The range's failed attempts, in every group.
last_failure_at	string (date-time) | null	The latest failed attempt, in any range.
last_success_at	string (date-time) | null	The latest attempt answered with a 2xx, in any range; none if no stored attempt was.

DestinationSettings

Unset fields use the gateway's defaults.

Field	Type	Description
headers	HeaderRule[] | null	Applied in order to each delivery's headers; at most 50.
hold_max_age_seconds	integer (int32) | null	How long a held delivery waits before it fails, 60 seconds to 7 days; 1 day when left out.
hold_max_events	integer (int32) | null	How many deliveries it holds at most, 1 to 1000; 100 when left out.
hold_offline	boolean | null	CLI destinations only (P3-26): hold deliveries while no ricochet listen session is connected and send them when one joins. Off when left out: such a delivery fails, and the event stays replayable.
max_age_seconds	integer (int32) | null	How long after the event arrived retries stop, 60 seconds to 30 days; 3 days when left out.
max_attempts	integer (int32) | null	Attempts before a delivery is dead, 1 to 50; 10 when left out.
max_in_flight	integer (int32) | null	Requests in flight at once, 1 to 100; 10 when left out.
max_per_second	integer (int32) | null	Requests per second, 1 to 1000; no limit when left out.
retry_statuses	integer (int32)[] | null	3xx and 4xx statuses to retry as well as 5xx, 408 and 429.
timeout_ms	integer (int32) | null	How long one attempt waits for an answer, 1000 to 60000 ms; 30 s when left out.

DestinationType

"http" | "cli"

DeviceLogin

A login waiting for the person to confirm it.

Field	Type	Description
device_code required	string	What the CLI polls with; secret.
expires_in required	integer (int64)	Seconds until the codes stop working.
interval required	integer (int64)	Seconds to wait between polls.
user_code required	string	What the person checks in the dashboard.
verification_uri required	string	Where the person confirms it.
verification_uri_complete required	string	The same, with the code filled in.

DeviceToken

The poll's answer while the login is open, and once it is confirmed.

Field	Type	Description
expires_at	string (date-time) | null	With approved: when the token stops working.
status required	DeviceTokenStatus	pending until the person confirms, then approved.
token	string | null	With approved, once: sent as Authorization: Bearer rd_….
user	User | null	With approved: who signed in.

DeviceTokenRequest

Field	Type	Description
device_code required	string

DeviceTokenStatus

"pending" | "approved"

Done

The JSON answer to a request that worked.

Field	Type	Description
ok required	boolean

Environment

Field	Type	Description
id required	string
kind required	string	dev, staging or production.
retention_days	integer (int64) | null	How many days its events are kept: its own limit or its plan's. None keeps them for the operational ceiling, 30 days by default (P2-29).

EnvironmentDetail

An environment with its limits.

Field	Type	Description
created_at required	string (date-time)
effective required	Limits	In force: the plan's, lowered by the overrides.
id required	string
kind required	string	dev, staging or production.
limits required	Limits	Its own overrides.
plan required	Limits	The organization's plan; null is unlimited.

ErrorExample

Field	Type	Description
attempt required	integer (int32)	The attempt's number in its delivery.
delivery_id required	string
event_id required	string

ErrorGroup

Failed attempts that failed the same way: the same kind, phase and status.

Field	Type	Description
count required	integer (int64)	Failed attempts in the range.
example required	ErrorExample	The latest of them.
fault required	string
hint required	string
kind required	string	As in AttemptError.
last_seen_at required	string (date-time)
message required	string	What happened, as in AttemptError.
outcome required	string
phase	string | null
status_code	integer (int32) | null	The response's status, for a response that was not a 2xx.

Event

EventSummary & object

EventPage

Field	Type	Description
data required	EventSummary[]	Newest first.
next_cursor	string | null	Pass as cursor for the next, older page; absent on the last page.

EventStatus

Where an event stands, from its deliveries (replays not counted).

"received" | "pending" | "delivered" | "failed"

EventSummary

Field	Type	Description
content_type	string | null	The first Content-Type header, if any.
delivered_count required	integer (int64)	Of those, how many succeeded.
delivery_count required	integer (int64)	Original deliveries, one per destination.
event_type	string | null	As its provider names it: the X-GitHub-Event, X-Gitlab-Event or X-Shopify-Topic header, else the JSON body's type, event_type or event.
failed_attempt_count required	integer (int64)	Attempts on those deliveries with no response or a response that was not a 2xx, including ones a retry later made good.
id required	string
last_error_kind	string | null	The latest failed attempt's kind (P3-56; other for one recorded before kinds were), or none without a failed attempt.
last_error_status	integer (int32) | null	That attempt's response status, when it got a response.
method required	string
quarantined required	boolean	Failed verification and held, not delivered, by the source's quarantine policy (P2-14).
received_at required	string (date-time)
size required	integer (int32)	The body's size in bytes.
source_id required	string
status required	EventStatus
target required	string	The request's path and query, as received.
verification required	VerificationResult
verification_reason	string | null	Why verification failed, as a reason code.

ExportedFeedback

Field	Type	Description
created_at required	string (date-time)
message required	string
page	string | null

ExportedOrganization

Field	Type	Description
id required	string
joined_at required	string (date-time)
name required	string
projects required	ExportedProject[]
role required	string

ExportedProject

Field	Type	Description
created_at required	string (date-time)
id required	string
name required	string

ExportedSession

Field	Type	Description
client	string | null
created_at required	string (date-time)
expires_at required	string (date-time)
last_used_at required	string (date-time)
user_agent	string | null

ExportedUser

Field	Type	Description
created_at required	string (date-time)
email required	string
github_linked required	boolean	Signs in with GitHub too.
id required	string
name	string | null
onboarding	object | null	The first-run setup's answers (P3-10), if given.
second_factor required	boolean

Feedback

Field	Type	Description
created_at required	string (date-time)
email required	string
message required	string
page	string | null	The dashboard path it was sent from.

FinishOnboarding

The first-run setup's end (P3-10).

Field	Type	Description
needs	string | null	Which other providers and destinations they will connect, in their words; at most 2,000 characters.
provider	string | null	The provider picked to start with, e.g. stripe.
skipped	boolean	Skipped rather than finished.

Fixture

FixtureSummary & object

FixtureSummary

A fixture without its request, as the list shows it.

Field	Type	Description
description required	string
event_type required	string	As the events list shows it.
provider required	string	The preset it belongs to: stripe or github.

Handshake

A provider's URL check that a source answers without creating an event (P2-05): the challenge it sends is echoed back.

"none" | "slack" | "meta" | "microsoft_graph" | "dropbox"

Header

Field	Type	Description
name required	string
value required	string

HeaderRule

One of {"set": name, "value": value} (replaces the header or adds it), {"add": name, "value": value} (adds it, keeping others) or {"remove": name}. Credentials go in the destination's credential.

Field	Type	Description
add	string | null
remove	string | null
set	string | null
value	string | null	For set and add; at most 8 KiB, on one line.

HeldDeliveries

Deliveries held by a pause, for one destination and connection.

Field	Type	Description
connection_id	string | null	con_ ID; null for a replay's deliveries.
count required	integer (int64)
destination_id required	string	dst_ ID.
oldest_held_at required	string (date-time)

HeldDeliveriesList

Field	Type	Description
data required	HeldDeliveries[]	Oldest first.

HmacAlgorithm

"sha1" | "sha256" | "sha512"

InstantToken

Field	Type	Description
token required	string	The ri_ token.

InstantView

A temporary URL and what it received.

Field	Type	Description
destination_id	string | null	With a CLI destination: its dst_ ID.
events required	Event[]	The newest events first, at most 20.
events_left required	integer (int64)	How many more events it takes; ingest may let a few more through while it catches up.
expires_at required	string (date-time)
url required	string
view_url required	string	The live page, with the token in its fragment.

Invite

An invite and whether it was used.

Field	Type	Description
email required	string
from_waitlist required	boolean	Whether it came from the waitlist.
invited_at required	string (date-time)
signed_up_at	string (date-time) | null	When its account was made; null until the first sign-in.

InviteRequest

A batch from the waitlist, or addresses by hand.

Field	Type	Description
count	integer (int64) | null	Invites this many from the waitlist, best fit first (1 to 500).
emails	string[]	Invites these addresses, on the waitlist or not.

Invited

Field	Type	Description
emails required	string[]	Newly invited, each sent an invite email; addresses already invited or with an account are left out.

Issue

Deliveries to one destination that failed for good the same way.

Field	Type	Description
cause required	string	A status class (5xx) or an error kind (refused): select a bulk replay by it with causes.
deliveries required	integer (int64)	Original deliveries, one per event and destination.
destination_id required	string
destination_name	string | null	Its name now; none once it is deleted.
example_event_id required	string	The latest of them.
fault required	string
first_failed_at required	string (date-time)	When the first and the latest of them failed for good.
hint required	string
last_failed_at required	string (date-time)
message required	string	What happened, how to fix it and whose fault it probably is, as for the latest attempt (P3-61).

IssueList

Field	Type	Description
after required	string (date-time)
before required	string (date-time)
data required	Issue[]	The largest first; at most 100.

JoinRequest

The join form's fields. A JSON body has the same names, with string values; unknown fields are ignored. The attribution fields come from the page script; a plain form post gets them from its Referer instead.

Field	Type	Description
cf-turnstile-response	string | null	The Cloudflare Turnstile token, checked when the API has TURNSTILE_SECRET.
email required	string
fbclid	string | null
gclid	string | null
landing_page	string | null	The landing page's path and query, e.g. /?utm_source=google.
li_fat_id	string | null
msclkid	string | null
ref	string | null	A share link's referral code (10 hex characters).
referrer	string | null	The page that linked to the landing page; only its origin and path are kept.
ttclid	string | null
utm_campaign	string | null
utm_content	string | null
utm_medium	string | null
utm_source	string | null
utm_term	string | null

KeyKind

"personal" | "service"

Limits

Limits by name; absent or null means none (unlimited, or the plan's).

Field	Type	Description
ingest_max_body_bytes	integer (int64) | null	The largest request body a source accepts.
ingest_max_header_bytes	integer (int64) | null	The most header bytes (names and values) a request may carry.
ingest_requests_per_minute	integer (int64) | null	Requests each source accepts a minute.
retention_days	integer (int64) | null	Days its events are kept.

LinkRequest

Field	Type	Description
email required	string
turnstile_token	string | null	The Cloudflare Turnstile token, checked when the API has TURNSTILE_SECRET.

Listeners

A CLI destination's ricochet listen sessions, as the gateway sees them now (#415).

Field	Type	Description
sessions required	integer (int64)	Sessions connected now; none for an HTTP destination.

LogPage

Field	Type	Description
lines required	string[]	Matching lines, oldest first, each one JSON object as logged. API keys and bearer credentials are replaced with [redacted].
next_offset	integer | null	Pass as offset for the next, newer lines; absent at the end.
offset required	integer	The position of the first returned line among the matching ones.
service required	string
total required	integer	Matching lines in all the service's files.

Member

Field	Type	Description
email required	string
joined_at required	string (date-time)
name	string | null
role required	string	owner, admin, developer or viewer.
user_id required	string

MemberInvite

Field	Type	Description
created_at required	string (date-time)
email required	string
expires_at required	string (date-time)
id required	string
invited_by	string | null	Who sent it; absent once they are gone.
role required	string	admin, developer or viewer.

MemberInviteRequest

Field	Type	Description
email required	string
role required	string	admin, developer or viewer.

MemberList

The members, oldest first, and the open invites, newest first.

Field	Type	Description
invites required	MemberInvite[]
members required	Member[]

Method

An HTTP method a source accepts; others get 405.

"GET" | "POST" | "PUT" | "PATCH" | "DELETE"

MetricBucket

One bucket's counts. Latency percentiles are of the attempts' durations; when several destinations are combined, each is their mean weighted by attempts, an approximation.

Field	Type	Description
attempts required	integer (int64)	Delivery attempts that started in the bucket.
events required	integer (int64)	Events stored.
failed required	integer (int64)
failed_by_kind required	object	The failed attempts by kind (P3-63): a failure without a response by its kind (closed_by_peer, refused...; other when recorded before kinds were), a response that was not a 2xx by its status class (5xx). Empty for attempts rolled up before kinds were counted.
p50_ms	integer (int32) | null	None without attempts.
p95_ms	integer (int32) | null
p99_ms	integer (int32) | null
quarantined required	integer (int64)	Of those, held after failed verification (P2-14).
start required	string (date-time)	When the bucket starts; it lasts one resolution.
succeeded required	integer (int64)	Of those, answered with a 2xx.

Metrics

Field	Type	Description
after required	string (date-time)
before required	string (date-time)
buckets required	MetricBucket[]	Every bucket in the range, oldest first, empty ones included.
resolution required	Resolution
totals required	MetricBucket	The whole range, its start being the first bucket's.

NameRequest

Field	Type	Description
name required	string

NewApiKey

A new key, with the secret: the only time it is shown.

ApiKey & object

NewInstant

A new temporary URL; its token is shown only now.

Field	Type	Description
destination_id	string | null	With cli: the dst_ ID to listen on with the token.
expires_at required	string (date-time)
token required	string	ri_…: opens the live page and lets the CLI listen, until it expires or is claimed. Keep it private.
url required	string	Where to send webhooks.
view_url required	string	The live page, with the token in its fragment.

NewShare

A new link: its URL is shown only now.

Share & object

NewSigningSecret

A secret just made: the only time its value is shown.

SigningSecret & object

OnFailure

What happens to a request that fails verification.

"reject" | "quarantine"

OnboardingAnswer

What someone said in the first-run setup (P3-10).

Field	Type	Description
email required	string
needs	string | null	What else they will connect, in their words.
onboarded_at required	string (date-time)
provider	string | null	The provider they started with.
skipped required	boolean	Skipped rather than finished.

Organization

Field	Type	Description
id required	string
name required	string
projects required	Project[]
role required	string	The signed-in user's role: owner, admin, developer or viewer.

PendingDeviceLogin

A login as the confirm page shows it.

Field	Type	Description
client required	string
created_at required	string (date-time)
expires_at required	string (date-time)
user_code required	string

Problem

An error. type is omitted, which RFC 9457 reads as about:blank: the status says what kind of problem it is.

Field	Type	Description
detail required	string	What went wrong, written for the person using the client.
status required	integer (int32)
title required	string	The status's reason phrase.

Project

Field	Type	Description
environments required	Environment[]
id required	string
name required	string
organization_id required	string

ReadShare

Field	Type	Description
token required	string	The token after # in the link.

ReceivedInvite

An invite to the signed-in person.

Field	Type	Description
expires_at required	string (date-time)
id required	string
invited_by	string | null	The inviter's name or email; absent once they are gone.
organization_id required	string
organization_name required	string
role required	string

RecoveryCodes

Recovery codes, shown once: each signs in once in place of a code.

Field	Type	Description
codes required	string[]

Released

A released event.

Field	Type	Description
event_id required	string	evt_ ID.
released required	boolean

Replay

Field	Type	Description
delivery_id required	string	The replay's own delivery, with its own attempts.
destination_environment_id required	string	The event's own environment unless the replay was sent to another.
destination_id required	string
event_id required	string
id required	string
label required	string
number required	integer (int64)	The event's first replay is 1.
requested_at required	string (date-time)
requested_by required	string	Who asked: a usr_ or key_ ID.

ReplayEvent

Field	Type	Description
destination_environment_id	string | null	env_ ID of another of the project's environments the destination is in; the event's own by default.
destination_id required	string	dst_ ID: the event's original destination or another one.

ReplayJob

Field	Type	Description
created_at required	string (date-time)
destination_environment_id required	string	Where its replays go: the events' environment unless sent to another.
destination_id	string | null
events required	integer (int64)	Events matched.
finished_at	string (date-time) | null
id required	string
processed required	integer (int64)	Of total, replayed or skipped so far.
rate_per_second required	integer (int64)
requested_by required	string
selection required	Selection
skipped required	integer (int64)	Of processed, events retention removed before their turn.
started_at	string (date-time) | null
status required	ReplayJobStatus
summary required	ReplayJobSummary
total required	integer (int64)	Replays it makes: one per event and destination.

ReplayJobStatus

"ready" | "running" | "paused" | "completed" | "cancelled"

ReplayJobSummary

How a job's replays went so far.

Field	Type	Description
delivered required	integer (int64)
failed required	integer (int64)	Dead, including those a cancellation stopped.
not_sent required	integer (int64)	A cancelled job's replays it never reached.
pending required	integer (int64)	Still being delivered.
skipped required	integer (int64)	Events retention removed before their turn.

ReplayList

Field	Type	Description
data required	ReplayWithStatus[]	Oldest first.

ReplayWithStatus

Replay & object

Resolution

"minute" | "hour"

RoleRequest

Field	Type	Description
role required	string	owner, admin, developer or viewer.

RotateSigningSecret

Field	Type	Description
overlap_seconds	integer (int32) | null	How long the previous secret keeps signing, 0 to 2592000 seconds; a day when left out.

RuleTestResult

Field	Type	Description
body	string | null	The body the transformation gives; null without one.
error	string | null	Why the transformation fails, as the delivery would.
event_id required	string	evt_ ID.
found required	boolean	False when the event is not stored in this environment.
passes	boolean | null	Whether it passes the filter.

RuleTestResults

Field	Type	Description
data required	RuleTestResult[]	One per event, in the order asked.

SearchField

A search field's value, as stored with the event.

Field	Type	Description
name required	string
value required	string

SecondFactor

Whether the second factor is on.

Field	Type	Description
enabled required	boolean
recovery_codes_left required	integer (int64)	Recovery codes not used yet.

SecondFactorRequired

The answer to a sign-in that needs the second factor.

Field	Type	Description
challenge required	string	Send it back with the code to POST /api/auth/second-factor.

SecondFactorSetup

A second factor being set up: the secret to put in an authenticator app.

Field	Type	Description
qr_svg required	string	The URI as a QR code, an SVG image.
secret required	string	Base32, to type in.
uri required	string	The otpauth:// URI the QR code holds.

Selection

Which events a bulk replay takes. Quarantined events and provider duplicates are never taken.

Field	Type	Description
causes	string[] | null	Why an original delivery's last attempt failed, as Issues groups them (P4-14): a status class (5xx) or, with no response, the error kind (refused). Events with such a delivery, in one of statuses and to one of destination_ids when those are given.
destination_ids	string[] | null	dst_ IDs: events with an original delivery to one of these, in one of statuses when both are given. Without a job destination, each event is replayed to those it matched.
event_types	string[] | null	Event types, as the events list shows them.
filter	object | null	A connection filter (P3-03) the event must pass.
from required	string (date-time)	Received at or after.
source_ids	string[] | null	src_ IDs; any of them.
statuses	DeliveryStatus[] | null	Events with an original delivery in one of these.
to required	string (date-time)	Received before.
unresolved	boolean | null	true leaves out an original delivery whose destination a replay of the event has delivered to, or is delivering to.

SendFeedback

Field	Type	Description
message required	string	1 to 5,000 characters.
page	string | null	The dashboard path it was sent from.

SendTestEvent

Field	Type	Description
body required	string	The raw body, as the provider would send it; at most 60,000 bytes.
headers	string[][] | null	[name, value] pairs, in order; at most 100. Ricochet adds the signature unless sign is false.
method	string | null	One the source accepts. Default POST.
sign	boolean | null	Sign it with the source's newest secret, as its verification method expects. Default true; false sends it exactly as given.

Session

The signed-in user and everything they can open.

Field	Type	Description
organizations required	Organization[]
user required	User

SessionInfo

A session the person is signed in with: a browser, or a CLI login.

Field	Type	Description
client	string | null	The machine a CLI login was made for; none for a browser.
created_at required	string (date-time)
current required	boolean	The session this request came with.
expires_at required	string (date-time)
id required	string
last_used_at required	string (date-time)	To the nearest five minutes.
user_agent	string | null	The browser, as it named itself when it signed in.

SetCredential

The credential to send; it replaces any the destination had.

object | object | object

Share

Field	Type	Description
created_at required	string (date-time)
created_by required	string	Who made it: a usr_ or key_ ID.
event_id required	string	evt_ ID.
expires_at required	string (date-time)
id required	string

ShareList

Field	Type	Description
data required	Share[]	The links that still work, newest first.

SharedEvent

The event behind a link.

Field	Type	Description
event required	Event	Credentials and signatures are masked.
expires_at required	string (date-time)	When the link stops working.

SignatureCheck

Field	Type	Description
method required	string	The source's verification method, as it is now.
reason	string | null	Why it failed, as stored on events.
result required	string	verified, not_configured or failed.
secret required	CheckedWith
steps required	SignatureStep[]

SignatureEncoding

"hex" | "base64"

SignatureStep

One step of the check.

Field	Type	Description
allowed	string[] | null	The source's allowed address ranges.
body_bytes	integer (int64) | null
detail required	string
expected	string | null	The signature the secret computes; with the current secrets, its first 12 characters and an ellipsis.
header	string | null	The header it read.
name required	string	method, allowed_ips, content_digest, settings, header, timestamp, signed_content, signature or credential.
ok	boolean | null	Null when the step was not checked.
received	object | null	What the request carried: a header value, a timestamp, or a list of signatures.
template	string | null	What is signed, with {body} standing for the body as received.

SigningSecret

Field	Type	Description
created_at required	string (date-time)
expires_at	string (date-time) | null	When it stops signing; none while it is the current secret.
id required	string

SimulateFailures

Field	Type	Description
count	integer (int32) | null	How many of the next deliveries: 1 to 100, default 1.
mode required	SimulationMode | null	Required; checked after access, so another tenant's ID is a 404.
status_code	integer (int32) | null	With status: 200 to 599.

Simulation

A destination's simulation in progress.

Field	Type	Description
created_at required	string (date-time)
destination_id required	string	dst_ ID.
mode required	SimulationMode
remaining required	integer (int32)	Deliveries left to fail.
requested_by required	string	Who set it: a usr_ or key_ ID.
status_code	integer (int32) | null

SimulationMode

How the simulated deliveries fail.

"timeout" | "status"

SimulationState

Field	Type	Description
simulation	Simulation | null	Null when none is left.

SlowestAttempt

Field	Type	Description
delivery_id required	string
destination_id required	string
duration_ms required	integer (int32)
event_id required	string
message required	string	How it failed, explained as the Events API does (P3-61).
number required	integer (int32)
project_id required	string
started_at required	string (date-time)
status_code	integer (int32) | null

Source

Field	Type	Description
created_at required	string (date-time)
deduplication required	Deduplication
handshake required	Handshake
id required	string
methods required	Method[]
name required	string
response required	SourceResponse
search_fields	string[]	Fields its events can be searched by (P4-09), as filter paths: body.data.object.customer or headers.x-shop-id.
updated_at required	string (date-time)
url required	string	Where providers send webhooks.
verification required	Verification

SourceResponse

What a source answers the sender once a request is stored. Unset fields mean 200 with an empty body.

Field	Type	Description
body	string | null	At most 4 KiB; none for 204.
content_type	string | null	The body's type; text/plain when a body has none.
status	integer (int32) | null	200 to 204.

SourceSecret

Field	Type	Description
created_at required	string (date-time)
expires_at	string (date-time) | null	When it stops verifying; none while it is the current secret.
id required	string

StartDeviceLogin

Field	Type	Description
client	string | null	What the token will be called, e.g. the machine's name.

Stats

Field	Type	Description
by_campaign required	Count[]
by_source required	Count[]
confirmed required	integer (int64)
referred required	integer (int64)	Signups that came through someone's share link.
submitted required	integer (int64)
unsubscribed required	integer (int64)

SurveyRequest

Every answer is optional; unknown values are dropped. A form post repeats providers; JSON sends it as an array.

Field	Type	Description
current_tool	"none" | "tunnel" | "hookdeck" | "svix" | "in_house" | "other"	What they use today
events	"lt_10k" | "10k_100k" | "100k_1m" | "gt_1m" | "unsure"	Webhook events a month
providers	"stripe" | "github" | "shopify" | "twilio" | "slack" | "paypal" | "other"[]	Providers whose webhooks they receive
team	"solo" | "2_10" | "11_50" | "51_plus"	Team size

TestEvent

Field	Type	Description
event_id required	string	The stored event: open it in the events list.
quarantined required	boolean	Failed verification and held by the source's policy, not delivered.
received_at required	string (date-time)
resent_from	string | null	For an edited copy (P3-17), the event it was resent from.
verification required	TestVerification

TestRules

Field	Type	Description
connection_id	string | null	con_ ID: its current filter and transformation, instead of the two above.
event_ids	string[]	1 to 50 evt_ IDs.
filter	object | null	A connection filter (P3-03); none passes every event.
transformation	object[] | null	A connection transformation's steps (P2-38); none keeps the body.

TestVerification

Field	Type	Description
reason	string | null	Why it failed, as a reason code.
status required	VerificationResult

UpdateAlertRule

What can change; to watch something else, make another rule.

Field	Type	Description
enabled	boolean | null
minutes	integer (int32) | null
threshold	integer (int32) | null

UpdateConnection

The fields to change; the others stay. null clears a filter or a transformation.

Field	Type	Description
filter	object | null
paused	boolean | null
transformation	object[] | null

UpdateDestination

The fields to change; the others stay. settings replaces the whole object.

Field	Type	Description
name	string | null
paused	boolean | null
settings	DestinationSettings | null
url	string | null

UpdateEnvironment

Field	Type	Description
limits	Limits	Replaces every override: a limit left out or null is the plan's.

UpdateSource

The fields to change; the others stay. response and verification and deduplication replace the whole object.

Field	Type	Description
deduplication	Deduplication | null
handshake	Handshake | null	Defaults to none.
methods	Method[] | null
name	string | null
response	SourceResponse | null
search_fields	string[] | null	Replaces the list; events already stored keep what they had.
verification	Verification | null

User

Field	Type	Description
email required	string
id required	string
name	string | null
onboarded	boolean	Finished or skipped the first-run setup (P3-10).

UserCode

The code the person typed or followed a link with.

Field	Type	Description
user_code required	string

Verification

How a source verifies requests. Which fields apply depends on method; the others must be left out.

Field	Type	Description
algorithm	HmacAlgorithm | null	hmac; sha256 when left out.
allowed_ips	string[] | null	Any method: the only addresses requests are accepted from, as IPv4 or IPv6 CIDR ranges.
encoding	SignatureEncoding | null	hmac; hex when left out.
field	string | null	shared_secret: the body field holding the token; a dotted path in JSON.
header	string | null	hmac: the signature header. api_key: the key's header.
method required	VerificationMethod
on_failure	OnFailure | null	Any method; reject when left out.
prefix	string | null	hmac: text before the signature, such as sha256=.
query	string | null	api_key: the key's query parameter, instead of header.
signed_content	string | null	hmac: what is signed, {body} when left out; {timestamp} is the timestamp_header value.
timestamp_header	string | null	hmac, when signed_content has {timestamp}.
tolerance_seconds	integer (int32) | null	hmac with a timestamp, and stripe: how far a signed timestamp may be from now, in seconds; 300 when left out.

VerificationMethod

"none" | "hmac" | "stripe" | "github" | "basic" | "api_key" | "shared_secret"

VerificationResult

How the source verified the event when it arrived (P2-08).

"verified" | "not_configured" | "failed"

VerifyRequest

Field	Type	Description
token required	string	The token from the link.