GraphQL API Overview

The GraphQL API provides a streamlined, rendering-first interface optimized for client applications consuming published content via API keys. While the REST API offers comprehensive content management capabilities, the GraphQL API focuses exclusively on content delivery, providing a simplified interface that returns only the fields needed for rendering.

Key Principles

Rendering-First Design

Returns only fields needed for display and execution
Excludes CMS/editorial metadata not required for rendering
Includes compiled code ready for execution
Provides resolved dependencies in a single request

Published Content Only

Always returns the latest published version
No draft or unpublished content access
Assets are always active (deleted assets excluded)
Simplified status model: everything returned is ready to render

API Key Authentication

Designed for client-side applications
Uses the same API keys as REST endpoints
Read-only access to published resources
No user authentication required

Simplified Schema

No versioning complexity in queries
Status is implicit (all returned content is published)
Cleaner type definitions
Consistent naming with REST API

Real-time Subscriptions

WebSocket-based GraphQL subscriptions
Watch specific content for updates
Automatic filtering to published content
Efficient multiplexing over single connection

Preview Link Support

Token-based authentication (no API key required)
Access to draft components and unpublished content
Real-time updates via WebSocket subscriptions
Version-specific component previews

Endpoint

The GraphQL API is available at:

https://api.metabind.ai/graphql

Authentication

GraphQL requests require an API key in the request header:

headers: {
  'x-api-key': 'YOUR_API_KEY',
  'Content-Type': 'application/json'
}

For WebSocket subscriptions:

connectionParams: {
  headers: {
    'x-api-key': 'YOUR_API_KEY'
  }
}

Preview Link Authentication

Preview queries and subscriptions use a preview-token header instead of an API key:

headers: {
  'preview-token': 'YOUR_PREVIEW_TOKEN',
  'Content-Type': 'application/json'
}

Making Requests

HTTP POST

curl -X POST "https://api.metabind.ai/graphql" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { contents { data { id name } } }",
    "variables": {}
  }'

JavaScript

const response = await fetch('https://api.metabind.ai/graphql', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    query: `
      query GetContent($id: ID!) {
        content(id: $id) {
          id
          name
          compiled
        }
      }
    `,
    variables: { id: 'cont123' }
  })
});

const { data, errors } = await response.json();

Apollo Client

import { ApolloClient, InMemoryCache, createHttpLink } from '@apollo/client';

const client = new ApolloClient({
  link: createHttpLink({
    uri: 'https://api.metabind.ai/graphql',
    headers: {
      'x-api-key': 'YOUR_API_KEY'
    }
  }),
  cache: new InMemoryCache()
});

Response Format

Successful responses follow the standard GraphQL format:

{
  "data": {
    "content": {
      "id": "cont123",
      "name": "Getting Started"
    }
  }
}

Errors are returned in the errors array:

{
  "errors": [
    {
      "message": "Content not found",
      "extensions": {
        "code": "NOT_FOUND"
      },
      "path": ["content"]
    }
  ],
  "data": {
    "content": null
  }
}

​Key Principles

​Rendering-First Design

​Published Content Only

​API Key Authentication

​Simplified Schema

​Real-time Subscriptions

​Preview Link Support

​Endpoint

​Authentication

​Preview Link Authentication

​Making Requests

​HTTP POST

​JavaScript

​Apollo Client

​Response Format