This document provides comprehensive documentation for the Lilith GraphQL API.
Overview#
The Lilith GraphQL API provides a flexible, type-safe interface for content management, entity relationships, and knowledge graph operations. Built on Mercurius (Fastify GraphQL plugin), it supports queries, mutations, subscriptions, and real-time updates.
Endpoint: https://api.lilith.ai/graphql Playground:
https://api.lilith.ai/graphiql WebSocket: wss://api.lilith.ai/graphql
Quick Start#
Basic Query#
query GetContent {
content(id: "content_123") {
id
title
slug
summary
status
author {
id
name
tradition
}
metadata {
language
tradition
era
readingTime
}
}
}
HTTP Request#
curl -X POST https://api.lilith.ai/graphql \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <token>" \
-d '{
"query": "query { content(id: \"content_123\") { id title } }"
}'
Custom Scalars#
DateTime#
ISO 8601 date-time string.
scalar DateTime
Examples:
"2024-01-15T10:30:00.000Z""2024-03-20T14:45:30+05:30"
JSON#
Arbitrary JSON data.
scalar JSON
Enums#
ContentType#
enum ContentType {
TEXT
SUTRA
COMMENTARY
LECTURE
MEDITATION
TEACHING
POEM
PRAYER
MANTRA
STORY
BIOGRAPHY
}
ContentStatus#
enum ContentStatus {
DRAFT
REVIEW
PUBLISHED
ARCHIVED
}
Visibility#
enum Visibility {
PUBLIC
PRIVATE
PREMIUM
RESTRICTED
}
DifficultyLevel#
enum DifficultyLevel {
BEGINNER
INTERMEDIATE
ADVANCED
SCHOLARLY
}
DateCertainty#
enum DateCertainty {
EXACT
APPROXIMATE
RANGE
CENTURY
UNKNOWN
}
CitationStyle#
enum CitationStyle {
CHICAGO
MLA
APA
TURABIAN
}
EntityType#
enum EntityType {
PERSON
PLACE
CONCEPT
EVENT
TEXT
TRADITION
SCHOOL
DEITY
SYMBOL
}
RelationshipType#
enum RelationshipType {
REFERENCES
CITES
RESPONDS_TO
INFLUENCES
INFLUENCED_BY
TEACHER_OF
STUDENT_OF
BELONGS_TO
LOCATED_IN
CONTEMPORARY_OF
ASSOCIATED_WITH
}
SortDirection#
enum SortDirection {
ASC
DESC
}
ContentSortField#
enum ContentSortField {
TITLE
CREATED_AT
UPDATED_AT
PUBLISHED_AT
VIEWS
RELEVANCE
}
Object Types#
Content#
Primary content object for scholarly texts.
type Content {
id: ID!
slug: String!
title: String!
summary: String
body: String
contentType: ContentType!
status: ContentStatus!
visibility: Visibility!
author: Author
metadata: ContentMetadata
citations: [Citation!]
tags: [String!]
version: Int!
versions: [ContentVersion!]
createdAt: DateTime!
updatedAt: DateTime!
publishedAt: DateTime
}
Author#
Author/contributor information.
type Author {
id: ID!
name: String!
slug: String!
biography: String
tradition: String
era: String
birthYear: Int
deathYear: Int
imageUrl: String
content: [Content!]
createdAt: DateTime!
updatedAt: DateTime!
}
ContentMetadata#
Rich metadata for scholarly content.
type ContentMetadata {
language: String
originalLanguage: String
tradition: String
era: String
genre: String
tags: [String!]
dateComposed: DateRange
location: Location
wordCount: Int
readingTime: Int
difficulty: DifficultyLevel
}
Entity#
Knowledge graph entity.
type Entity {
id: ID!
name: String!
slug: String!
type: EntityType!
description: String
properties: [EntityProperty!]
relationships: [Relationship!]
incomingRelationships: [Relationship!]
metadata: JSON
createdAt: DateTime!
updatedAt: DateTime!
}
EntityProperty#
Entity attribute key-value pair.
type EntityProperty {
key: String!
value: String!
dataType: PropertyDataType!
}
Relationship#
Entity-to-entity relationship.
type Relationship {
id: ID!
type: RelationshipType!
sourceId: ID!
targetId: ID!
source: Entity
target: Entity
properties: JSON
strength: Float
createdAt: DateTime!
updatedAt: DateTime!
}
Citation#
Source citation information.
type Citation {
id: ID!
style: CitationStyle!
title: String!
author: String
year: Int
source: String
url: String
doi: String
isbn: String
pages: String
formatted: String
}
ContentVersion#
Version history entry.
type ContentVersion {
version: Int!
title: String!
body: String
changedBy: String
changedAt: DateTime!
changeNote: String
}
Connection Types (Pagination)#
The API uses Relay-style cursor-based pagination.
ContentConnection#
type ContentConnection {
edges: [ContentEdge!]!
pageInfo: PageInfo!
totalCount: Int!
}
type ContentEdge {
node: Content!
cursor: String!
}
EntityConnection#
type EntityConnection {
edges: [EntityEdge!]!
pageInfo: PageInfo!
totalCount: Int!
}
type EntityEdge {
node: Entity!
cursor: String!
}
AuthorConnection#
type AuthorConnection {
edges: [AuthorEdge!]!
pageInfo: PageInfo!
totalCount: Int!
}
type AuthorEdge {
node: Author!
cursor: String!
}
PageInfo#
type PageInfo {
hasNextPage: Boolean!
hasPreviousPage: Boolean!
startCursor: String
endCursor: String
}
Queries#
Content Queries#
Get Single Content#
query {
content(id: ID!): Content
}
Get Content by Slug#
query {
contentBySlug(slug: String!): Content
}
List Contents with Filtering#
query {
contents(
filter: ContentFilterInput
sort: ContentSortInput
first: Int
after: String
last: Int
before: String
): ContentConnection!
}
ContentFilterInput:
| Field | Type | Description |
|---|---|---|
contentType |
ContentType |
Filter by type |
status |
ContentStatus |
Filter by status |
visibility |
Visibility |
Filter by visibility |
authorId |
ID |
Filter by author |
tradition |
String |
Filter by tradition |
era |
String |
Filter by era |
language |
String |
Filter by language |
tags |
[String!] |
Filter by tags |
tagsMatch |
TagsMatch |
ALL or ANY tag match |
difficulty |
DifficultyLevel |
Filter by difficulty |
search |
String |
Full-text search |
publishedAfter |
DateTime |
Published date filter |
publishedBefore |
DateTime |
Published date filter |
Example:
query BuddhistTexts {
contents(
filter: {
tradition: "Buddhism"
status: PUBLISHED
difficulty: INTERMEDIATE
}
sort: { field: PUBLISHED_AT, direction: DESC }
first: 10
) {
edges {
node {
id
title
summary
author {
name
}
}
}
pageInfo {
hasNextPage
endCursor
}
totalCount
}
}
Search Content#
query {
searchContent(
query: String!
filter: ContentFilterInput
first: Int
after: String
): SearchResult!
}
SearchResult:
type SearchResult {
edges: [ContentEdge!]!
pageInfo: PageInfo!
totalCount: Int!
facets: SearchFacets
suggestions: [SearchSuggestion!]
}
type SearchFacets {
traditions: [FacetItem!]
eras: [FacetItem!]
types: [FacetItem!]
languages: [FacetItem!]
difficulties: [FacetItem!]
}
type FacetItem {
value: String!
count: Int!
}
Example:
query SearchMeditation {
searchContent(query: "mindfulness meditation", first: 20) {
edges {
node {
title
summary
metadata {
tradition
difficulty
}
}
}
facets {
traditions {
value
count
}
}
totalCount
}
}
Get Search Suggestions#
query {
suggestions(prefix: String!, limit: Int): [SearchSuggestion!]!
}
Author Queries#
Get Author#
query {
author(id: ID!): Author
}
List Authors#
query {
authors(
tradition: String
era: String
first: Int
after: String
): AuthorConnection!
}
Entity Queries#
Get Entity#
query {
entity(id: ID!): Entity
}
List Entities#
query {
entities(
filter: EntityFilterInput
first: Int
after: String
): EntityConnection!
}
EntityFilterInput:
| Field | Type | Description |
|---|---|---|
types |
[EntityType!] |
Filter by entity types |
search |
String |
Search entity names |
Get Entity Types#
query {
entityTypes: [EntityType!]!
}
Relationship Queries#
Get Relationship#
query {
relationship(id: ID!): Relationship
}
Get Entity Relationships#
query {
relationshipsByEntity(
entityId: ID!
type: RelationshipType
direction: String # "outgoing" | "incoming" | "both"
): [Relationship!]!
}
Get Relationship Types#
query {
relationshipTypes: [RelationshipType!]!
}
Knowledge Graph Queries#
Traverse Knowledge Graph#
query {
knowledgeGraph(
entityId: ID!
depth: Int
relationshipTypes: [RelationshipType!]
): KnowledgeGraphResult!
}
KnowledgeGraphResult:
type KnowledgeGraphResult {
entities: [Entity!]!
relationships: [Relationship!]!
metadata: KnowledgeGraphMetadata!
}
type KnowledgeGraphMetadata {
totalEntities: Int!
totalRelationships: Int!
maxDepthReached: Int!
traversalTime: Float!
}
Example:
query BuddhaInfluences {
knowledgeGraph(
entityId: "entity_buddha"
depth: 2
relationshipTypes: [INFLUENCES, TEACHER_OF]
) {
entities {
id
name
type
}
relationships {
type
source {
name
}
target {
name
}
}
metadata {
totalEntities
maxDepthReached
}
}
}
Mutations#
Content Mutations#
Create Content#
mutation {
createContent(input: CreateContentInput!): Content!
}
CreateContentInput:
| Field | Type | Required | Description |
|---|---|---|---|
title |
String! |
Yes | Content title |
slug |
String |
No | URL slug (auto-generated if omitted) |
summary |
String |
No | Content summary |
body |
String |
No | Full content body |
contentType |
ContentType! |
Yes | Content type |
visibility |
Visibility |
No | Visibility level |
authorId |
ID |
No | Author reference |
metadata |
ContentMetadataInput |
No | Content metadata |
tags |
[String!] |
No | Content tags |
Example:
mutation CreateSutra {
createContent(
input: {
title: "The Heart Sutra Commentary"
contentType: COMMENTARY
summary: "A modern interpretation of the Prajñāpāramitā Hṛdaya"
body: "..."
visibility: PUBLIC
metadata: {
tradition: "Buddhism"
language: "en"
difficulty: INTERMEDIATE
}
tags: ["Buddhism", "Mahayana", "Wisdom"]
}
) {
id
slug
status
}
}
Update Content#
mutation {
updateContent(id: ID!, input: UpdateContentInput!): Content!
}
Delete Content#
mutation {
deleteContent(id: ID!): DeleteResult!
}
Publish Content#
mutation {
publishContent(id: ID!): Content!
}
Archive Content#
mutation {
archiveContent(id: ID!): Content!
}
Restore Content Version#
mutation {
restoreContentVersion(id: ID!, version: Int!): Content!
}
Bulk Content Operations#
mutation {
bulkContentOperation(
operation: BulkOperation!
inputs: [BulkContentInput!]!
): BulkOperationResult!
}
BulkOperation Enum:
enum BulkOperation {
CREATE
UPDATE
DELETE
PUBLISH
ARCHIVE
}
BulkOperationResult:
type BulkOperationResult {
success: Boolean!
processed: Int!
failed: Int!
results: [Content!]
failures: [BulkFailure!]
}
type BulkFailure {
index: Int!
error: String!
}
Author Mutations#
Create Author#
mutation {
createAuthor(input: CreateAuthorInput!): Author!
}
CreateAuthorInput:
| Field | Type | Required | Description |
|---|---|---|---|
name |
String! |
Yes | Author name |
slug |
String |
No | URL slug |
biography |
String |
No | Biography |
tradition |
String |
No | Tradition |
era |
String |
No | Historical era |
birthYear |
Int |
No | Birth year |
deathYear |
Int |
No | Death year |
imageUrl |
String |
No | Profile image |
Update Author#
mutation {
updateAuthor(id: ID!, input: CreateAuthorInput!): Author!
}
Delete Author#
mutation {
deleteAuthor(id: ID!): DeleteResult!
}
Entity Mutations#
Create Entity#
mutation {
createEntity(input: CreateEntityInput!): Entity!
}
CreateEntityInput:
| Field | Type | Required | Description |
|---|---|---|---|
name |
String! |
Yes | Entity name |
slug |
String |
No | URL slug |
type |
EntityType! |
Yes | Entity type |
description |
String |
No | Description |
properties |
[EntityPropertyInput!] |
No | Properties |
metadata |
JSON |
No | Additional metadata |
Example:
mutation CreatePhilosopher {
createEntity(
input: {
name: "Nagarjuna"
type: PERSON
description: "Indian Mahayana Buddhist philosopher"
properties: [
{ key: "birthCentury", value: "2", dataType: INTEGER }
{ key: "tradition", value: "Madhyamaka", dataType: STRING }
]
}
) {
id
slug
type
}
}
Update Entity#
mutation {
updateEntity(id: ID!, input: CreateEntityInput!): Entity!
}
Delete Entity#
mutation {
deleteEntity(id: ID!): DeleteResult!
}
Relationship Mutations#
Create Relationship#
mutation {
createRelationship(input: CreateRelationshipInput!): Relationship!
}
CreateRelationshipInput:
| Field | Type | Required | Description |
|---|---|---|---|
type |
RelationshipType! |
Yes | Relationship type |
sourceId |
ID! |
Yes | Source entity ID |
targetId |
ID! |
Yes | Target entity ID |
properties |
JSON |
No | Relationship properties |
strength |
Float |
No | Relationship strength (0-1) |
Example:
mutation CreateInfluence {
createRelationship(
input: {
type: INFLUENCES
sourceId: "entity_nagarjuna"
targetId: "entity_chandrakirti"
strength: 0.9
properties: { domain: "philosophy", evidence: "direct lineage" }
}
) {
id
type
source {
name
}
target {
name
}
}
}
Update Relationship#
mutation {
updateRelationship(
id: ID!
properties: JSON
strength: Float
): Relationship!
}
Delete Relationship#
mutation {
deleteRelationship(id: ID!): DeleteResult!
}
Subscriptions#
Real-time updates via WebSocket.
Content Subscriptions#
Content Updated#
subscription {
contentUpdated(contentId: ID): ContentUpdateEvent!
}
ContentUpdateEvent:
type ContentUpdateEvent {
type: ContentUpdateType!
content: Content!
timestamp: DateTime!
changedFields: [String!]
}
enum ContentUpdateType {
CREATED
UPDATED
PUBLISHED
ARCHIVED
DELETED
}
Content Created#
subscription {
contentCreated(contentType: ContentType): Content!
}
Content Published#
subscription {
contentPublished(tradition: String): Content!
}
Entity Subscriptions#
Entity Updated#
subscription {
entityUpdated(entityType: EntityType): EntityUpdateEvent!
}
EntityUpdateEvent:
type EntityUpdateEvent {
type: EntityUpdateType!
entity: Entity!
timestamp: DateTime!
}
enum EntityUpdateType {
CREATED
UPDATED
DELETED
RELATIONSHIP_ADDED
RELATIONSHIP_REMOVED
}
Subscription Example#
import { createClient } from 'graphql-ws';
const client = createClient({
url: 'wss://api.lilith.ai/graphql',
connectionParams: {
authorization: `Bearer ${token}`,
},
});
// Subscribe to content updates
const unsubscribe = client.subscribe(
{
query: `
subscription {
contentUpdated {
type
content {
id
title
status
}
timestamp
}
}
`,
},
{
next: (data) => {
console.log('Content updated:', data);
},
error: (err) => {
console.error('Subscription error:', err);
},
complete: () => {
console.log('Subscription complete');
},
}
);
// Later: unsubscribe
unsubscribe();
Error Handling#
Error Response Format#
{
"data": null,
"errors": [
{
"message": "Content not found",
"locations": [{ "line": 2, "column": 3 }],
"path": ["content"],
"extensions": {
"code": "NOT_FOUND",
"timestamp": "2024-01-15T10:30:00.000Z"
}
}
]
}
Error Codes#
| Code | Description |
|---|---|
NOT_FOUND |
Resource not found |
UNAUTHORIZED |
Authentication required |
FORBIDDEN |
Insufficient permissions |
VALIDATION_ERROR |
Invalid input data |
CONFLICT |
Resource conflict (e.g., duplicate slug) |
INTERNAL_ERROR |
Server error |
Pagination#
The API uses Relay-style cursor-based pagination.
Forward Pagination#
query {
contents(first: 10, after: "cursor123") {
edges {
node {
id
title
}
cursor
}
pageInfo {
hasNextPage
endCursor
}
}
}
Backward Pagination#
query {
contents(last: 10, before: "cursor456") {
edges {
node {
id
title
}
cursor
}
pageInfo {
hasPreviousPage
startCursor
}
}
}
Pagination Best Practices#
- Use
first/afterfor forward pagination - Store
endCursorfor next page requests - Check
hasNextPagebefore fetching more - Default page size: 20, max: 100
Rate Limiting#
| Operation | Limit |
|---|---|
| Queries | 100/minute |
| Mutations | 50/minute |
| Subscriptions | 10 concurrent |
| Complexity | 1000 points/query |
Complexity Calculation#
- Each field: 1 point
- Connections: 10 points + (first × child complexity)
- Nested resolvers: Multiplicative
Best Practices#
Query Optimization#
# DO: Request only needed fields
query {
contents(first: 10) {
edges {
node {
id
title
}
}
}
}
# DON'T: Over-fetch
query {
contents(first: 100) {
edges {
node {
id
title
body # Large field
versions # Expensive nested query
author {
content # N+1 query
}
}
}
}
}
Batching Requests#
# Batch multiple queries
query BatchedQueries {
content1: content(id: "id1") {
title
}
content2: content(id: "id2") {
title
}
content3: content(id: "id3") {
title
}
}
Fragment Reuse#
fragment ContentSummary on Content {
id
title
summary
status
}
query {
recentContent: contents(
first: 5
sort: { field: CREATED_AT, direction: DESC }
) {
edges {
node {
...ContentSummary
}
}
}
popularContent: contents(first: 5, sort: { field: VIEWS, direction: DESC }) {
edges {
node {
...ContentSummary
}
}
}
}
Related Documentation#
- TypeScript SDK Reference - SDK with GraphQL client
- Authentication Guide - API authentication
- Error Codes - Complete error reference
- API Versioning - Version management
GraphQL Playground#
Access the interactive GraphQL IDE at:
- Development: http://localhost:8080/graphiql
- Production: https://api.lilith.ai/graphiql
Features:
- Schema explorer
- Auto-complete
- Query history
- Variable editor
- Response viewer