API Documentation

Vault API Documentation

RESTful API reference for the Hybrid Vault system

🚀 Interactive API Documentation

Try out API endpoints directly in your browser with automatic request/response examples

⚡ Quick Reference

Base URL:
http://lims-api-1:8000/api/v1
Authentication:
Authorization: Bearer <token>
Content Type:
application/json
OpenAPI Schema:
http://vaulttest.c-path.be/openapi.json

HTTP Methods

GET Retrieve resources

POST Create resources or complex queries

PUT Update resources

DELETE Remove resources

📦 Nodes API

/api/v1/nodes

GET /nodes

List all accessible nodes with pagination and filtering

POST /nodes/

Create a new node

Example Request Body

{
  "node_type": "Task",
  "content": {
    "title": "Implement new feature",
    "description": "Add user authentication",
    "status": "pending",
    "priority": "high"
  },
  "is_key_holder": false
}

GET /nodes/{uuid}

Retrieve specific node with all relationships

PUT /nodes/{uuid}/content

Update node mutable content fields

DELETE /nodes/{uuid}

Delete node and all its relationships

🔗 Relationships API

/api/v1/relationships

POST /relationships/

Create a relationship between two nodes

Example Request Body

{
  "source_uuid": "550e8400-...",
  "target_uuid": "660e8400-...",
  "relationship_type": "ASSIGNED_TO",
  "content": {
    "assigned_date": "2025-12-08",
    "role": "primary",
    "priority": "high"
  }
}

GET /relationships/?source_uuid={uuid}

Get all relationships for a node (optionally filter by type)

PUT /relationships/{uuid}/content

Update relationship metadata

DELETE /relationships/{target_uuid}

Delete specific relationship (requires source_uuid and relationship_type params)

⚙️ Schema API

/api/v1/schema

GET /schema/

Get complete vault schema (all node and relationship types)

GET /schema/node-types

List all defined node types

GET /schema/node-types/{type}

Get schema definition for specific node type

PUT /schema/node-types/{type}

Create or update node type schema

POST /schema/validate/node

Validate node data against schema

POST /schema/allowed-relationships

Get allowed relationship types for a node type

🔍 Search API

/api/v1/search

POST /search

Advanced search with filters and access control

Example Request Body

{
  "query": "urgent tasks",
  "node_type": "Task",
  "filters": {
    "status": "pending",
    "priority": "high"
  },
  "limit": 50,
  "offset": 0
}

📋 Audit API

/api/v1/audit

GET /audit/entity/{uuid}

Get complete audit trail for an entity (node or relationship)

GET /audit/user/{uuid}

Get all audit events for a specific user

POST /audit/search

Advanced audit search with multiple filters (event type, date range, user)

GET /audit/statistics?time_range=7d

Get aggregate audit statistics (event counts, top users, top entities)

GET /audit/export/user/{uuid}

GDPR-compliant export of all user data

DELETE /audit/anonymize/user/{uuid}

Anonymize user PII from audit events (GDPR right to be forgotten)

📊 HTTP Response Codes

Code	Meaning	Description
200	OK	Request successful
201	Created	Resource created successfully
204	No Content	Deletion successful (no response body)
400	Bad Request	Invalid request data or schema validation failed
401	Unauthorized	Missing or invalid authentication token
403	Forbidden	No access permission (insufficient access keys)
404	Not Found	Resource does not exist
500	Internal Server Error	Unexpected server error

💻 Code Examples

Python (requests)

import requests

BASE_URL = "http://lims-api-1:8000/api/v1"
TOKEN = "your-auth-token"

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json"
}

# Create a node
response = requests.post(
    f"{BASE_URL}/nodes/",
    json={
        "node_type": "Task",
        "content": {
            "title": "Implement feature X",
            "status": "pending"
        }
    },
    headers=headers
)

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

# Get node
response = requests.get(
    f"{BASE_URL}/nodes/{node['uuid']}",
    headers=headers
)
print(response.json())

JavaScript (fetch)

const BASE_URL = 'http://lims-api-1:8000/api/v1';
const TOKEN = 'your-auth-token';

const headers = {
    'Authorization': `Bearer ${TOKEN}`,
    'Content-Type': 'application/json'
};

// Create a node
const response = await fetch(`${BASE_URL}/nodes/`, {
    method: 'POST',
    headers: headers,
    body: JSON.stringify({
        node_type: 'Task',
        content: {
            title: 'Implement feature X',
            status: 'pending'
        }
    })
});

const node = await response.json();
console.log('Created node:', node.uuid);

// Get node
const getResponse = await fetch(`${BASE_URL}/nodes/${node.uuid}`, {
    headers: headers
});
console.log(await getResponse.json());

cURL

# Create a node
curl -X POST "http://lims-api-1:8000/api/v1/nodes/" \
  -H "Authorization: Bearer your-auth-token" \
  -H "Content-Type: application/json" \
  -d '{
    "node_type": "Task",
    "content": {
      "title": "Implement feature X",
      "status": "pending"
    }
  }'

# Get a node
curl -X GET "http://lims-api-1:8000/api/v1/nodes/{uuid}" \
  -H "Authorization: Bearer your-auth-token"

# Search nodes
curl -X POST "http://lims-api-1:8000/api/v1/search" \
  -H "Authorization: Bearer your-auth-token" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "urgent",
    "node_type": "Task",
    "filters": {"status": "pending"}
  }'

📚 Additional Resources

🚀 Interactive Swagger UI
Try API endpoints in your browser 📖 ReDoc Documentation
Clean, searchable API reference

📄 Architecture Documentation
See VAULT_ARCHITECTURE.md for detailed system design

❓ Help & User Guide
Learn how to use the web interface