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 |