GraphQL API

Programmatic access to George AI for building integrations, automation tools, and custom applications

Overview

George AI provides a comprehensive GraphQL API that allows you to programmatically interact with all platform features. This is ideal for building custom integrations, automation workflows (like n8n), or external applications.

Secure Access

Multiple authentication methods including API keys, JWT tokens, and library-scoped Bearer tokens

Type-Safe Schema

Strongly-typed GraphQL schema with introspection support for code generation and IDE autocomplete

Comprehensive API

Access to all platform features: conversations, libraries, files, crawlers, processing, and more

Automation Ready

Perfect for n8n workflows, Zapier integrations, custom dashboards, and automated data pipelines

API Endpoint

POST http://localhost:3003/graphql

application/json

Replace localhost:3003 with your George AI server URL in production environments.

Authentication

George AI supports multiple authentication methods for different use cases:

1. Global API Key (Recommended for Automation)

Full access to all resources. Best for server-to-server integrations, automation tools, and administrative operations.

x-api-key Header Authorization Header

x-api-key: your-api-key-here

Authorization: ApiKey your-api-key-here

How to get your Global API Key

The Global API Key is configured via environment variable on the server:

GRAPHQL_API_KEY=your-secret-key-here

Set this in your .env file or environment configuration. Default example value is TestKey (change this in production!).

Full Access

Server-to-Server

2. Library API Key (Scoped Access)

Scoped access to a specific library and its resources. Ideal for third-party integrations with limited permissions.

Authorization: Bearer library-specific-token-here

How to generate a Library API Key

Use the GraphQL mutation to create a library-scoped API key:

mutation {
  generateApiKey(
    libraryId: "library-id-here"
    name: "n8n Integration"
  ) {
    id
    name
    apiKey
    createdAt
  }
}

The apiKey field contains your Bearer token. Store it securely - it won't be shown again!

Scoped Access

Third-Party Integrations

3. User JWT Token (User Context)

User-specific access based on Keycloak authentication. Used by the George AI web application.

x-user-jwt: user-jwt-token-from-keycloak

This method requires Keycloak integration and is primarily used by the frontend application.

User Context

Web Application

4. Dev User Header (Development Only)

Bypass authentication in development environments for testing purposes.

x-dev-user: test-user-id

Only works when NODE_ENV is NOT production. Never use this in production!

Development Only

Testing

Making Requests

Using cURL

curl -X POST http://localhost:3003/graphql \

  -H "Content-Type: application/json" \

  -H "x-api-key: your-api-key-here" \

  -d '{
    "query": "query { aiServiceStatus { status } }"
  }'

Using JavaScript / Node.js

const response = await fetch('http://localhost:3003/graphql', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'your-api-key-here',
  },
  body: JSON.stringify({
    query: `
      query {
        aiLibraries {
          id
          name
          description
        }
      }
    `,
  })
})

const data = await response.json()

console.log(data.data.aiLibraries)

Using Python

import requests

url = "http://localhost:3003/graphql"

headers = {
    "Content-Type": "application/json",
    "x-api-key": "your-api-key-here"
}

query = """
query {
  aiLibraries {
    id
    name
    description
  }
}
"""

response = requests.post(
    url,
    json={ "query": query },
    headers=headers
)

data = response.json()
print(data["data"]["aiLibraries"])

Schema Introspection

Explore the GraphQL schema to discover all available queries, mutations, and types:

Interactive GraphQL Yoga UI

George AI uses GraphQL Yoga, which provides a modern, interactive GraphiQL interface built right into the server.

Open this URL in your browser to access the interactive GraphQL IDE

Features of the Yoga GraphiQL UI:

Auto-completion: IntelliSense for queries, mutations, and types
Documentation Explorer: Browse the complete schema with inline docs
Query History: Access previously executed queries
Variables Panel: Test queries with different input variables
Headers Configuration: Set authentication headers for testing

Authentication Required:

Click on "Headers" in the Yoga UI and add your authentication header:

{
  "x-api-key": "your-api-key-here"
}

Download Schema as SDL

The complete GraphQL schema is available as a file in the codebase:

apps/georgeai-webapp/src/gql/schema.graphql

This file is auto-generated by the codegen process and contains all types, queries, mutations, inputs, and enums.

Introspection Query Example

Use this query to fetch the entire schema programmatically:

query IntrospectionQuery {
  __schema {
    queryType { name }
    mutationType { name }
    types {
      name
      kind
      description
      fields {
        name
        description
        type {
          name
          kind
        }
      }
    }
  }
}

Common Operations

List All Libraries

query {
  aiLibraries {
    id
    name
    description
    filesCount
    createdAt
  }
}

Get Library Details

query {
  aiLibrary(libraryId: "library-id") {
    id
    name
    description
    filesCount
    crawlers {
      id
      name
      type
      status
    }
    files(take: 10, skip: 0) {
      items {
        id
        title
        originUri
        processingStatus
      }
      total
    }
  }
}

Create a New Library

mutation {
  createLibrary(data: {
    name: "My Knowledge Base"
    description: "Company documentation"
  }) {
    id
    name
    description
    createdAt
  }
}

Run a Crawler

mutation {
  runAiLibraryCrawler(crawlerId: "crawler-id")
}

Check Processing Queue Status

query {
  queueSystemStatus {
    totalPendingTasks
    totalProcessingTasks
    totalFailedTasks
    allWorkersRunning
    queues {
      queueType
      pendingTasks
      processingTasks
      failedTasks
      isRunning
    }
  }
}

Send Message to AI Assistant

mutation {
  sendMessage(data: {
    conversationId: "conversation-id"
    content: "What is our refund policy?"
  }) {
    id
    content
    role
    createdAt
  }
}

Tip: Use Schema Introspection

These are just examples. Explore the full schema at apps/georgeai-webapp/src/gql/schema.graphql to discover all available operations.

Integration with n8n

George AI's GraphQL API is perfect for building n8n workflows. Here's how to use it:

Add HTTP Request Node

In your n8n workflow, add an HTTP Request node

Method	POST
URL	http://localhost:3003/graphql
Body Content Type	JSON

Configure Authentication

Add authentication header in the "Headers" section

x-api-key

your-api-key-here

For library-scoped access, use Authorization header with Bearer {token} instead.

Set Request Body

Configure the JSON body with your GraphQL query or mutation

{
  "query": "query { aiLibraries { id name } }"
}

For mutations with variables:

{
  "query": "mutation($name: String!) { createLibrary(data: { name: $name }) { id name } }",
  "variables": {
    "name": "My Library"
  }
}

Process Response

Access the response data in subsequent nodes

{{$json.data.aiLibraries}}

{{$json.errors}}

GraphQL responses always return a data field for successful queries and an errors array for any errors.

Example n8n Workflow: Monitor Processing Queue

This workflow checks the processing queue every 5 minutes and sends a notification if there are failed tasks:

Cron Node: Trigger every 5 minutes
HTTP Request Node: Query queue status using GraphQL
IF Node: Check if totalFailedTasks > 0
Email Node: Send alert notification

// HTTP Request Body
{
  "query": "query { queueSystemStatus { totalFailedTasks queues { queueType failedTasks } } }"
}

Error Handling

GraphQL Errors

When a GraphQL query has errors, the response includes an errors array:

{
  "errors": [
    {
      "message": "Library not found",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["aiLibrary"]
    }
  ],
  "data": {
    "aiLibrary": null
  }
}

Authentication Errors

When authentication fails, the server returns a 401 status:

401 Unauthorized

Unauthorized

Always verify your API key is correct and that you're using the right authentication header format.

Network Errors

Connection issues will result in HTTP-level errors:

ECONNREFUSED: Server is not running or wrong port
ETIMEDOUT: Request timed out (check firewall/network)
500 Internal Server Error: Server-side issue (check logs)

Best Practices for Error Handling

Always check for the errors field in GraphQL responses
Implement retry logic for network errors
Log authentication failures for security monitoring
Handle partial data scenarios (when data and errors both exist)
Use appropriate timeouts for long-running operations

Best Practices

Security

• Never commit API keys to version control
• Use library-scoped keys for third-party integrations
• Rotate keys regularly
• Use environment variables for credentials

Performance

• Request only the fields you need
• Use pagination for large datasets
• Implement caching where appropriate
• Batch related operations when possible

Code Quality

• Use GraphQL code generators for type safety
• Define fragments for reusable field sets
• Validate queries during development
• Keep queries focused and single-purpose

Error Handling

• Always check for errors in responses
• Implement proper logging and monitoring
• Handle partial failures gracefully
• Provide meaningful error messages

Next Steps

Libraries Documentation

Learn about organizing and managing your document libraries via API

Crawler Configuration

Automate document collection from SharePoint, SMB, HTTP sources, and more

Processing Pipeline

Understand how documents are extracted and embedded for AI search

Conversations & Assistants

Build conversational AI experiences with custom assistants