Automation API Reference

Complete HTTP API documentation for managing automation rules and monitoring executions.

Base URL

Production: https://api.knowledgedataflow.org/api/v1
Local:      http://localhost:8080/api/v1

Authentication

All automation endpoints require authentication with an API key:

Authorization: Bearer YOUR_API_KEY

Example:

curl -X GET https://api.knowledgedataflow.org/api/v1/automation/rules \
  -H "Authorization: Bearer YOUR_API_KEY"

Endpoints

Create Rule

Create a new automation rule.

Endpoint: POST /automation/rules

Request Body:

{
  "name": "Auto-summarize Documents",
  "description": "Generate summaries for new documents",
  "trigger_type": "node_created",
  "trigger_filters": {
    "labels": ["Document", "Article"],
    "has_property": "content"
  },
  "operation_type": "summarize",
  "llm_provider": "google",
  "llm_model": "gemini-2.5-flash-preview-09-2025",
  "prompt_template": "Summarize the following text in 2-3 sentences:\n\n{content}",
  "input_property": "content",
  "output_strategy": "update_property",
  "output_property": "summary",
  "is_active": true,
  "max_tokens": 200,
  "temperature": 0.7
}

Response: 201 Created

{
  "rule": {
    "rule_id": "550e8400-e29b-41d4-a716-446655440000",
    "tenant_id": "default",
    "name": "Auto-summarize Documents",
    "description": "Generate summaries for new documents",
    "trigger_type": "node_created",
    "trigger_filters": {
      "labels": ["Document", "Article"],
      "has_property": "content"
    },
    "operation_type": "summarize",
    "llm_provider": "google",
    "llm_model": "gemini-2.5-flash-preview-09-2025",
    "prompt_template": "Summarize the following text in 2-3 sentences:\n\n{content}",
    "input_property": "content",
    "output_strategy": "update_property",
    "output_property": "summary",
    "is_active": true,
    "max_tokens": 200,
    "temperature": 0.7,
    "created_at": "2025-11-15T00:00:00Z",
    "updated_at": "2025-11-15T00:00:00Z",
    "created_by": "api"
  }
}

Field Reference:

Field	Type	Required	Description
`name`	string	✅ Yes	Human-readable rule name
`description`	string	No	Detailed description of the rule
`trigger_type`	enum	✅ Yes	`node_created`, `node_updated`, `node_deleted`, `edge_created`, `edge_deleted`
`trigger_filters`	object	No	Filters to match specific events
`trigger_filters.labels`	string[]	No	Match nodes/edges with these labels
`trigger_filters.has_property`	string	No	Match when this property exists
`operation_type`	enum	✅ Yes	`summarize`, `generate_embedding`, `extract_entities`, `classify`, `custom`
`llm_provider`	enum	✅ Yes	`google`, `openai`, `anthropic`
`llm_model`	string	✅ Yes	Model identifier (e.g., `gemini-2.5-flash-preview-09-2025`)
`prompt_template`	string	No	Template with `{property}` placeholders
`input_property`	string	✅ Yes	Node property to use as LLM input
`output_strategy`	enum	✅ Yes	`update_property`, `create_node`, `create_edge`
`output_property`	string	Conditional	Required if `output_strategy` is `update_property`
`output_node_label`	string	Conditional	Required if `output_strategy` is `create_node`
`is_active`	boolean	✅ Yes	Whether rule is active
`max_tokens`	integer	No	Maximum tokens for LLM response
`temperature`	number	No	LLM temperature (0.0-1.0)

List Rules

Get all automation rules.

Endpoint: GET /automation/rules

Response: 200 OK

{
  "total": 2,
  "rules": [
    {
      "rule_id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Auto-summarize Documents",
      "description": "Generate summaries for new documents",
      "trigger_type": "node_created",
      "operation_type": "summarize",
      "llm_provider": "google",
      "llm_model": "gemini-2.5-flash-preview-09-2025",
      "is_active": true,
      "created_at": "2025-11-15T00:00:00Z",
      "updated_at": "2025-11-15T00:00:00Z"
    },
    {
      "rule_id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "Auto-embed Code Files",
      "description": "Generate embeddings for code files",
      "trigger_type": "node_created",
      "operation_type": "generate_embedding",
      "llm_provider": "google",
      "llm_model": "gemini-2.5-flash-preview-09-2025",
      "is_active": true,
      "created_at": "2025-11-15T00:01:00Z",
      "updated_at": "2025-11-15T00:01:00Z"
    }
  ]
}

Get Rule

Get a specific automation rule by ID.

Endpoint: GET /automation/rules/:rule_id

Response: 200 OK

{
  "rule": {
    "rule_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Auto-summarize Documents",
    "description": "Generate summaries for new documents",
    "trigger_type": "node_created",
    "trigger_filters": {
      "labels": ["Document"],
      "has_property": "content"
    },
    "operation_type": "summarize",
    "llm_provider": "google",
    "llm_model": "gemini-2.5-flash-preview-09-2025",
    "is_active": true,
    "created_at": "2025-11-15T00:00:00Z",
    "updated_at": "2025-11-15T00:00:00Z"
  }
}

Error Response: 404 Not Found

{
  "status": 404,
  "message": "Rule not found: 550e8400-e29b-41d4-a716-446655440000"
}

Update Rule

Update an existing automation rule.

Endpoint: PUT /automation/rules/:rule_id

Request Body: (all fields optional)

{
  "name": "Updated Rule Name",
  "description": "Updated description",
  "is_active": false,
  "max_tokens": 300,
  "temperature": 0.5
}

Response: 200 OK

{
  "rule": {
    "rule_id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Updated Rule Name",
    "description": "Updated description",
    "is_active": false,
    "updated_at": "2025-11-15T00:10:00Z"
  }
}

Delete Rule

Delete an automation rule.

Endpoint: DELETE /automation/rules/:rule_id

Response: 200 OK

{
  "rule_id": "550e8400-e29b-41d4-a716-446655440000",
  "message": "Rule deleted successfully"
}

Get Execution Logs

Get execution logs for automation rules.

Endpoint: GET /automation/executions

Query Parameters:

Parameter	Type	Description
`rule_id`	UUID	Filter by specific rule
`limit`	integer	Max results to return (default: 100)

Example:

GET /automation/executions?rule_id=550e8400-e29b-41d4-a716-446655440000&limit=50

Response: 200 OK

{
  "total": 23,
  "logs": [
    {
      "execution_id": "770e8400-e29b-41d4-a716-446655440002",
      "rule_id": "550e8400-e29b-41d4-a716-446655440000",
      "tenant_id": "default",
      "event_type": "node_created",
      "node_id": "880e8400-e29b-41d4-a716-446655440003",
      "status": "success",
      "input_text": "Long document content...",
      "output_value": "This is a concise summary of the document.",
      "execution_time_ms": 342,
      "tokens_used": 156,
      "cost_usd": 0.0012,
      "timestamp": "2025-11-15T00:05:00Z"
    },
    {
      "execution_id": "770e8400-e29b-41d4-a716-446655440003",
      "rule_id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "failed",
      "error_message": "API rate limit exceeded",
      "execution_time_ms": 52,
      "timestamp": "2025-11-15T00:04:30Z"
    }
  ]
}

Execution Status:

Status	Description
`pending`	Queued but not yet executed
`success`	Completed successfully
`failed`	Failed with error

Get Execution

Get details for a specific execution.

Endpoint: GET /automation/executions/:execution_id

Response: 200 OK

{
  "execution_id": "770e8400-e29b-41d4-a716-446655440002",
  "log": {
    "execution_id": "770e8400-e29b-41d4-a716-446655440002",
    "rule_id": "550e8400-e29b-41d4-a716-446655440000",
    "event_type": "node_created",
    "node_id": "880e8400-e29b-41d4-a716-446655440003",
    "status": "success",
    "input_text": "Document content here...",
    "output_value": "Generated summary here...",
    "execution_time_ms": 342,
    "tokens_used": 156,
    "cost_usd": 0.0012,
    "timestamp": "2025-11-15T00:05:00Z"
  }
}

Error Responses

All endpoints may return these error responses:

400 Bad Request

Invalid request data (e.g., missing required fields, invalid UUIDs).

{
  "status": 400,
  "message": "Invalid rule_id: not a valid UUID"
}

401 Unauthorized

Missing or invalid API key.

{
  "status": 401,
  "message": "Authentication required"
}

404 Not Found

Resource not found.

{
  "status": 404,
  "message": "Rule not found: 550e8400-e29b-41d4-a716-446655440000"
}

500 Internal Server Error

Server-side error.

{
  "status": 500,
  "message": "Internal server error"
}

Code Examples

JavaScript (fetch)

const API_URL = 'https://api.knowledgedataflow.org/api/v1';
const API_KEY = 'YOUR_API_KEY';

// Create a rule
async function createRule() {
  const response = await fetch(`${API_URL}/automation/rules`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${API_KEY}`
    },
    body: JSON.stringify({
      name: 'Auto-summarize Documents',
      trigger_type: 'node_created',
      operation_type: 'summarize',
      llm_provider: 'google',
      llm_model: 'gemini-2.5-flash-preview-09-2025',
      input_property: 'content',
      output_strategy: 'update_property',
      output_property: 'summary',
      is_active: true
    })
  });

  return await response.json();
}

// List rules
async function listRules() {
  const response = await fetch(`${API_URL}/automation/rules`, {
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  });

  return await response.json();
}

// Delete a rule
async function deleteRule(ruleId) {
  const response = await fetch(`${API_URL}/automation/rules/${ruleId}`, {
    method: 'DELETE',
    headers: {
      'Authorization': `Bearer ${API_KEY}`
    }
  });

  return await response.json();
}

Python (requests)

import requests

API_URL = 'https://api.knowledgedataflow.org/api/v1'
API_KEY = 'YOUR_API_KEY'
HEADERS = {
    'Content-Type': 'application/json',
    'Authorization': f'Bearer {API_KEY}'
}

# Create a rule
def create_rule():
    rule_data = {
        'name': 'Auto-summarize Documents',
        'trigger_type': 'node_created',
        'operation_type': 'summarize',
        'llm_provider': 'google',
        'llm_model': 'gemini-2.5-flash-preview-09-2025',
        'input_property': 'content',
        'output_strategy': 'update_property',
        'output_property': 'summary',
        'is_active': True
    }

    response = requests.post(
        f'{API_URL}/automation/rules',
        json=rule_data,
        headers=HEADERS
    )

    return response.json()

# List rules
def list_rules():
    response = requests.get(
        f'{API_URL}/automation/rules',
        headers=HEADERS
    )

    return response.json()

# Get execution logs
def get_executions(rule_id=None, limit=100):
    params = {'limit': limit}
    if rule_id:
        params['rule_id'] = rule_id

    response = requests.get(
        f'{API_URL}/automation/executions',
        params=params,
        headers=HEADERS
    )

    return response.json()

Rust (reqwest)

use reqwest;
use serde_json::json;

const API_URL: &str = "https://api.knowledgedataflow.org/api/v1";
const API_KEY: &str = "YOUR_API_KEY";

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = reqwest::Client::new();

    // Create a rule
    let rule = json!({
        "name": "Auto-summarize Documents",
        "trigger_type": "node_created",
        "operation_type": "summarize",
        "llm_provider": "google",
        "llm_model": "gemini-2.5-flash-preview-09-2025",
        "input_property": "content",
        "output_strategy": "update_property",
        "output_property": "summary",
        "is_active": true
    });

    let response = client
        .post(format!("{}/automation/rules", API_URL))
        .header("Authorization", format!("Bearer {}", API_KEY))
        .json(&rule)
        .send()
        .await?;

    println!("Created rule: {:?}", response.json::<serde_json::Value>().await?);

    Ok(())
}

cURL

# Create a rule
curl -X POST https://api.knowledgedataflow.org/api/v1/automation/rules \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "name": "Auto-summarize Documents",
    "trigger_type": "node_created",
    "operation_type": "summarize",
    "llm_provider": "google",
    "llm_model": "gemini-2.5-flash-preview-09-2025",
    "input_property": "content",
    "output_strategy": "update_property",
    "output_property": "summary",
    "is_active": true
  }'

# List all rules
curl https://api.knowledgedataflow.org/api/v1/automation/rules \
  -H "Authorization: Bearer YOUR_API_KEY"

# Get execution logs
curl "https://api.knowledgedataflow.org/api/v1/automation/executions?limit=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Delete a rule
curl -X DELETE https://api.knowledgedataflow.org/api/v1/automation/rules/RULE_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

Rate Limits

Tier	Rules	Executions/min	Executions/day
Free	10	60	1,000
Pro	100	600	10,000
Enterprise	Unlimited	Unlimited	Unlimited

Next Steps

📖 Read the Automation Overview
🎮 Try the Interactive Playground

Base URL​

Authentication​

Endpoints​

Create Rule​

List Rules​

Get Rule​

Update Rule​

Delete Rule​

Get Execution Logs​

Get Execution​

Error Responses​

400 Bad Request​

401 Unauthorized​

404 Not Found​

500 Internal Server Error​

Code Examples​

JavaScript (fetch)​

Python (requests)​

Rust (reqwest)​

cURL​

Rate Limits​

Next Steps​

Base URL

Authentication

Endpoints

Create Rule

List Rules

Get Rule

Update Rule

Delete Rule

Get Execution Logs

Get Execution

Error Responses

400 Bad Request

401 Unauthorized

404 Not Found

500 Internal Server Error

Code Examples

JavaScript (fetch)

Python (requests)

Rust (reqwest)

cURL

Rate Limits

Next Steps