paste.es/docs/api.md

API Documentation

Hemmelig provides a REST API for programmatic access to secret sharing functionality.

Interactive Documentation

The API is documented using OpenAPI 3.0 specification with an interactive Swagger UI:

• Swagger UI: /api/docs - Interactive API explorer
• OpenAPI Spec: /api/openapi.json - Raw OpenAPI specification

Authentication

Session Authentication

For browser-based access, authenticate through the /auth endpoints provided by better-auth. Session cookies are automatically managed.

API Key Authentication

For programmatic access, create an API key in your account settings under the Developer tab.

Use the API key as a Bearer token in the Authorization header:

curl -H "Authorization: Bearer hemmelig_your_api_key_here" \
  https://your-instance.com/api/secrets

Important:

• API keys are shown only once upon creation - store them securely
• Maximum 5 API keys per user
• Keys can optionally expire after 30, 90, or 365 days
• Revoke compromised keys immediately from your account settings

For endpoints requiring admin access, the authenticated user must have the admin role.

Quick Reference

Public Endpoints

Method	Endpoint	Description
GET	/api/healthz	Health check
POST	/api/secrets	Create a new secret
POST	/api/secrets/:id	Retrieve a secret (password in body if protected)
GET	/api/secrets/:id/check	Check if secret exists and requires password
POST	/api/files	Upload a file
GET	/api/files/:id	Download a file
GET	/api/instance/settings/public	Get public instance settings
GET	/api/setup/status	Check if initial setup is needed
POST	/api/setup/complete	Complete initial setup

Authenticated Endpoints

Method	Endpoint	Description
GET	/api/secrets	List user's secrets
DELETE	/api/secrets/:id	Delete a secret
GET	/api/account	Get account info
PUT	/api/account	Update account info
PUT	/api/account/password	Update password
DELETE	/api/account	Delete account
GET	/api/api-keys	List API keys
POST	/api/api-keys	Create API key
DELETE	/api/api-keys/:id	Delete API key

Admin Endpoints

Method	Endpoint	Description
GET	/api/instance/settings	Get all instance settings
PUT	/api/instance/settings	Update instance settings
GET	/api/analytics	Get secret analytics
GET	/api/analytics/visitors/daily	Get daily visitor stats
GET	/api/invites	List invite codes
POST	/api/invites	Create invite code
DELETE	/api/invites/:id	Deactivate invite code
PUT	/api/user/:id	Update user

Example: Create a Secret

curl -X POST https://your-instance.com/api/secrets \
  -H "Content-Type: application/json" \
  -d '{
    "secret": "BASE64_ENCRYPTED_CONTENT",
    "salt": "ENCRYPTION_SALT",
    "expiresAt": 3600,
    "views": 1
  }'

Response:

{
    "id": "abc123xyz"
}

Important Notes

• Client-side encryption: All secret content should be encrypted client-side before sending to the API. The server only stores encrypted data.
• Decryption keys: Never send decryption keys to the server. They should be passed via URL fragments (#key=...) which are not transmitted to the server.
• Rate limiting: API requests may be rate-limited based on instance settings.