CloudKey — API Reference

Authentication & Rate Limits

All document API endpoints require a single request header for authentication. Pass the secret key that was generated when your organization was provisioned.

Rate Limiting: Requests are limited to 100 requests per 15 minutes per IP address.

Required Header

Include this header on every request to the Documents API.

Header	Type	Description
x-secret-key	string	Your organization's secret access key REQUIRED

Providers

CloudKey supports two storage backends. Set the x-provider header on every request to select the one relevant to your organization.

minio — Self-hosted MinIO aws-s3 — Amazon S3

Value	Endpoint Used	Notes
minio	MINIO_ENDPOINT (.env)	Uses path-style routing. Default: `http://localhost:9000`
aws-s3	Standard AWS S3	Uses AWS region from `AWS_REGION` env variable

Folder Structure

CloudKey automatically enforces a consistent folder layout for all uploads. If your key does not already start with your orgname, it is rewritten automatically.

Passing key = report.pdf with x-orgname: acme-corp will automatically store the file at acme-corp/documents/2026-08/report.pdf.

{bucket}/acme-corp/documents/2026-08/report.pdf │ │ │ │ └─ Original filename │ │ │ └─────────── YYYY-MM auto folder │ │ └───────────────────────── Resource type │ └─────────────────────────────────── Your org prefix (x-orgname) └───────────────────────────────────────────── Your bucket

POST

Upload Document

POST /api/documents/upload

Upload a file to your organization's storage bucket. The request must be sent as multipart/form-data. The folder path is enforced automatically based on your org name and the current date.

Request Body — multipart/form-data

Field	Type	Description
folder_name	string	Target subfolder (e.g., `invoices`, `reports`) REQUIRED
file	file	Binary file content to upload REQUIRED

Code Example

curl -X POST http://localhost:3001/api/documents/upload \ -H "x-secret-key: YOUR_SECRET_KEY" \ -F "folder_name=reports" \ -F "file=@/path/to/report.pdf"

200 — Success Response

{ "success": true, "message": "File uploaded successfully", "key": "acme-corp/documents/2026-08/report.pdf" }

GET

View / Download Document

GET /api/documents/view?bucket=&key=

Returns a temporary presigned URL for the specified document. This URL allows any HTTP client or browser to securely access the file for up to 1 hour without additional credentials.

Query Parameters

Parameter	Type	Description
key	string	Full path to the file (e.g. `acme-corp/documents/2026-08/reports/report.pdf`) REQUIRED

Code Example

curl -G http://localhost:3001/api/documents/view \ -H "x-secret-key: YOUR_SECRET_KEY" \ --data-urlencode "key=acme-corp/documents/2026-08/reports/report.pdf"

200 — Success Response

{ "success": true, "url": "http://localhost:9000/my-bucket/acme-corp/documents/2026-08/report.pdf?X-Amz-Algorithm=..." }

DELETE

Delete Document

DELETE /api/documents/delete

Permanently removes a document from the storage bucket. This operation is irreversible. Ensure you have the correct key before proceeding.

Request Body — application/json

Field	Type	Description
key	string	Full path to the file to delete REQUIRED

Code Example

curl -X DELETE http://localhost:3001/api/documents/delete \ -H "Content-Type: application/json" \ -H "x-secret-key: YOUR_SECRET_KEY" \ -d '{"key":"acme-corp/documents/2026-08/reports/report.pdf"}'

200 — Success Response

{ "success": true, "message": "File deleted successfully" }

Error Codes

All error responses follow a consistent JSON format with a success: false flag and a descriptive message.

HTTP Code	Meaning	Common Cause
400	Bad Request	Missing required field (folder_name, key, or file)
401	Unauthorized	Missing x-secret-key header
403	Forbidden	Invalid secret key
429	Too Many Requests	Rate limit exceeded (100 reqs / 15 mins)
500	Internal Server Error	Storage service unreachable or misconfigured .env

Error Response Shape

{ "success": false, "message": "Missing x-access-key or x-secret-key in headers." }