instance

Add a connection entry, verified by one authenticated fetch.

Changed on

URL AND PIN ARE IMMUTABLE once stored, so there is no edit verb anywhere: re-pointing a stored credential at a different host is the credential-redirect attack, and re-pointing is remove + add, which re-runs the full ceremony including the human fingerprint confirmation.

The caller must already have displayed the SPKI fingerprint and taken the human's confirmation — that is interactive and belongs to the client. This endpoint performs the authenticated directory fetch, which returns the remote's instance identity: self-connection (409) and duplicate-identity (409) fire there, BEFORE the entry is committed. A fetch that does not succeed commits nothing (422).

The credential is write-only after storage: sealed under the instance keyring, never re-displayable through any surface, and leaving the process only inside TLS to the pinned remote.

post/api/v1/instance/remotes

Request

  • Base URL: / (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /api/v1/instance/remotes
  • Auth: HTTP bearer

Request body

namestring required

A display name for an organisation, project or environment. Identity is the immutable id, so this is a label and a rename never breaks a reference. The 128-byte bound is the one the organisation contract has carried since the first slice, adopted for every entity so there is one number rather than four; no ADR fixes a per-entity name length. The grammar itself (non-empty, no control characters, no surrounding whitespace) is enforced in the domain rather than restated as a pattern here — two grammars would be two things to keep in sync.

The bound is 128 UTF-8 BYTES, and the server is authoritative. maxLength below counts Unicode code points, which is the only length JSON Schema can express, so a name of 100 emoji satisfies this schema and is still refused by the server with bad_request. Clients that want to pre-validate must measure the UTF-8 encoding, not the string length.

urlstring required

A canonical https:// origin — no userinfo, no path, no query, no fragment, no plaintext HTTP. A value carrying one is REFUSED, never silently normalised.

spki_pinstring required

The fingerprint the human confirmed interactively.

credentialstring required

The connection credential minted on the serving side. Verified by one authenticated fetch before the entry is committed, then sealed under the instance keyring and never returned again.

Response

The entry, with the listing its verifying fetch returned.

idstring required

A prefixed UUIDv7, e.g. org_0198….

namestring required

A display name for an organisation, project or environment. Identity is the immutable id, so this is a label and a rename never breaks a reference. The 128-byte bound is the one the organisation contract has carried since the first slice, adopted for every entity so there is one number rather than four; no ADR fixes a per-entity name length. The grammar itself (non-empty, no control characters, no surrounding whitespace) is enforced in the domain rather than restated as a pattern here — two grammars would be two things to keep in sync.

The bound is 128 UTF-8 BYTES, and the server is authoritative. maxLength below counts Unicode code points, which is the only length JSON Schema can express, so a name of 100 emoji satisfies this schema and is still refused by the server with bad_request. Clients that want to pre-validate must measure the UTF-8 encoding, not the string length.

urlstring required

The canonical https origin. Immutable for the life of the entry.

spki_pinstring required

base64(sha256(SubjectPublicKeyInfo)), confirmed by a human at add time and verified on every connection before any bytes are written. Immutable for the life of the entry.

created_atstring date-time required

RFC 3339 UTC, microsecond precision.

created_bystring required
state'ok' | 'unreachable' | 'credential-rejected' | 'pin-mismatch' | 'redirect-refused' | 'identity-conflict' | 'self-connected' required

The most recent fetch's outcome. A closed enum because the operator's fix differs per outcome, and collapsing them into one "error" is what makes a directory card useless.

last_attempt_atstring date-time required

RFC 3339 UTC, microsecond precision.

observed_atstring date-time

RFC 3339 UTC, microsecond precision.

staleboolean required

The listing below is a SNAPSHOT, not current. Computed from the outcome rather than the age: a fetch that just failed makes even a one-second-old snapshot stale.

stale_for_secondsinteger

The snapshot's age, the number the card prints beside "unreachable".

identitystring
versionstring
org_countinteger
project_countinteger

Changes

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • warning

      added the new payload_too_large enum value to the / response property for the response status

    • warning

      added the new payload_too_large enum value to the / response property for the response status

    • warning

      added the new payload_too_large enum value to the / response property for the response status

    • warning

      added the new payload_too_large enum value to the / response property for the response status

    • warning

      added the new payload_too_large enum value to the / response property for the response status

    • warning

      added the new payload_too_large enum value to the / response property for the response status

    • warning

      added the new payload_too_large enum value to the / response property for the response status

    • warning

      added the new payload_too_large enum value to the / response property for the response status

    • warning

      added the new unprocessable enum value to the / response property for the response status

    • warning

      added the new unprocessable enum value to the / response property for the response status

    • warning

      added the new unprocessable enum value to the / response property for the response status

    • warning

      added the new unprocessable enum value to the / response property for the response status

    • warning

      added the new unprocessable enum value to the / response property for the response status

    • warning

      added the new unprocessable enum value to the / response property for the response status

    • warning

      added the new unprocessable enum value to the / response property for the response status

    • warning

      added the new unprocessable enum value to the / response property for the response status