Build on the Ontology

MCP-native. Ontology-powered. Ready for your code. Build plugins that query a living knowledge graph of real user data — people, transactions, events, goals — and ship intelligent features on day one.

Get started API Reference

Skip the Context Layer

Every Oxagen user brings a personal ontology — hundreds of connected entities and relationships your plugin can query instantly. Stop building context. Start building features.

Zero Cold Starts

Your plugin inherits a personal knowledge graph that took the user months to build. No onboarding friction. No data collection. Just rich, structured context from day one.

Cross-System Reasoning

Calendars, finances, contacts, goals — all connected. Build intelligent features without building the data layer. One plugin, full life context.

Overview

Everything you need to integrate with Oxagen.

The Oxagen platform empowers you to build AI plugins and tools powered by users' living ontologies — rich, always-updating graphs of real-life context from their connected apps. Our developer ecosystem is built on openness via MCP, portability, and privacy. Create differentiated experiences that tap into deep user context and reach users who value intelligence and control.

Base URL

All API endpoints are served under a single base URL. Append the path for each resource.

https://api.oxagen.ai/v1

Response Format

Every response is JSON. Successful responses return the resource directly. Errors return {"detail": "..."}.

{"status": "ok", "version": "0.2.1"}

Streaming

The agent chat endpoint supports Server-Sent Events (SSE) for real-time streaming of AI responses, tool calls, and results.

POST /v1/agent/chat/stream

Rate Limits

Authenticated requests are limited to 60 req/min per user. Public (unauthenticated) endpoints are limited to 10 req/min per IP.

X-RateLimit-Remaining: 58

Authentication

Authenticate with JWT tokens passed as Bearer tokens.

Oxagen uses Custom JWT (RS256) for authentication. Every authenticated request must include a valid JWT in theAuthorizationheader. The backend validates the token and resolves the user and tenant automatically.

bash

# Obtain a session token, then:
curl -X GET "https://api.oxagen.ai/v1/users/me" \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json"

python

import httpx

TOKEN = "eyJhbGci..."  # JWT access token

resp = httpx.get(
    "https://api.oxagen.ai/v1/users/me",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
print(resp.json())

typescript

const resp = await fetch("https://api.oxagen.ai/v1/users/me", {
  headers: { Authorization: "Bearer " + token },
});
const user = await resp.json();

API Reference

Auto-generated from the live OpenAPI specification.

Loading API specification…

The Ontology

Oxagen's knowledge graph maps relationships across every entity in a user's digital life.

The ontology is the core data model. Every connected data source (email, calendar, finances, files) feeds entities and relationships into a per-tenant knowledge graph. AI agents reason over this graph to answer cross-system questions and surface intelligent insights.

Entity types and relationship types are free-form strings — the system accepts any type you define. The table below lists common types used by the AI classifier, but user-specific types (e.g. job_post, experiment, invoice) are discovered and created automatically as data flows in.

Common Entity Types

Entity types are free-form strings. These are the most common types used by the AI classifier. You can create entities with any type.

Type	Description
person	A person — contact, colleague, family member
business	A business, company, or organization
trip	A trip with related events and expenses
receipt	A receipt or proof of purchase
transaction	A financial transaction
meeting	A calendar meeting or appointment
subscription	A recurring subscription or membership
goal	A financial or personal goal
budget	A budget with categories and limits
document	A document, file, or note
photo	A photograph or image
message	An email, chat message, or notification
task	A task or to-do item
account	A financial account
expense_report	An expense report
loan	A loan or debt
location	A physical location or venue
event	A general event

Common Relationship Types

Relationship types are free-form strings. These are the most common types. You can create relationships with any type.

Type	Description
belongs_to	Entity belongs to another (e.g. transaction → trip)
attended_by	Event attended by a person
paid_by	Transaction paid by a person or account
works_at	Person works at a business or organization
member_of	Person is a member of a group or organization
organized_by	Event or meeting organized by a person or business
scheduled_for	Entity scheduled for a specific date or event
occurred_during	Happened during a time period or trip
related_to	General association between entities
linked_to	Explicit link between entities
part_of	Entity is part of a larger entity
generated_by	Created by a workflow or agent

Building on the Graph

Use the REST API or MCP tools to create entities, define relationships, and query the graph. Here's an example that creates a trip entity and links a transaction to it:

python

import httpx

BASE = "https://api.oxagen.ai/v1"
HEADERS = {"Authorization": f"Bearer {TOKEN}"}

# 1. Create a trip entity
trip = httpx.post(f"{BASE}/mcp", headers=HEADERS, json={
    "jsonrpc": "2.0", "id": 1,
    "method": "tools/call",
    "params": {
        "name": "create_entity",
        "arguments": {
            "entity_type": "trip",
            "name": "NYC Business Trip",
            "description": "March 2026 client meetings",
            "properties": {"city": "New York", "dates": "2026-03-15 to 2026-03-18"}
        }
    }
}).json()

trip_id = trip["result"]["content"][0]["text"]  # JSON with entity id

# 2. Link an existing transaction to the trip
httpx.post(f"{BASE}/mcp", headers=HEADERS, json={
    "jsonrpc": "2.0", "id": 2,
    "method": "tools/call",
    "params": {
        "name": "create_relationship",
        "arguments": {
            "source_entity_id": "<transaction-uuid>",
            "target_entity_id": "<trip-uuid>",
            "relationship_type": "belongs_to"
        }
    }
})

MCP Server

Beta

Connect AI tools directly to the ontology via the Model Context Protocol.

Oxagen exposes a Model Context Protocol (MCP) server that lets AI clients — Claude Desktop, custom agents, or any MCP-compatible tool — interact with the ontology directly. The server uses JSON-RPC 2.0 over HTTP. The MCP server is currently in beta and under active development.

MCP enables AI to search your knowledge graph, create entities, build relationships, and list connected data sources — all through a standardized protocol that works with any MCP client.

Connect with Claude Desktop

Add this to your claude_desktop_config.json:

json

{
  "mcpServers": {
    "oxagen": {
      "url": "https://api.oxagen.ai/v1/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_TOKEN"
      }
    }
  }
}

Available Tools

search_entities

Search ontology entities by type, name, or keyword

get_entity

Get a single ontology entity by ID

get_entity_relationships

List relationships for an entity (inbound and outbound)

create_entity

Create a new ontology entity with a free-form entity type

create_relationship

Create a relationship between two ontology entities

list_entity_types

List entity types that have been used in your ontology

list_connections

List your data connections (Gmail, Calendar, Plaid, etc.)

list_artifacts

List generated artifacts (reports, dashboards, summaries)

Example: Search Entities

bash

curl -X POST "https://api.oxagen.ai/v1/mcp" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_entities",
      "arguments": {
        "query": "dinner expenses",
        "entity_type": "transaction",
        "limit": 10
      }
    }
  }'

Protocol Reference

Method	Description
initialize	Handshake — returns server info and capabilities
tools/list	List all available ontology tools with input schemas
tools/call	Execute a tool with the given arguments

The Ontology Is Built. Now Build What's Next.

Oxagen users have connected their apps and mapped their digital lives. Your plugin turns that context into action — expense tools, productivity agents, financial advisors, and more.

Get started Talk to us