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

Automation endpoints use the same hosted-service auth model as the rest of the API:

Authorization: Bearer <token>
x-derive-session-id: <session_id> when the rule reads or writes private tenant data
x-derive-key: <derive_key_hex> alongside the derive session header

The docs-site playground handles these headers automatically after Privy login. For custom clients, obtain the bearer token through the wallet challenge/verify flow and derive the session key through the sign-to-derive flow described in Wallet Authentication.

Example:

curl -X GET https://api.knowledgedataflow.org/api/v1/automation/rules \
  -H "Authorization: Bearer $KFDB_TOKEN" \
  -H "x-derive-session-id: $KFDB_DERIVE_SESSION_ID" \
  -H "x-derive-key: $KFDB_DERIVE_KEY"

Legacy Compatibility

Some older tooling still accepts X-Wallet-Address. Treat that as a compatibility path for internal or transitional clients, not as the recommended automation auth contract.

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-3-flash-preview",
  "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-3-flash-preview",
    "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-3-flash-preview`)
`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-3-flash-preview",
      "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-3-flash-preview",
      "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-3-flash-preview",
    "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 wallet address.

{
  "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 TOKEN = process.env.KFDB_TOKEN;
const DERIVE_SESSION_ID = process.env.KFDB_DERIVE_SESSION_ID;
const DERIVE_KEY = process.env.KFDB_DERIVE_KEY;

const headers = {
  'Content-Type': 'application/json',
  Authorization: `Bearer ${TOKEN}`,
  'x-derive-session-id': DERIVE_SESSION_ID,
  'x-derive-key': DERIVE_KEY,
};

// Create a rule
async function createRule() {
  const response = await fetch(`${API_URL}/automation/rules`, {
    method: 'POST',
    headers,
    body: JSON.stringify({
      name: 'Auto-summarize Documents',
      trigger_type: 'node_created',
      operation_type: 'summarize',
      llm_provider: 'google',
      llm_model: 'gemini-3-flash-preview',
      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
  });

  return await response.json();
}

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

  return await response.json();
}

Python (requests)

import requests

API_URL = 'https://api.knowledgedataflow.org/api/v1'
TOKEN = 'YOUR_BEARER_TOKEN'
DERIVE_SESSION_ID = 'YOUR_DERIVE_SESSION_ID'
DERIVE_KEY = 'YOUR_DERIVE_KEY_HEX'
HEADERS = {
    'Content-Type': 'application/json',
    'Authorization': f'Bearer {TOKEN}',
    'x-derive-session-id': DERIVE_SESSION_ID,
    'x-derive-key': DERIVE_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-3-flash-preview',
        '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 TOKEN: &str = "YOUR_BEARER_TOKEN";
const DERIVE_SESSION_ID: &str = "YOUR_DERIVE_SESSION_ID";
const DERIVE_KEY: &str = "YOUR_DERIVE_KEY_HEX";

#[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-3-flash-preview",
        "input_property": "content",
        "output_strategy": "update_property",
        "output_property": "summary",
        "is_active": true
    });

    let response = client
        .post(format!("{}/automation/rules", API_URL))
        .bearer_auth(TOKEN)
        .header("x-derive-session-id", DERIVE_SESSION_ID)
        .header("x-derive-key", DERIVE_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 $KFDB_TOKEN" \
  -H "x-derive-session-id: $KFDB_DERIVE_SESSION_ID" \
  -H "x-derive-key: $KFDB_DERIVE_KEY" \
  -d '{
    "name": "Auto-summarize Documents",
    "trigger_type": "node_created",
    "operation_type": "summarize",
    "llm_provider": "google",
    "llm_model": "gemini-3-flash-preview",
    "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 $KFDB_TOKEN" \
  -H "x-derive-session-id: $KFDB_DERIVE_SESSION_ID" \
  -H "x-derive-key: $KFDB_DERIVE_KEY"

# Get execution logs
curl "https://api.knowledgedataflow.org/api/v1/automation/executions?limit=50" \
  -H "Authorization: Bearer $KFDB_TOKEN" \
  -H "x-derive-session-id: $KFDB_DERIVE_SESSION_ID" \
  -H "x-derive-key: $KFDB_DERIVE_KEY"

# Delete a rule
curl -X DELETE https://api.knowledgedataflow.org/api/v1/automation/rules/RULE_ID \
  -H "Authorization: Bearer $KFDB_TOKEN" \
  -H "x-derive-session-id: $KFDB_DERIVE_SESSION_ID" \
  -H "x-derive-key: $KFDB_DERIVE_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​

Legacy Compatibility​

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

Legacy Compatibility

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