zpe-paste · zpe API

GET /_/api/v1/me GET /_/api/v1/me getPasteMe no account

GET /_/api/v1/me

Parameters

No parameters.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	Who is asking, as the door sees them. A stranger is a 200 with `signedIn: false` and a sign-in URL, not a 401: the question has an answer whoever asks it.	object
`500`	This app failed while answering	object
`503`	The door (auth.zpe.vc) did not answer, so whether this visitor is signed in could not be checked. Retry once the door is back; nothing about the visitor is implied by this answer.	object

Example

GET /_/api/v1/me.

GET /_/api/v1/me

curl -X GET 'https://zpe.vc/paste/_/api/v1/me'

200 application/json

{
  "signedIn": false,
  "accountId": null,
  "rung": 0,
  "email": null,
  "tenant": null,
  "signin": null
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

POST /_/api/v1/paste POST /_/api/v1/paste postPaste

POST /_/api/v1/paste

Parameters

No parameters.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`201`	The paste was written. The id is the capability the link carries; the deletion token is answered once and never again.	object
`400`	The request could not be read	object
`401`	The credential is missing or does not open this account	object
`403`	This account may not do that	object
`404`	Nothing is here	object
`413`	The body is larger than this deployment accepts (`MAX_BODY_BYTES`, 4 MiB by default).	object
`415`	The body is not `application/json`, and this path reads nothing else.	object
`429`	Too many requests	object

Example

POST /_/api/v1/paste, with a token from the door.

POST /_/api/v1/paste

curl -X POST 'https://zpe.vc/paste/_/api/v1/paste' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

201 application/json

{
  "id": "string",
  "deletetoken": "string"
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

POST /_/api/v1/guest/paste POST /_/api/v1/guest/paste createGuestPaste no account

POST /_/api/v1/guest/paste

Parameters

No parameters.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`201`	The paste was written for a reserved guest principal. Nothing lists it and nothing signs in to it: the delete token is the only handle on the row.	object
`400`	A lifetime longer than this path allows, which is 24 hours.	object
`401`	The credential is missing or does not open this account	object
`403`	This deployment does not take pastes from strangers: the operation exists and is not open here.	object
`404`	Nothing is here	object
`413`	The body is larger than this deployment accepts.	object
`415`	The body is not `application/json`.	object
`429`	More pastes than this address may make in a minute. Signing in lifts the limit, because an account is an identity and an address is not.	object

Example

POST /_/api/v1/guest/paste.

POST /_/api/v1/guest/paste

curl -X POST 'https://zpe.vc/paste/_/api/v1/guest/paste'

201 application/json

{
  "id": "string",
  "deletetoken": "string"
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

GET /_/api/v1/pastes GET /_/api/v1/pastes getPastes

GET /_/api/v1/pastes

Parameters

No parameters.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	The pastes filed under the caller's account, newest first, each with the state it is in.	object
`401`	No credential was presented, or the one presented does not open this account. Sign in at the door, or mint a key for it.	object
`403`	The credential is real and may not read this app: a key not granted it, or a session the door could not map to an account.	object
`429`	The key has spent its request ceiling. `retry-after` says when to try again; signing in raises the ceiling, because an account is an identity and a clock is not.	object
`500`	This app failed while answering	object
`503`	The door (auth.zpe.vc) did not answer, so the credential could not be checked. Retry once the door is back: a 503 withholds the verdict rather than refusing the caller.	object

Example

GET /_/api/v1/pastes, with a token from the door.

GET /_/api/v1/pastes

curl -X GET 'https://zpe.vc/paste/_/api/v1/pastes' \
  -H 'Authorization: Bearer $ZPE_TOKEN'

200 application/json

{
  "pastes": [
    {
      "id": "string",
      "burn": false,
      "created": 0,
      "expires": null,
      "consumedAt": null,
      "state": "live"
    }
  ]
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

GET /_/api/v1/paste/{id} GET /_/api/v1/paste/:id getPasteById no account

GET /_/api/v1/paste/:id

Parameters

name	in	required	type	notes
`id`	path	yes	string	The paste's id · the capability the link carries.
`meta`	query	no	"1"	Answer only the paste's head (its metadata), never the ciphertext · what a preview does with an id it merely learned.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	The paste in the format its client wrote · or only its head when it is one-time, because an ambient GET (a prefetch, a link scanner) must not spend a paste it merely learned the id of.	object
`400`	The request could not be read	object
`401`	The credential is missing or does not open this account	object
`403`	This account may not do that	object
`404`	Nothing is here	object
`410`	A one-time paste whose id has already been read, or that has expired: the id is the capability, and it is spent. Nothing else will ever answer at this address.	object
`429`	Too many requests	object

Example

GET /_/api/v1/paste/:id.

GET /_/api/v1/paste/{id}

curl -X GET 'https://zpe.vc/paste/_/api/v1/paste/string?meta=1'

200 application/json

{
  "v": 0,
  "ct": "string",
  "wk": "string",
  "adata": {},
  "meta": {
    "expire": "string",
    "created": 0
  }
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

DELETE /_/api/v1/paste/{id} DELETE /_/api/v1/paste/:id deletePasteById no account

DELETE /_/api/v1/paste/:id

Parameters

name	in	required	type	notes
`id`	path	yes	string	The paste's id.
`X-Delete-Token`	header	no	string	The deletion token the create answered. Absent, the owner's own session is what allows the delete, and another account's row is refused.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	The row is gone. The deletion token or the owner's session allowed it, and the answer names what it removed.	object
`400`	Neither `X-Delete-Token` nor a signed-in session was presented, so there is nothing that could authorise the delete.	object
`403`	The delete token does not match this row (`wrong-delete-token`), or the row belongs to another account. The paste was not deleted.	object
`404`	That id is not a paste this app has: never issued, already deleted, or expired.	object
`500`	This app failed while answering	object
`503`	The door (auth.zpe.vc) did not answer, so the owner's session could not be read. Retry once the door is back; the row is untouched.	object

Example

DELETE /_/api/v1/paste/:id.

DELETE /_/api/v1/paste/{id}

curl -X DELETE 'https://zpe.vc/paste/_/api/v1/paste/string'

200 application/json

{
  "status": "deleted",
  "id": "string"
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

POST /_/api/v1/paste/{id}/consume POST /_/api/v1/paste/:id/consume postPasteByIdConsume no account

POST /_/api/v1/paste/:id/consume

Parameters

name	in	required	type	notes
`id`	path	yes	string	The one-time paste's id.
`X-Burn-Intent`	header	yes	"consume"	Must be `consume`. Required so a cross-site page cannot burn a paste by linking to it · the answer to a request without it is `400 bad-request`.

Request body

None: this operation takes its arguments in the path and the query.

Responses

status	meaning	body
`200`	The ciphertext, to the one caller whose statement won the row. `X-Burn-Intent: consume` is required, so a cross-site page cannot burn a paste by linking to it.	object
`400`	The request could not be read	object
`401`	The credential is missing or does not open this account	object
`403`	This account may not do that	object
`404`	Nothing is here	object
`410`	Someone else consumed it first, or it has expired. The row is gone and no second read exists.	object
`429`	Too many requests	object

Example

POST /_/api/v1/paste/:id/consume.

POST /_/api/v1/paste/{id}/consume

curl -X POST 'https://zpe.vc/paste/_/api/v1/paste/string/consume'

200 application/json

{
  "v": 0,
  "ct": "string",
  "wk": "string",
  "adata": {},
  "meta": {
    "expire": "string",
    "created": 0
  }
}

The example is generated from the schema in the contract: the shape is the document's, the values are placeholders.

Matches in other apps

zpe-paste API

Parameters

Request body

Responses

Example

Parameters

Request body

Responses

Example

Parameters

Request body

Responses

Example

Parameters

Request body

Responses

Example

Parameters

Request body

Responses

Example

Parameters

Request body

Responses

Example

Parameters

Request body

Responses

Example