API Reference

Choosing the Right Endpoint

Not sure which endpoint to use? See How It Works for guidance on when to use /public (no encryption) vs /private (automatic encryption). You can also remove stored resources with the DELETE endpoint.

Authentication

All operations require an API key passed via the X-API-Key header. The API key is configured by the service operator through the API_KEY environment variable.

X-API-Key: your-secure-api-key-here

Store Public Data

• Endpoint: POST /api/3.0.0/public
• Authentication: Required (X-API-Key header)
• Content Types: application/json or multipart/form-data

Stores data or files without encryption. Returns a URI where the content can be accessed and a hash for integrity verification.

JSON Upload

curl -X POST http://localhost:3333/api/3.0.0/public \
-H "Content-Type: application/json" \
-H "X-API-Key: your-secure-api-key-here" \
-d '{
  "bucket": "documents",
  "data": {
    "field1": "value1"
  }
}'

Example response:

{
    "uri": "http://localhost:3333/api/3.0.0/documents/2ad789c7-e513-4523-a826-ab59e1c423cd.json",
    "hash": "d6bb7b579925baa4fe1cec41152b6577003e6a9fde6850321e36ad4ac9b3f30a"
}

Binary File Upload

curl -X POST http://localhost:3333/api/3.0.0/public \
-H "X-API-Key: your-secure-api-key-here" \
-F "file=@/path/to/image.png" \
-F "bucket=files"

Example response:

{
    "uri": "http://localhost:3333/api/3.0.0/files/123e4567-e89b-12d3-a456-426614174000.png",
    "hash": "d6bb7b579925baa4fe1cec41152b6577003e6a9fde6850321e36ad4ac9b3f30a"
}

Request Payload (JSON)

Field	Description	Required
bucket	Name of the bucket where the data will be stored. Falls back to the DEFAULT_BUCKET environment variable if omitted.	No
data	The actual data to be stored, must be in JSON format.	Yes
id	Optional UUID for the document. If not provided, one will be generated.	No

Request Payload (Binary)

Field	Description	Required
file	The binary file to upload.	Yes
bucket	Name of the bucket where the file will be stored. Falls back to the DEFAULT_BUCKET environment variable if omitted.	No
id	Optional UUID for the file. If not provided, one will be generated.	No

Response Data

Field	Description
uri	The link to the stored data.
hash	A hash of the data, used to verify your data has not been changed.

---

Store Private Data

• Endpoint: POST /api/3.0.0/private
• Authentication: Required (X-API-Key header)
• Content Types: application/json or multipart/form-data

Automatically encrypts and stores data or files. Returns a URI, a hash, and a decryption key. The decryption key is returned only once -- store it securely.

JSON Upload

curl -X POST http://localhost:3333/api/3.0.0/private \
-H "Content-Type: application/json" \
-H "X-API-Key: your-secure-api-key-here" \
-d '{
  "bucket": "documents",
  "data": {
    "field1": "value1"
  }
}'

Example response:

{
    "uri": "http://localhost:3333/api/3.0.0/documents/e8b32169-582c-421a-a03f-5d1a7ac62d51.json",
    "hash": "d6bb7b579925baa4fe1cec41152b6577003e6a9fde6850321e36ad4ac9b3f30a",
    "decryptionKey": "f3bee3dc18343aaab66d28fd70a03015d2ddbd5fd3b9ad38fff332c09014598d"
}

Binary File Upload

curl -X POST http://localhost:3333/api/3.0.0/private \
-H "X-API-Key: your-secure-api-key-here" \
-F "file=@/path/to/image.png" \
-F "bucket=files"

Example response:

{
    "uri": "http://localhost:3333/api/3.0.0/files/123e4567-e89b-12d3-a456-426614174000.json",
    "hash": "d6bb7b579925baa4fe1cec41152b6577003e6a9fde6850321e36ad4ac9b3f30a",
    "decryptionKey": "a1bc2de3f4567890abcdef1234567890abcdef1234567890abcdef1234567890"
}

Request Payload (JSON)

Field	Description	Required
bucket	Name of the bucket where the data will be stored. Falls back to the DEFAULT_BUCKET environment variable if omitted.	No
data	The actual data to be stored, must be in JSON format.	Yes
id	Optional UUID for the document. If not provided, one will be generated.	No

Request Payload (Binary)

Field	Description	Required
file	The binary file to upload.	Yes
bucket	Name of the bucket where the file will be stored. Falls back to the DEFAULT_BUCKET environment variable if omitted.	No
id	Optional UUID for the file. If not provided, one will be generated.	No

Response Data

Field	Description
uri	The link to the stored data.
hash	A hash of the data, used to verify your data has not been changed.
decryptionKey	The key required to decrypt the stored data.

---

Delete a Resource

• Endpoint: DELETE /api/3.0.0/:bucket/:id
• Authentication: Required (X-API-Key header)

Deletes a previously stored resource (public or encrypted) by bucket and ID. Uses prefix matching to locate the resource regardless of file extension. If multiple objects share the same ID prefix, all are deleted.

curl -X DELETE http://localhost:3333/api/3.0.0/documents/2ad789c7-e513-4523-a826-ab59e1c423cd \
-H "X-API-Key: your-secure-api-key-here"

Path Parameters

Parameter	Description	Required
bucket	Name of the bucket. Must be a configured bucket.	Yes
id	UUID of the resource to delete.	Yes

Response

A successful deletion returns 204 No Content with no response body.

Error Responses

Status Code	Description
400	Bad request -- invalid bucket or missing ID.
401	Unauthorised -- missing or invalid API key.
404	Not found -- no resource matches the given ID.
500	Internal server error.

---

Full API Documentation

Full API documentation including request/response schemas and error responses is available at {your-deployment-url}/api-docs from any running instance.

For local development: http://localhost:3333/api-docs.