SnapPwd API reference

Base URL

The examples below use a local instance. The self-hosting guide shows how to start one with Docker Compose. The hosted instance is the one behind snappwd.io and the default for the SnapPwd CLI. It accepted writes without a token when we checked on October 12, 2026, and it serves the same /openapi.yaml as the repository. This page makes no promise about its rate limits or availability. If an integration matters to you, run your own instance.

The API stores ciphertext only

The API does not encrypt anything. It stores the string you send in encryptedSecret or encryptedData as it is, and returns it once. If you send plaintext, plaintext is what gets stored. Encrypting, and keeping the key away from the server, is the client's job. The security architecture page explains the model.

The SnapPwd CLI is the reference client. Its crypto.ts does the following, and links it creates against the hosted API open in the hosted web app:

• Generate 32 random bytes as an AES-256-GCM key, and a random 12-byte initialization vector for each payload.
• For a secret, send encryptedSecret as the base64 encoding of one version byte (0x02), then the initialization vector, then the ciphertext with its authentication tag.
• For a file, send the initialization vector as base64 in metadata.iv and the ciphertext as base64 in encryptedData.
• Put the key, base58 encoded, in the URL fragment of the share link: /g/<id>#<key>. The fragment is never part of an API request.

The API does not check this format. A client that only talks to itself can use any scheme. The self-hosted web client uses a different one, described under known limitations.

Conventions

• Request and response bodies are JSON. POST requests must send Content-Type: application/json.
• Secret IDs start with sps- and file IDs start with spf-. Treat the rest as opaque. An ID with the wrong prefix returns 404.
• expiration is a lifetime in seconds, from 60 (1 minute) to 2592000 (30 days). There is no default: it is required.
• Retrieval is one-time. A GET without peek returns the payload and deletes it in the same step, so two simultaneous requests cannot both succeed.
• ?peek=true returns the creation time, the seconds left and the metadata, without the payload and without deleting anything. It needs only the ID, not the key.
• Errors raised by the service's own checks have the shape {"error": "..."}. Requests rejected before they reach those checks may return a plain-text message instead: malformed JSON or an invalid query parameter (400), an oversized body (413), a missing JSON content type (415) and a wrong or missing field (422). Do not assume an error body is JSON; check the status code first.
• Reads need no authentication. Writes need Authorization: Bearer <token> only when the instance sets WRITE_API_TOKEN.

POST /v1/secrets

Store an encrypted secret. Returns its ID.

Response 200:

{"secretId":"sps-JfMLhNZ939fMhYWmE37twN"}

GET /v1/secrets/{id}

Retrieve a secret and delete it. Add ?peek=true to read its status instead.

Both forms return 404 once the secret has been retrieved or has expired. When the sender asked for a notification, a successful retrieval emails them the caller's IP address and user agent. A peek never does.

POST /v1/files

Store an encrypted file. Returns its ID.

Response 200:

{"fileId":"spf-SzJyjzvbSXn6JLHkVRaUjY"}

GET /v1/files/{id}

Retrieve a file and delete it. Add ?peek=true to read its metadata instead.

The filename and content type come from whoever created the file. Treat them as untrusted input: escape them before display and do not use the filename as a path without checking it.

Status codes

Limits

Values are the service defaults. A hosted or third-party instance may be configured differently.

curl examples

These use a placeholder string where your ciphertext goes. The output shown is what a local instance returned. IDs and timestamps will differ for you.

Create, peek at and retrieve a secret

curl -s -X POST http://localhost:8080/v1/secrets \
  -H 'Content-Type: application/json' \
  -d '{"encryptedSecret":"AgECAwQFBgcICQoLDGNpcGhlcnRleHQ=","expiration":3600}'
# {"secretId":"sps-JfMLhNZ939fMhYWmE37twN"}

curl -s 'http://localhost:8080/v1/secrets/sps-JfMLhNZ939fMhYWmE37twN?peek=true'
# {"createdAt":1791828484,"ttlSeconds":3600}

curl -s http://localhost:8080/v1/secrets/sps-JfMLhNZ939fMhYWmE37twN
# {"encryptedSecret":"AgECAwQFBgcICQoLDGNpcGhlcnRleHQ="}

curl -s http://localhost:8080/v1/secrets/sps-JfMLhNZ939fMhYWmE37twN
# {"error":"Secret not found or already accessed"}   (HTTP 404)

Attach metadata

curl -s -X POST http://localhost:8080/v1/secrets \
  -H 'Content-Type: application/json' \
  -d '{"encryptedSecret":"AgECAwQFBgcICQoLDGNpcGhlcnRleHQ=","expiration":600,"metadata":{"label":"API key for staging","rotateBy":"2026-11-01"}}'
# {"secretId":"sps-JHuwxQUE3v9BtoqU2YEU4T"}

curl -s 'http://localhost:8080/v1/secrets/sps-JHuwxQUE3v9BtoqU2YEU4T?peek=true'
# {"createdAt":1791828484,"ttlSeconds":600,"metadata":{"label":"API key for staging","rotateBy":"2026-11-01"}}

Create, peek at and retrieve a file

curl -s -X POST http://localhost:8080/v1/files \
  -H 'Content-Type: application/json' \
  -d '{"metadata":{"originalFilename":"notes.txt","contentType":"text/plain","iv":"AQIDBAUGBwgJCgsM"},"encryptedData":"Y2lwaGVydGV4dA==","expiration":3600}'
# {"fileId":"spf-SzJyjzvbSXn6JLHkVRaUjY"}

curl -s 'http://localhost:8080/v1/files/spf-SzJyjzvbSXn6JLHkVRaUjY?peek=true'
# {"createdAt":1791828484,"ttlSeconds":3600,"metadata":{"originalFilename":"notes.txt","contentType":"text/plain","iv":"AQIDBAUGBwgJCgsM"}}

curl -s http://localhost:8080/v1/files/spf-SzJyjzvbSXn6JLHkVRaUjY
# {"metadata":{"originalFilename":"notes.txt","contentType":"text/plain","iv":"AQIDBAUGBwgJCgsM"},"encryptedData":"Y2lwaGVydGV4dA==","createdAt":1791828484}

Write to a token-protected instance

On an instance started with WRITE_API_TOKEN, a POST without the token returns 401 and {"error":"Valid write token required"}. Send the token as a bearer token. Retrieval still needs none.

curl -s -X POST http://localhost:8080/v1/secrets \
  -H 'Authorization: Bearer 0123456789abcdef0123456789abcdef' \
  -H 'Content-Type: application/json' \
  -d '{"encryptedSecret":"AgECAwQFBgcICQoLDGNpcGhlcnRleHQ=","expiration":3600}'
# {"secretId":"sps-GVBbHVW1rTeQBCtR5PBnQx"}

The token above is an example value. Generate your own random one and send it only over HTTPS.

What errors look like

# expiration below 60 seconds: HTTP 400
{"error":"Invalid expiration time"}

# senderEmail on an instance without SMTP: HTTP 503
{"error":"Email notifications are unavailable"}

# more than 10 writes within a minute: HTTP 429, with a retry-after header
{"error":"Write rate limit exceeded"}

# a metadata field that is not allowed: HTTP 422, plain text
Failed to deserialize the JSON body into the target type: metadata: metadata contains unknown field `owner` at line 1 column 68

OpenAPI specification

The machine-readable definition is openapi.yaml in the service repository. Every running instance also serves it at GET /openapi.yaml. The explorer below is generated from the same file.