API Overview

Essence Platform provides two powerful APIs to integrate with your applications: GraphQL and REST. Choose the one that best fits your needs.

API Endpoints

Production

GraphQL: https://api.essence.digital/graphql
REST:    https://api.essence.digital/api/v1

Development

GraphQL: https://dev-api.essence.digital/graphql
REST:    https://dev-api.essence.digital/api/v1

API Comparison

Feature	GraphQL	REST
Flexibility	Request exactly what you need	Fixed response structures
Efficiency	Single request for nested data	Multiple requests often needed
Real-time	WebSocket subscriptions ✅	Webhooks only
Learning Curve	Steeper	Gentler
Caching	Custom	HTTP caching
Tooling	Playground, introspection	Swagger UI, OpenAPI

GraphQL API

Modern, flexible API with powerful querying capabilities.

Why Choose GraphQL?

✅ Precise Data Fetching — Request only the fields you need ✅ Nested Relationships — Load related data in a single request ✅ Real-time Updates — WebSocket subscriptions for live data ✅ Strong Typing — Complete type safety with schema ✅ Self-Documenting — Built-in schema introspection

Quick Example

query {
  vaults {
    id
    name
    documents {
      id
      fileName
    }
  }
}

Learn more about GraphQL API →

REST API

Traditional REST endpoints for compatibility and simplicity.

Why Choose REST?

✅ Familiar — Standard HTTP methods and status codes ✅ Cacheable — Leverage HTTP caching ✅ Stateless — Simple request/response model ✅ Tooling — Works with any HTTP client ✅ OpenAPI — Complete specification available

Quick Example

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

Learn more about REST API →

Authentication

Both APIs use the same authentication mechanisms:

Bearer Token (JWT)

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

API Key

X-Api-Key: your-api-key-here

Learn more about authentication →

Rate Limiting

Both APIs share the same rate limits:

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

Learn more about rate limiting →

Versioning

API Versions

• Current: v1 (stable)
• Status: Generally Available
• Deprecation Policy: 12 months notice

REST API Versioning

REST API version is included in the URL:

/api/v1/vaults
/api/v2/vaults  (when available)

GraphQL API Versioning

GraphQL uses schema evolution rather than versioning:

• Fields are never removed, only deprecated
• New fields added without breaking changes
• @deprecated directive marks old fields

Learn more about versioning →

SDKs

Official SDKs are available for popular languages:

JavaScript/TypeScript

npm install @essence/sdk

import { EssenceClient } from '@essence/sdk';

const client = new EssenceClient({
  apiKey: 'your-api-key'
});

SDK Documentation →

Python

pip install essence-sdk

C#

dotnet add package Essence.Sdk

Error Handling

Both APIs return structured errors:

GraphQL Errors

{
  "errors": [
    {
      "message": "Vault not found",
      "extensions": {
        "code": "NOT_FOUND",
        "vaultId": "vault-123"
      }
    }
  ]
}

REST Errors

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Vault not found",
    "vaultId": "vault-123"
  }
}

Performance

Both APIs deliver excellent performance:

Metric	Target	Actual
Average Response Time	<200ms	~145ms
95th Percentile	<300ms	~275ms
Throughput	1K req/sec	1.2K req/sec

Try It Out

Interactive Playgrounds

• GraphQL Playground — Try GraphQL queries
• REST Explorer — Test REST endpoints

Code Examples

• Tutorials — Step-by-step guides
• SDK Examples — Common use cases

OpenAPI Specification

Download the complete API specification:

• OpenAPI 3.0 JSON
• OpenAPI 3.0 YAML
• Postman Collection

Status & Uptime

Check API status and historical uptime:

status.essence.digital →

• Current status
• Incident history
• Scheduled maintenance
• Subscribe to updates

Support

Need help with the API?

• Browse Documentation
• Discord Community
• Email Support
• GitHub Issues

Best Practices

1. Use the SDK

The official SDK handles:

• Authentication
• Error handling
• Retry logic
• Rate limiting
• Type safety

2. Implement Retry Logic

async function withRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      if (error.code === 'RATE_LIMIT_EXCEEDED') {
        await delay(error.retryAfter * 1000);
      } else {
        throw error;
      }
    }
  }
}

3. Cache Responses

// Cache GET requests
const cache = new Map();
const cacheKey = `vaults:${userId}`;

if (cache.has(cacheKey)) {
  return cache.get(cacheKey);
}

const vaults = await client.vaults.list();
cache.set(cacheKey, vaults);
setTimeout(() => cache.delete(cacheKey), 5 * 60 * 1000); // 5 min TTL

4. Handle Errors Gracefully

try {
  const vault = await client.vaults.get(vaultId);
} catch (error) {
  if (error.code === 'NOT_FOUND') {
    // Handle missing vault
  } else if (error.code === 'FORBIDDEN') {
    // Handle permission error
  } else {
    // Log unexpected error
    console.error('Unexpected error:', error);
  }
}

5. Use Environment Variables

// ❌ Bad
const client = new EssenceClient({
  apiKey: 'essence_sk_abc123'
});

// ✅ Good
const client = new EssenceClient({
  apiKey: process.env.ESSENCE_API_KEY
});

Next Steps

1. Quick Start — Your first API call
2. Authentication — Set up auth
3. Choose Your API — GraphQL or REST
4. Try the Playground — Interactive testing

---

Ready to build? Check out our tutorials for step-by-step guides.