Skip to content

Requests

Submitting data to a request by slug.

GET /api/public/requests/{slug}

Probe a request

Unauthenticated

Callable with no credential.

Describes what a request is asking for — its template, whether it needs a password, an identifier or a proven identity — plus the requester's identity claim so the responder can verify who is asking before answering.

Parameters

Name In Required Notes
slug path yes The capability. Unguessable by construction and never derived from anything user-visible — whoever holds it holds the access.

Responses

Status Meaning
200 The request's shape and the requester's claim.
404 No such resource, or the caller may not see it.
429 Too many attempts. Password gates, probes and challenges are limited per client, so a slug cannot be brute-forced.

Response fields

Field Type Notes
requestId string
slug string
label string
status string
requiresPassword boolean
requiresIdentifier boolean
requireHandshake boolean
allowExtraFields boolean
identity string The id of the identity the request is made under, or empty.
identityScope string (` \|any\|from_root`) Which identities the request will accept.
template object What the request asks for, grouped as its template groups it.
requester Sharer
server ServerClaim

POST /api/public/requests/{slug}

Submit a response

Auth: Session

Answers a request. Requires an account on this server: the answer is minted as a revocable link in the responder's own workspace, where they can update or withdraw it. An unauthenticated call is refused with request_account_required. Submitting again from the same account updates the existing response rather than creating a second one.

A responder whose account is on another server answers through that server instead (POST /api/requests/remote there), and the answer stays in their vault on it.

An identity is recorded only when a challenge signature verified. A claimed identityId without one is dropped, not attributed — otherwise anyone could submit under someone else's name.

If the request names a callback URL, a successful submission is POSTed onward to it.

Parameters

Name In Required Notes
slug path yes The capability. Unguessable by construction and never derived from anything user-visible — whoever holds it holds the access.

Request body

application/json

Field Type Notes
data object Answers keyed by template key.
mappings object Answers supplied as references to the responder's own vault records rather than as literal values, so the requester keeps resolving the current value. Same-server only.
senderName string
identifier string Required when the probe reported requiresIdentifier.
password string
identityId string
handshakeToken string
challengeNonce string
challengeSignature string

Responses

Status Meaning
200 The submission was recorded.
401 Refused, with a named reason.
404 No such resource, or the caller may not see it.
429 Too many attempts. Password gates, probes and challenges are limited per client, so a slug cannot be brute-forced.

POST /api/requests/remote

Answer a request on another server

Auth: Session

Answers a request published by another Revoked server for the person signed in here. The answers become entries in their vault on this server and a link they own, as for a request on this server; the other server receives the link's id and a token to read it with, and reads the values from here whenever it needs them. Revoking the link here revokes the answer there.

origin is the address the request was opened at. This server reads the request's probe there first, checks that the server at that address claims the domain the address belongs to, and checks the answer against the published template before writing anything. If the other server then refuses the answer, everything written for it is taken back and the refusal is passed on with its own code, so a wrong password there reads as request_password_invalid here.

For a request that requires a proven identity, the challenge comes from the other server (GET /api/challenges/request/{slug} there, with this server's identityId) and is signed on the device as usual. This server passes the identity's public material along; the other server checks it against this server's DNS-pinned root key and asks this server whether it still vouches for it.

Answering the same request again updates the same link and rotates its token.

Request body

application/json

Field Type Notes
origin string The other server's address, e.g. https://requests.example. Plain http is accepted only for a domain listed in PEER_OVERRIDES.
slug string
data object Answers keyed by template key.
mappings object Answers supplied as references to the responder's own vault entries.
senderName string
identifier string
password string
identityId string An identity of the signed-in person on this server.
challengeNonce string
challengeSignature string

Responses

Status Meaning
200 The other server accepted the answer.
400 Refused, with a named reason.
401 Refused, with a named reason.
403 Refused, with a named reason.
404 No such resource, or the caller may not see it.
429 Too many attempts. Password gates, probes and challenges are limited per client, so a slug cannot be brute-forced.
502 remote_unreachable when the other server could not be reached, remote_server_mismatch when it claims a different domain than its address, or the other server's own refusal when it failed.

Response fields

Field Type Notes
ok boolean
linkId string The responder's link on this server.
responseId string The answer's id on the other server.
server string The other server's domain.
completed boolean
updated boolean