Destinations

Where events are delivered. Authentication, errors and limits are on the overview.

List destinations

GET /api/v1/projects/{project_id}/environments/{environment_id}/destinations

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID

Responses

Status	Description	Body
200	Oldest first	Destination[]
401	No API key, or it is invalid or revoked	Problem
404	No such environment, or no access	Problem
429	Over the key's rate limit; Retry-After says when to try again	Problem

Create destination

POST /api/v1/projects/{project_id}/environments/{environment_id}/destinations

A new HTTP destination, or the caller's CLI destination.

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID

Request body

JSON, 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.

Responses

Status	Description	Body
201	Created, with its signing secret	CreatedDestination
401	No API key, or it is invalid or revoked	Problem
404	No such environment, or no access	Problem
409	The caller already has a CLI destination here	Problem
422	Invalid name, URL or settings	Problem
429	Over the key's rate limit; Retry-After says when to try again	Problem

Delete destination

DELETE /api/v1/projects/{project_id}/environments/{environment_id}/destinations/{destination_id}

Deletes it with its connections. Its past deliveries stay with their events until retention removes them.

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
destination_id required	path	string	dst_ ID

Responses

Status	Description	Body
204	Deleted
401	No API key, or it is invalid or revoked	Problem
404	No such destination, or no access	Problem
429	Over the key's rate limit; Retry-After says when to try again	Problem

Get destination

GET /api/v1/projects/{project_id}/environments/{environment_id}/destinations/{destination_id}

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
destination_id required	path	string	dst_ ID

Responses

Status	Description	Body
200	The destination	Destination
401	No API key, or it is invalid or revoked	Problem
404	No such destination, or no access	Problem
429	Over the key's rate limit; Retry-After says when to try again	Problem

Update destination

PATCH /api/v1/projects/{project_id}/environments/{environment_id}/destinations/{destination_id}

Rename, move, pause and resume it, or change its settings.

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
destination_id required	path	string	dst_ ID

Request body

JSON, UpdateDestination.

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

Responses

Status	Description	Body
200	Updated	Destination
401	No API key, or it is invalid or revoked	Problem
404	No such destination, or no access	Problem
422	Invalid name, URL or settings, or an http:// URL for a destination with a credential	Problem
429	Over the key's rate limit; Retry-After says when to try again	Problem

Check destination

POST /api/v1/projects/{project_id}/environments/{environment_id}/destinations/{destination_id}/check

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
destination_id required	path	string	dst_ ID

Request body

JSON, CheckDestination.

Field	Type	Description
method	CheckRequest

Responses

Status	Description	Body
200	How far the request got, step by step	DestinationCheck
401	No API key, or it is invalid or revoked	Problem
404	No such destination, or no access	Problem
422	Not an HTTP destination	Problem
429	Over the key's rate limit; Retry-After says when to try again	Problem
503	The gateway is not answering	Problem

Get destination circuit

GET /api/v1/projects/{project_id}/environments/{environment_id}/destinations/{destination_id}/circuit

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
destination_id required	path	string	dst_ ID

Responses

Status	Description	Body
200	The circuit; closed for a destination not delivered to lately	Circuit
401	No API key, or it is invalid or revoked	Problem
404	No such destination, or no access	Problem
429	Over the key's rate limit; Retry-After says when to try again	Problem
503	The gateway is not answering	Problem

Delete destination credential

DELETE /api/v1/projects/{project_id}/environments/{environment_id}/destinations/{destination_id}/credential

Deliveries go without it from now on.

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
destination_id required	path	string	dst_ ID

Responses

Status	Description	Body
204	Deleted
401	No API key, or it is invalid or revoked	Problem
404	No such credential, or no access	Problem
429	Over the key's rate limit; Retry-After says when to try again	Problem

Set destination credential

PUT /api/v1/projects/{project_id}/environments/{environment_id}/destinations/{destination_id}/credential

Sets the credential sent with every delivery, replacing any it had.

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
destination_id required	path	string	dst_ ID

Request body

JSON, SetCredential.

Responses

Status	Description	Body
200	Stored; its secret is not returned	DestinationCredential
401	No API key, or it is invalid or revoked	Problem
404	No such destination, or no access	Problem
422	Invalid credential, or the destination is not https://	Problem
429	Over the key's rate limit; Retry-After says when to try again	Problem
503	The API has no MASTER_KEYS to seal it with	Problem

Get destination health

GET /api/v1/projects/{project_id}/environments/{environment_id}/destinations/{destination_id}/health

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
destination_id required	path	string	dst_ ID
after	query	string (date-time)	From this time (attempts started at or after), default a day before before.
before	query	string (date-time)	Up to this time, default now. At most 31 days after after.

Responses

Status	Description	Body
200	Its failures in the range, and its last success and failure	DestinationHealth
401	No API key, or it is invalid or revoked	Problem
404	No such destination, or no access	Problem
422	Invalid range	Problem
429	Over the key's rate limit; Retry-After says when to try again	Problem

Get destination listeners

GET /api/v1/projects/{project_id}/environments/{environment_id}/destinations/{destination_id}/listeners

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
destination_id required	path	string	dst_ ID

Responses

Status	Description	Body
200	How many ricochet listen sessions are connected	Listeners
401	No API key, or it is invalid or revoked	Problem
404	No such destination, or no access	Problem
429	Over the key's rate limit; Retry-After says when to try again	Problem
503	The gateway is not answering	Problem

List destination secrets

GET /api/v1/projects/{project_id}/environments/{environment_id}/destinations/{destination_id}/secrets

Newest first, expired ones too.

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
destination_id required	path	string	dst_ ID

Responses

Status	Description	Body
200	Newest first, without their values	SigningSecret[]
401	No API key, or it is invalid or revoked	Problem
404	No such destination, or no access	Problem
429	Over the key's rate limit; Retry-After says when to try again	Problem

Rotate destination secret

POST /api/v1/projects/{project_id}/environments/{environment_id}/destinations/{destination_id}/secrets

Makes the next secret and shows it once. The one before keeps signing for overlap_seconds; older ones stop now.

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
destination_id required	path	string	dst_ ID

Request body

JSON, 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.

Responses

Status	Description	Body
201	Made; its value is shown only now	NewSigningSecret
401	No API key, or it is invalid or revoked	Problem
404	No such destination, or no access	Problem
422	Invalid overlap	Problem
429	Over the key's rate limit; Retry-After says when to try again	Problem
503	The API has no MASTER_KEYS to seal it with	Problem

Delete destination secret

DELETE /api/v1/projects/{project_id}/environments/{environment_id}/destinations/{destination_id}/secrets/{secret_id}

It stops signing now, e.g. to end an overlap early. Without any secret, deliveries go out unsigned.

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
destination_id required	path	string	dst_ ID
secret_id required	path	string	sec_ ID

Responses

Status	Description	Body
204	Deleted
401	No API key, or it is invalid or revoked	Problem
404	No such secret, or no access	Problem
429	Over the key's rate limit; Retry-After says when to try again	Problem

Stop failure simulation

DELETE /api/v1/projects/{project_id}/environments/{environment_id}/destinations/{destination_id}/simulation

The next deliveries reach the destination again.

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
destination_id required	path	string	dst_ ID

Responses

Status	Description	Body
204	Stopped (or there was none)
401	No API key, or it is invalid or revoked	Problem
403	A production environment	Problem
404	No such destination, or no access	Problem
429	Over the key's rate limit; Retry-After says when to try again	Problem
503	The gateway is not answering	Problem

Get failure simulation

GET /api/v1/projects/{project_id}/environments/{environment_id}/destinations/{destination_id}/simulation

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
destination_id required	path	string	dst_ ID

Responses

Status	Description	Body
200	The simulation in progress, if any	SimulationState
401	No API key, or it is invalid or revoked	Problem
403	A production environment	Problem
404	No such destination, or no access	Problem
422	Not an HTTP destination	Problem
429	Over the key's rate limit; Retry-After says when to try again	Problem
503	The gateway is not answering	Problem

Simulate failures

PUT /api/v1/projects/{project_id}/environments/{environment_id}/destinations/{destination_id}/simulation

The next count deliveries fail without reaching the destination. Replaces any earlier one.

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
destination_id required	path	string	dst_ ID

Request body

JSON, 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.

Responses

Status	Description	Body
200	Set: each simulated attempt is recorded with simulated in its error	SimulationState
401	No API key, or it is invalid or revoked	Problem
403	A production environment	Problem
404	No such destination, or no access	Problem
422	An invalid status or count, or not an HTTP destination	Problem
429	Over the key's rate limit; Retry-After says when to try again	Problem
503	The gateway is not answering	Problem

List held deliveries

GET /api/v1/projects/{project_id}/environments/{environment_id}/held-deliveries

Deliveries a paused destination or connection holds, counted by destination and connection.

Parameters

Name	In	Type	Description
project_id required	path	string	prj_ ID
environment_id required	path	string	env_ ID
destination_id	query	string	Only this destination's (dst_ ID).

Responses

Status	Description	Body
200	The held deliveries, oldest first	HeldDeliveriesList
401	No API key, or it is invalid or revoked	Problem
404	No such environment, or no access	Problem
429	Over the key's rate limit; Retry-After says when to try again	Problem
503	The gateway is not answering	Problem