API reference

Create a secret

Store an encrypted envelope and receive a reference, a private deletion token, and an expiry.

POST/secrets

Request#

envelope	Required object with version, iv, ciphertext.
expiresIn	3600, 86400, or 604800 seconds. Default: 86400.

Send JSON with Content-Type: application/json. Unknown fields, null expiry, and arbitrary durations are rejected. JavaScript uses Quickstart setup; cURL requires a real encrypted envelope.

JavaScript

// Run only when the sender chooses Create.
const { envelope, keyFragment } = await encryptText('A disposable demo note')
const createResponse = await fetch(`${api}/secrets`, {
  ...requestOptions,
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ envelope, expiresIn: 3600 }),
  signal: AbortSignal.timeout(15000),
})
if (createResponse.status !== 201) {
  throw new Error(`Creation failed (${createResponse.status})`)
}
const { id, deleteToken, expiresAt } = await createResponse.json()

cURL

# Save a real encrypted envelope from the helper as envelope.json.
# Its fields are version, iv and ciphertext. Never include the key.
node --input-type=module -e '
  import fs from "node:fs";
  const envelope = JSON.parse(fs.readFileSync("envelope.json", "utf8"));
  process.stdout.write(JSON.stringify({ envelope, expiresIn: 3600 }));
' | curl -i -X POST https://api.xasha.site/secrets \
  -H 'Content-Type: application/json' \
  --data-binary @-

Response#

201 Created. Example values below are placeholders, not valid credentials.

json

{
  "id": "<32-character base64url reference>",
  "deleteToken": "<43-character base64url token>",
  "expiresAt": "2026-10-08T12:00:00.000Z"
}

Errors and retries#

400 for invalid input; 413 for oversized payloads; 415 for unsupported content type; 429 for throttling; 500/503 for service failure.