Nodes API

Manage nodes in the Paradigm identity graph.

Base URL

https://api.ofself.ai/api/v1

Authentication

All requests require either:

• JWT Token: Authorization: Bearer <token>
• API Key: X-API-Key: <your-key> + X-User-ID: <user-id>

Endpoints

POST /nodes

POST Create a new node.

curl -X POST "https://api.ofself.ai/api/v1/nodes" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "First day teaching my own class",
    "value": "This was the moment everything clicked...",
    "node_type": "EXPERIENCE",
    "meaning_level": "IDENTITY",
    "graph_view": "identity",
    "importance_score": 0.98,
    "metadata": {
      "properties": {
        "when": {
          "type": "instance",
          "status": "done",
          "start": "2020-09-15"
        },
        "where": "University lecture hall",
        "significance": "Realized teaching was my calling"
      }
    },
    "agent_metadata": {
      "agent_id": "agent_001",
      "agent_name": "Memory Extraction Agent v2.1",
      "agent_type": "experience_extractor",
      "confidence_score": 0.92
    },
    "last_modified_by_agent_id": "agent_001",
    "tags": ["formative", "career"]
  }'

Request Body:

Field	Type	Required	Description
title	string	Yes	Main description/content
value	string	No	Additional notes
node_type	enum	Yes	EXPERIENCE, BELIEF, ENTITY, or GOAL
meaning_level	enum	Yes	DATA, CONTEXT, or IDENTITY
graph_view	string	No	"identity" (default)
importance_score	float	No	0.0-1.0 relevance score
metadata	object	No	Contains properties with type-specific fields
agent_metadata	object	No	Agent information
last_modified_by_agent_id	UUID	No	Agent ID for traceability
tags	array	No	Tag names (auto-created if needed)

Type-Specific Properties (in metadata.properties):

EXPERIENCE:

{
  "when": {
    "type": "instance | series",
    "status": "done | ongoing | future",
    "start": "2020-09-15",
    "end": "2020-09-16"
  },
  "where": "string",
  "significance": "string"
}

BELIEF:

{
  "category": "about_self | about_world",
  "strength_of_belief": 8,
  "status": "active | outdated"
}

ENTITY:

{
  "name": "string",
  "category": "person | place | idea | practice | community | organization"
}

GOAL:

{
  "motivation": "string",
  "time_horizon": "immediate | short_term | long_term | lifelong",
  "status": "active | paused | achieved | abandoned"
}

Agent Metadata:

{
  "agent_id": "uuid",
  "agent_name": "string",
  "agent_type": "string",
  "agent_version": "string",
  "processing_time_ms": 1850,
  "confidence_score": 0.92,
  "source_models": ["gpt-4"],
  "extraction_method": "string",
  "validation_status": "verified | pending | rejected",
  "timestamp": "2024-01-15T10:30:00Z",
  "session_id": "string",
  "contribution_details": {
    "fields_extracted": ["when", "where"],
    "verification_passed": true,
    "quality_score": 0.92
  }
}

Response: 201 Created

{
  "id": "223845bf-4397-4135-899f-c72f84289caa",
  "title": "First day teaching my own class",
  "value": "This was the moment everything clicked...",
  "node_type": "EXPERIENCE",
  "meaning_level": "IDENTITY",
  "graph_view": "identity",
  "importance_score": 0.98,
  "owner_id": "user_123",
  "metadata": {
    "properties": {
      "when": {...},
      "where": "University lecture hall",
      "significance": "Realized teaching was my calling"
    }
  },
  "agent_metadata": {
    "agent_id": "agent_001",
    "agent_name": "Memory Extraction Agent v2.1",
    "confidence_score": 0.92
  },
  "last_modified_by_agent_id": "agent_001",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

---

GET /nodes

GET List nodes with optional filters.

curl -X GET "https://api.ofself.ai/api/v1/nodes?node_type=EXPERIENCE&meaning_level=IDENTITY&limit=20" \
  -H "Authorization: Bearer your-jwt-token"

Query Parameters:

Parameter	Type	Default	Description
access	string	all	Access scope: owned, shared, or all
node_type	string	-	EXPERIENCE, BELIEF, ENTITY, or GOAL
meaning_level	string	-	DATA, CONTEXT, or IDENTITY
view	string	-	Graph view: identity or neutral
tag_id	UUID	-	Filter by tag
search	string	-	Search title/value
include_tags	boolean	false	Include associated tags
include_owner	boolean	false	Include owner info (useful for grouping shared nodes)
sort	string	updated_at	updated_at, created_at, or title
order	string	desc	asc or desc
limit	integer	20	Items to return (max 100)
offset	integer	0	Pagination offset

Response: 200 OK

{
  "nodes": [
    {
      "id": "node_1",
      "title": "First day teaching",
      "node_type": "EXPERIENCE",
      "meaning_level": "IDENTITY",
      "importance_score": 0.98,
      "metadata": {"properties": {...}},
      "agent_metadata": {...},
      "created_at": "2024-01-15T10:30:00Z",
      "tags": [{"id": "tag_1", "name": "formative"}],
      "is_shared": false,
      "owner": {"id": "user_123", "username": "alice"}
    }
  ],
  "total": 42
}

Shared With Me

To list only nodes shared to you by other users:

curl -X GET "https://api.ofself.ai/api/v1/nodes?access=shared&include_owner=true&include_tags=true&limit=50&offset=0" \
  -H "Authorization: Bearer your-jwt-token"

---

GET /nodes/:node_id

GET Get a single node with full details.

curl -X GET "https://api.ofself.ai/api/v1/nodes/223845bf-4397-4135-899f-c72f84289caa" \
  -H "Authorization: Bearer your-jwt-token"

Response: 200 OK

{
  "id": "223845bf-4397-4135-899f-c72f84289caa",
  "title": "First day teaching",
  "value": "Full content...",
  "node_type": "EXPERIENCE",
  "meaning_level": "IDENTITY",
  "owner_id": "user_123",
  "metadata": {
    "properties": {
      "when": {"type": "instance", "status": "done", "start": "2020-09-15"},
      "where": "University",
      "significance": "Realized my calling"
    }
  },
  "agent_metadata": {
    "agent_id": "agent_001",
    "agent_name": "Memory Extraction Agent",
    "confidence_score": 0.92
  },
  "last_modified_by_agent_id": "agent_001",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

---

PUT /nodes/:node_id

PUT Update a node (creates history entry).

curl -X PUT "https://api.ofself.ai/api/v1/nodes/node_abc" \
  -H "Authorization: Bearer your-jwt-token" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated title",
    "meaning_level": "IDENTITY",
    "agent_metadata": {
      "agent_id": "agent_002",
      "agent_name": "Enhancement Agent",
      "confidence_score": 0.88
    },
    "last_modified_by_agent_id": "agent_002"
  }'

Request Body: All fields are optional - only include what you want to update.

Response: 200 OK (returns updated node)

---

DELETE /nodes/:node_id

DELETE Soft delete a node.

curl -X DELETE "https://api.ofself.ai/api/v1/nodes/node_abc" \
  -H "Authorization: Bearer your-jwt-token"

Response: 204 No Content

---

Agent & History Endpoints

GET /nodes/:node_id/ledger

GET Get all agents that contributed to a node.

curl -X GET "https://api.ofself.ai/api/v1/nodes/node_abc/ledger" \
  -H "Authorization: Bearer your-jwt-token"

Response: 200 OK

{
  "node_id": "node_abc",
  "total_agents": 3,
  "agents": [
    {
      "agent_id": "agent_001",
      "agent_name": "Memory Extraction Agent v2.1",
      "agent_type": "experience_extractor",
      "contribution_count": 1,
      "last_contribution": "2024-01-15T10:30:00Z"
    },
    {
      "agent_id": "agent_002",
      "agent_name": "Enhancement Agent v2.5",
      "agent_type": "content_enhancer",
      "contribution_count": 2,
      "last_contribution": "2024-01-16T14:20:00Z"
    }
  ]
}

---

GET /nodes/:node_id/history

GET Get version history for a node.

curl -X GET "https://api.ofself.ai/api/v1/nodes/node_abc/history?limit=10&include_snapshots=false" \
  -H "Authorization: Bearer your-jwt-token"

Query Parameters:

Parameter	Type	Default	Description
limit	integer	100	Number of versions to return
offset	integer	0	Pagination offset
include_snapshots	boolean	false	Include full node snapshots
start_date	datetime	-	Filter from date
end_date	datetime	-	Filter to date

Response: 200 OK

{
  "node_id": "node_abc",
  "history": [
    {
      "version": 3,
      "changed_at": "2024-01-17T09:15:00Z",
      "change_type": "update",
      "changed_by_type": "agent",
      "changed_by_agent_id": "agent_003",
      "agent_metadata": {
        "agent_name": "QA Agent",
        "confidence_score": 0.95,
        "validation_status": "verified"
      },
      "changed_fields": {
        "metadata": {...}
      }
    },
    {
      "version": 2,
      "changed_at": "2024-01-16T14:20:00Z",
      "change_type": "update",
      "changed_by_type": "agent",
      "changed_by_agent_id": "agent_002",
      "agent_metadata": {
        "agent_name": "Enhancement Agent",
        "confidence_score": 0.88
      },
      "changed_fields": {
        "title": "Enhanced title",
        "meaning_level": "IDENTITY"
      }
    }
  ],
  "total": 3,
  "limit": 10,
  "offset": 0
}

---

GET /nodes/:node_id/contributions

GET Get detailed contributions to a node.

curl -X GET "https://api.ofself.ai/api/v1/nodes/node_abc/contributions" \
  -H "Authorization: Bearer your-jwt-token"

Response: 200 OK

{
  "node_id": "node_abc",
  "contributions": [
    {
      "id": "contrib_001",
      "contributor_id": "agent_001",
      "field_name": "title",
      "contributed_value": "First day teaching",
      "confidence_score": 0.92,
      "contributed_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "contrib_002",
      "contributor_id": "agent_002",
      "field_name": "metadata.properties.significance",
      "contributed_value": "Realized my calling",
      "confidence_score": 0.88,
      "contributed_at": "2024-01-16T14:20:00Z"
    }
  ],
  "total": 2
}

---

Error Responses

All endpoints return standard error responses:

400 Bad Request

{
  "error": {
    "code": "INVALID_INPUT",
    "message": "node_type must be one of: EXPERIENCE, BELIEF, ENTITY, GOAL"
  }
}

401 Unauthorized

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid authentication"
  }
}

404 Not Found

{
  "error": {
    "code": "NODE_NOT_FOUND",
    "message": "Node not found or access denied"
  }
}

422 Unprocessable Entity

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Entity nodes require name and category in properties"
  }
}

---

Rate Limits

• Default: 1000 requests/hour per user
• Burst: 50 requests/minute

Headers included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1705323600

---

Examples

Create an EXPERIENCE Node

import requests

response = requests.post(
    "https://api.ofself.ai/api/v1/nodes",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json"
    },
    json={
        "title": "First day teaching my own class",
        "node_type": "EXPERIENCE",
        "meaning_level": "IDENTITY",
        "metadata": {
            "properties": {
                "when": {
                    "type": "instance",
                    "status": "done",
                    "start": "2020-09-15"
                },
                "significance": "Realized teaching was my calling"
            }
        },
        "agent_metadata": {
            "agent_id": "agent_001",
            "agent_name": "Memory Extractor",
            "confidence_score": 0.92
        },
        "last_modified_by_agent_id": "agent_001"
    }
)

node = response.json()
print(f"Created node: {node['id']}")

Multi-Agent Collaboration

# Agent 1: Initial extraction
node = create_node({
    "title": "Started teaching",
    "node_type": "EXPERIENCE",
    "meaning_level": "CONTEXT",
    "agent_metadata": {
        "agent_id": "agent_001",
        "agent_name": "Extractor",
        "confidence_score": 0.75
    },
    "last_modified_by_agent_id": "agent_001"
})

# Agent 2: Enhancement
update_node(node['id'], {
    "meaning_level": "IDENTITY",
    "metadata": {
        "properties": {
            "significance": "Defining moment"
        }
    },
    "agent_metadata": {
        "agent_id": "agent_002",
        "agent_name": "Enhancer",
        "confidence_score": 0.88
    },
    "last_modified_by_agent_id": "agent_002"
})

# View all contributors
ledger = get_ledger(node['id'])
print(f"Total agents: {ledger['total_agents']}")

Query by Type and Level

# Get all identity-level experiences
experiences = requests.get(
    "https://api.ofself.ai/api/v1/nodes",
    headers={"Authorization": f"Bearer {token}"},
    params={
        "node_type": "EXPERIENCE",
        "meaning_level": "IDENTITY"
    }
).json()

for node in experiences['nodes']:
    print(f"{node['title']}")
    print(f"  Confidence: {node['agent_metadata']['confidence_score']}")

---

Next Steps

• Agent Infrastructure - Multi-agent collaboration
• Node History - Version tracking
• Relationships - Connect nodes
• Tags - Organize nodes