Retry an endpoint's gated connections

POST

/endpoints/{endpoint}:retry

const url = 'https://example.com/api/v1/endpoints/boi.17c.415a.%24comp.display-1%2Fhttps:retry';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"certificate":"example","host_key":"example"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://example.com/api/v1/endpoints/boi.17c.415a.%24comp.display-1%2Fhttps:retry \
  --header 'Content-Type: application/json' \
  --data '{ "certificate": "example", "host_key": "example" }'

Moves the endpoint’s retry counter, which is part of its connection fingerprint: a gate a refusal retrying cannot fix holds (a wrong credential, a changed host key or certificate, a reply its driver declares terminal) lifts, the node recycles the endpoint’s held session, and every connection to it is attempted again. Fixing the secret, the address, the transport, the tls mode or the driver’s login needs no retry: the change moves the fingerprint itself. An unrelated edit (a label) moves nothing. host_key names a key to trust, the one the endpoint’s transport pins (the offered key a key refusal names): an ssh host key, or a tls or https endpoint’s certificate public key, which such an endpoint also takes as certificate. It becomes the declared pin and recycles the session onto it whatever its state, an audited acceptance of the change. While the endpoint’s gate names an offered key, the key must be that key, so a trust confirmed against a refusal the record has since moved past is a 409 and changes nothing. Audited, a trusted key with the pin it replaced (old) and the pin it set (new). Gated by endpoint:retry; read and retry scopes (through the component) drive the 404 versus 403 split.

Parameters

Path Parameters

endpoint

required

The endpoint, as / (the component by name, dotted address or uuid) or by its uuid. The slash is percent-encoded in a URL, as the CLI does

string

The endpoint, as / (the component by name, dotted address or uuid) or by its uuid. The slash is percent-encoded in a URL, as the CLI does

Request Body

application/json

object

$schema

A URL to the JSON Schema for this object.

string format: uri

certificate

A tls or https endpoint only: the same as host_key, named for the certificate (the offered_key a certificate refusal names). It becomes the endpoint’s declared tls-certificate pin, held to the same rule (the exact offered key while a key refusal holds), and the session redials onto it. Omit to retry with the pin unchanged

string

host_key

The SHA256 fingerprint of a changed key the operator now trusts, the key the endpoint’s transport pins (the offered_key a key refusal names on the component’s reachability read): an ssh endpoint’s host key, which becomes its declared ssh-host-key, or a tls or https endpoint’s certificate public key, which becomes its declared tls-certificate. The session redials onto it. While a key refusal holds, it must be that exact offered key: any other is a 409 that changes nothing (the refusal on record is the node’s last word, so to trust a key the component presents since, retry without a key first). With no key refusal held it declares a pin ahead of time. Omit to retry with the pin unchanged

string

Responses

200

application/json

object

$schema

A URL to the JSON Schema for this object.

string format: uri

component

The owning component name; absent for a server-hosted endpoint

string

component_id

The owning component’s id; the stable form of component

string

driver

The driver this endpoint was attached through (#813); absent for a bare probe endpoint

string

driver_id

The attached driver’s id; the stable form of driver

string

required

The endpoint’s uuid, the stable handle; / is the address an operator types

string

inputs

The effective inputs supplied at attach, defaults baked; secret inputs are reference names, never values

label

The friendly string an operator reads, and the only identity string an operator types here: the name is derived from the transport. Absent when unset, and a surface with none renders the name verbatim

string

name

required

The derived name (its transport), unique within the owning component

string

node

The node placement name, if assigned

string

node_id

The placed node’s id; the stable form of node

string

params

The address/target settings (jsonb)

transport

required

The transport name (the wire this endpoint speaks over), from the code registry

string

Example

{
  "$schema": "/api/v1/schemas/EndpointBody.json"
}

default

Error

application/problem+json

object

$schema

A URL to the JSON Schema for this object.

string format: uri

detail

A human-readable explanation specific to this occurrence of the problem.

string

errors

Optional list of individual error details

Array<object> | null

object

location

Where the error occurred, e.g. ‘body.items[3].tags’ or ‘path.thing-id’

string

message

Error message text

string

value

The value at the given location

instance

A URI reference that identifies the specific occurrence of the problem.

string format: uri

status

HTTP status code

integer format: int64

title

A short, human-readable summary of the problem type. This value should not change between occurrences of the error.

string

type

A URI reference to human-readable documentation for the error.

string format: uri

default: about:blank

Example

{
  "$schema": "/api/v1/schemas/ErrorModel.json",
  "detail": "Property foo is required but is missing.",
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}