GraphQL API Overview

Essence Platform provides a modern GraphQL API with powerful querying capabilities, real-time subscriptions, and comprehensive type safety.

Endpoint

POST https://api.essence.digital/graphql

Authentication

Include your JWT token or API key in the Authorization header:

Authorization: Bearer your-jwt-token-here

Or use an API key:

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

Schema Overview

The Essence GraphQL schema is organized into three main operation types:

Queries (26 operations)

Read-only operations to fetch data:

• Vaults: vaults, getVault, searchVaults, getVaultStatistics, getVaultsByCategory
• Documents: documents, getDocument, searchDocuments, getDocumentByShareToken, getDocumentVersions, getDocumentShares, getRecentDocuments, getDocumentsByCategory
• Instances: getMyInstance, getAllInstances, getInstancesByType, getInstancesByOrganization, getInstancesByRegion, getInstancesByStatus, getInstanceHealth, getInstanceStatistics, searchInstances
• Users: me, getUser

Mutations (9 operations)

Write operations to modify data:

• Vaults: createVault, updateVault, deleteVault, shareVault
• Documents: createDocument, updateDocument, shareDocument, updateDocumentShare, revokeDocumentShare

Subscriptions (4 operations)

Real-time updates via WebSockets:

• onVaultUpdated: Notified when a vault changes
• onDocumentUpdated: Notified when documents change
• onDocumentShareAccessed: Notified when someone accesses a shared document
• onVaultQuotaWarning: Notified when approaching storage limits

Quick Example

typescript

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

const client = new EssenceClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.essence.digital'
});

// Query vaults with nested document loading
const response = await client.graphql.query(`
  query GetVaultsWithDocuments {
    vaults {
      id
      name
      documentCount
      documents {
        id
        fileName
        sizeBytes
        createdAt
      }
    }
  }
`);

console.log(response.data.vaults);

javascript

const { EssenceClient } = require('@essence-platform/sdk');

const client = new EssenceClient({
  apiKey: 'your-api-key',
  baseUrl: 'https://api.essence.digital'
});

// Query vaults with nested document loading
const response = await client.graphql.query(`
  query GetVaultsWithDocuments {
    vaults {
      id
      name
      documentCount
      documents {
        id
        fileName
        sizeBytes
        createdAt
      }
    }
  }
`);

console.log(response.data.vaults);

Features

1. Precise Data Fetching

Request exactly the data you need, nothing more:

query {
  vaults {
    id
    name
    # Only fetch what you need
  }
}

2. Nested Relationships

Load related data in a single request:

query {
  vaults {
    id
    name
    documents {
      id
      fileName
      versions {
        versionNumber
        createdAt
      }
    }
  }
}

3. Filtering and Sorting

Built-in support for filtering and sorting:

query {
  vaults(
    where: { isActive: { eq: true } }
    order: { createdAt: DESC }
  ) {
    id
    name
  }
}

4. Pagination

Cursor-based pagination for large result sets:

query {
  vaults(first: 10, after: "cursor123") {
    nodes {
      id
      name
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

5. Real-time Subscriptions

Subscribe to changes via WebSockets:

subscription {
  onVaultUpdated(userId: "user-id") {
    vault {
      id
      name
      updatedAt
    }
    changeType
  }
}

6. Field-Level Authorization

Sensitive fields are automatically protected:

query {
  me {
    id
    email
    passwordChangedAt  # Only visible to the user themselves
  }
}

Error Handling

GraphQL returns structured errors:

{
  "errors": [
    {
      "message": "You don't have permission to access this vault",
      "extensions": {
        "code": "FORBIDDEN",
        "vaultId": "vault-123"
      }
    }
  ],
  "data": null
}

Common Error Codes

Code	Description
UNAUTHENTICATED	Missing or invalid authentication
FORBIDDEN	Insufficient permissions
NOT_FOUND	Resource doesn't exist
BAD_USER_INPUT	Invalid input data
RATE_LIMIT_EXCEEDED	Too many requests
INTERNAL_SERVER_ERROR	Server error

Query Complexity

To prevent abuse, queries are limited by:

• Max Depth: 10 levels of nesting
• Max Complexity: 1000 points
• Timeout: 30 seconds

Each field adds to the complexity score. The server will reject queries that exceed these limits.

Try It Out

Explore the API interactively:

• GraphQL Playground — Try queries in your browser
• Query Examples — Browse common queries
• Mutation Examples — See how to modify data
• Subscription Examples — Real-time updates

Best Practices

1. Use Fragments for Reusability

fragment VaultFields on Vault {
  id
  name
  documentCount
  createdAt
}

query {
  vaults {
    ...VaultFields
  }
}

2. Leverage DataLoaders

The API uses DataLoaders to batch requests and prevent N+1 queries. Take advantage of this by requesting nested data:

query {
  vaults {
    documents {  # Batched efficiently
      fileName
    }
  }
}

3. Request Only Needed Fields

# ❌ Over-fetching
query {
  vaults {
    id
    name
    description
    category
    isActive
    documentCount
    totalSize
    createdAt
    updatedAt
    # ... all fields
  }
}

# ✅ Optimized
query {
  vaults {
    id
    name
    documentCount
  }
}

4. Handle Errors Gracefully

try {
  const response = await client.graphql.query(query);

  if (response.errors) {
    // Handle GraphQL errors
    response.errors.forEach(error => {
      if (error.extensions?.code === 'RATE_LIMIT_EXCEEDED') {
        // Wait and retry
      } else {
        console.error('GraphQL error:', error.message);
      }
    });
  }

  return response.data;
} catch (error) {
  // Handle network errors
  console.error('Network error:', error);
}

5. Use Variables for Dynamic Queries

const query = `
  query GetVault($id: ID!) {
    getVault(id: $id) {
      id
      name
      documents {
        id
        fileName
      }
    }
  }
`;

const variables = {
  id: 'vault-123'
};

const response = await client.graphql.query(query, variables);

Schema Introspection

The GraphQL schema supports introspection (in development mode):

query {
  __schema {
    types {
      name
      description
    }
  }
}

Use this to build tools, generate types, or explore the schema programmatically.

Performance

GraphQL API performance metrics:

Metric	Target	Actual
Simple Query	<200ms	~145ms
Complex Query (3 levels)	<500ms	~387ms
Subscription Setup	<100ms	~75ms
DataLoader Efficiency	10x	50x

Rate Limiting

GraphQL queries count toward your rate limit based on complexity:

• Simple queries: 1 point
• Nested queries: 1 point per level
• Mutations: 2 points
• Subscriptions: 0 points (separate connection limit)

Example:

query {
  vaults {              # 1 point
    documents {         # 1 point
      versions {        # 1 point
        # Total: 3 points
      }
    }
  }
}

Next Steps

• Queries — Browse all available queries
• Mutations — Learn how to modify data
• Subscriptions — Real-time updates
• Types — Explore the type system
• Playground — Try it interactively

---

Need help? Check out our tutorials or join our Discord.