Spellbook API Reference

This reference provides a conceptual overview of the Spellbook API for working with Temporal Bayesian Knowledge Graphs.

API Versioning

Spellbook uses URL-based versioning for its API to ensure backward compatibility as the system evolves:

https://spellbook.magick.ai/api/v1/memories

All API endpoints are prefixed with /api/v1/ to indicate they are using version 1 of the API.

Interactive API Documentation

For interactive API documentation with the ability to test endpoints directly, visit the Swagger UI.

The Swagger UI provides:

• Detailed endpoint documentation
• Request and response schemas
• The ability to try API calls directly from your browser
• Authentication support

Core Concepts

Knowledge Graph Elements

Element	Description
Entity	A node in the knowledge graph representing a person, place, concept, or object
Relationship	An edge connecting two entities, describing how they relate to each other
Property	An attribute or characteristic of an entity or relationship
Temporal Annotation	Time-based metadata attached to entities, relationships, or properties
Belief Score	A probabilistic confidence value associated with a fact or relationship

Graph Operations

Operation	Description
Create	Add new entities, relationships, or properties to the graph
Read	Query and retrieve information from the graph
Update	Modify existing entities, relationships, or properties
Delete	Remove elements from the graph
Merge	Combine information from multiple sources with appropriate belief updates

API Structure

The Spellbook API is organized into several functional areas, all accessible under the /api/v1 base path:

Entity Management

APIs for creating, retrieving, updating, and deleting entities in the knowledge graph.

Relationship Management

APIs for establishing, modifying, and removing relationships between entities.

Temporal Operations

APIs for working with the temporal aspects of the knowledge graph, including:

• Querying the state of the graph at a specific point in time
• Tracking the evolution of entities and relationships over time
• Analyzing temporal patterns and trends

Bayesian Inference

APIs for probabilistic reasoning, including:

• Updating belief scores based on new evidence
• Calculating conditional probabilities
• Performing inference across the graph

Query and Search

APIs for retrieving information from the knowledge graph:

• Entity and relationship lookup
• Pattern matching across the graph
• Semantic similarity search
• Temporal and causal reasoning queries

Authentication and Access Control

Access to the Spellbook API is controlled through:

• API keys for service-to-service communication
• JWT tokens for user authentication
• Role-based access control for multi-tenant deployments

Integration Points

Spellbook provides integration capabilities with:

• Large Language Models via the Model Context Protocol (MCP)
• Workflow automation tools
• Custom applications via REST APIs

API Examples

Here are some examples of how to use the Spellbook API with versioned endpoints:

Creating an Entity

curl -X POST https://spellbook.magick.ai/api/v1/entities \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "Albert Einstein",
    "type": "person",
    "description": "Theoretical physicist who developed the theory of relativity",
    "metadata": {
      "birth_year": 1879,
      "death_year": 1955
    }
  }'

Retrieving Entities

# Get all entities
curl -X GET https://spellbook.magick.ai/api/v1/entities \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get a specific entity by ID
curl -X GET https://spellbook.magick.ai/api/v1/entities/12345 \
  -H "Authorization: Bearer YOUR_API_KEY"

Creating a Relationship

curl -X POST https://spellbook.magick.ai/api/v1/relationships \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "sourceEntityId": "12345",
    "targetEntityId": "67890",
    "type": "developed",
    "metadata": {
      "year": 1915
    }
  }'

Temporal Query

curl -X POST https://spellbook.magick.ai/api/v1/query/temporal \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "entityId": "12345",
    "startTime": "1900-01-01T00:00:00Z",
    "endTime": "1920-01-01T00:00:00Z"
  }'