REST API Explorer

Interactive REST API Explorer

Explore and test all REST API endpoints using Swagger UI. You can execute real API calls directly from your browser.

Authentication Required

To use the "Try it out" feature, click the "Authorize" button at the top right and enter your:

• Bearer Token: JWT token from authentication
• API Key: X-Api-Key header from settings

The explorer will remember your authentication for this session.

Quick Start

1. Get Your API Key

1. Sign in to app.essence.digital
2. Navigate to Settings → API Keys
3. Click Generate New API Key
4. Copy your API key

2. Authorize

1. Click the "Authorize" button above (🔓 icon)
2. Enter your API key in the X-Api-Key field
3. Or enter your JWT token in the Bearer field
4. Click "Authorize"
5. Click "Close"

3. Try an Endpoint

1. Find an endpoint (e.g., GET /api/v1/vaults)
2. Click to expand the endpoint
3. Click "Try it out"
4. Edit parameters if needed
5. Click "Execute"
6. View the response below

API Endpoints Overview

Vaults

Method	Endpoint	Description
GET	/api/v1/vaults	List all vaults
POST	/api/v1/vaults	Create new vault
GET	/api/v1/vaults/{id}	Get vault by ID
PUT	/api/v1/vaults/{id}	Update vault
DELETE	/api/v1/vaults/{id}	Delete vault
GET	/api/v1/vaults/search	Search vaults

Documents

Method	Endpoint	Description
GET	/api/v1/documents	List documents
POST	/api/v1/documents	Upload document
GET	/api/v1/documents/{id}	Get document
PUT	/api/v1/documents/{id}	Update document
DELETE	/api/v1/documents/{id}	Delete document
POST	/api/v1/documents/{id}/share	Create share link
GET	/api/v1/documents/share/{token}	Access shared document

Instances

Method	Endpoint	Description
GET	/api/v1/instances	List instances
GET	/api/v1/instances/{id}	Get instance
GET	/api/v1/instances/{id}/health	Get instance health
GET	/api/v1/instances/statistics	Get statistics

Users

Method	Endpoint	Description
GET	/api/v1/users/me	Get current user
PUT	/api/v1/users/me	Update profile

Example API Calls

Create a Vault

curl -X POST https://api.essence.digital/api/v1/vaults \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Personal Vault",
    "description": "Personal documents",
    "category": "personal"
  }'

Response:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "My Personal Vault",
  "description": "Personal documents",
  "category": "personal",
  "userId": "user-123",
  "isActive": true,
  "documentCount": 0,
  "totalSize": 0,
  "createdAt": "2025-11-06T10:00:00Z"
}

List All Vaults

curl -X GET https://api.essence.digital/api/v1/vaults \
  -H "Authorization: Bearer YOUR_TOKEN"

Upload a Document

curl -X POST https://api.essence.digital/api/v1/documents \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vaultId": "vault-id-here",
    "fileName": "document.pdf",
    "encryptedData": "base64-encrypted-data",
    "sizeBytes": 1024,
    "mimeType": "application/pdf",
    "encryptionMetadata": {
      "algorithm": "AES-256-GCM",
      "keyDerivation": "PBKDF2",
      "iterations": 100000,
      "iv": "base64-iv",
      "authTag": "base64-auth-tag"
    }
  }'

Share a Document

curl -X POST https://api.essence.digital/api/v1/documents/{id}/share \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": ["read"],
    "expiresAt": "2025-12-31T23:59:59Z",
    "maxAccessCount": 5
  }'

Response:

{
  "id": "share-123",
  "shareToken": "secure-random-token-here",
  "permissions": ["read"],
  "expiresAt": "2025-12-31T23:59:59Z",
  "maxAccessCount": 5,
  "accessCount": 0,
  "isActive": true
}

Response Codes

Code	Description
200 OK	Request successful
201 Created	Resource created successfully
204 No Content	Request successful, no content returned
400 Bad Request	Invalid request parameters
401 Unauthorized	Missing or invalid authentication
403 Forbidden	Insufficient permissions
404 Not Found	Resource not found
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Server error

Error Response Format

All error responses follow this format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Vault name is required",
    "details": {
      "field": "name",
      "constraint": "required"
    },
    "timestamp": "2025-11-06T10:00:00Z",
    "requestId": "req-123"
  }
}

Rate Limiting

API responses include rate limit headers:

X-Rate-Limit-Limit: 1000
X-Rate-Limit-Remaining: 995
X-Rate-Limit-Reset: 2025-11-06T11:00:00Z

Rate Limits by Tier

Tier	Hourly Limit	Burst Limit
Free	1,000	10/minute
Paid	10,000	100/minute
Enterprise	100,000	1,000/minute

When rate limited, you'll receive:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "API rate limit exceeded",
    "retryAfter": 45
  }
}

Pagination

List endpoints support pagination:

GET /api/v1/vaults?page=1&pageSize=20&sortBy=createdAt&sortOrder=desc

Response:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalPages": 5,
    "totalCount": 95,
    "hasNextPage": true,
    "hasPreviousPage": false
  }
}

Filtering

Use query parameters to filter results:

# Filter by category
GET /api/v1/vaults?category=health

# Filter by active status
GET /api/v1/vaults?isActive=true

# Search by name
GET /api/v1/vaults?search=medical

# Combine filters
GET /api/v1/vaults?category=health&isActive=true&sortBy=name

Sorting

Sort results using sortBy and sortOrder:

# Sort by creation date (newest first)
GET /api/v1/vaults?sortBy=createdAt&sortOrder=desc

# Sort by name (A-Z)
GET /api/v1/vaults?sortBy=name&sortOrder=asc

# Sort by document count
GET /api/v1/documents?sortBy=documentCount&sortOrder=desc

OpenAPI Specification

Download the complete OpenAPI specification:

• OpenAPI 3.0 JSON
• OpenAPI 3.0 YAML

Use these to generate client SDKs, mock servers, or import into tools like Postman.

Alternative Tools

Postman

1. Download OpenAPI spec
2. Open Postman
3. Click Import → Link
4. Paste the OpenAPI URL
5. Postman will create a collection with all endpoints

Insomnia

1. Open Insomnia
2. Click Create → Import
3. Enter URL: https://api.essence.digital/openapi/v1.json
4. Insomnia will import all endpoints

cURL

For command-line testing, use cURL with the examples above.

HTTPie

For a more user-friendly CLI:

# Install httpie
pip install httpie

# Make requests
http GET https://api.essence.digital/api/v1/vaults \
  Authorization:"Bearer YOUR_TOKEN"

http POST https://api.essence.digital/api/v1/vaults \
  Authorization:"Bearer YOUR_TOKEN" \
  name="My Vault" \
  category="personal"

Next Steps

• GraphQL Playground — Try the GraphQL API
• API Reference — Complete API documentation
• SDK Documentation — Use our TypeScript SDK
• Tutorials — Step-by-step guides

---

Need help? Join our Discord community or email support.