DAG Workflows API

13 Endpoints for Workflow Orchestration (Team+)

Overview

The DAG (Directed Acyclic Graph) Workflows API enables programmatic creation and management of document processing workflows. Build complex multi-step automations with AI processing, human approval, and external integrations.

Base URL 

https://api.archivus.app/api/v1/dag

Authentication

All DAG endpoints require authentication and Team+ tier subscription.

curl -H "X-API-Key: ak_live_YOUR_API_KEY" \
     https://api.archivus.app/api/v1/dag/workflows

Workflow Management

List Workflows 

GET /dag/workflows

Query Parameters:

Parameter Type Description
page integer Page number (default: 1)
page_size integer Items per page (default: 20, max: 100)
status string Filter: active, paused, draft

Response:

{
  "data": [
    {
      "id": "wf_abc123",
      "name": "Contract Review Workflow",
      "description": "AI analysis with human approval",
      "status": "active",
      "trigger_type": "document_upload",
      "node_count": 5,
      "created_at": "2026-01-15T10:00:00Z",
      "updated_at": "2026-01-18T09:30:00Z",
      "last_execution": "2026-01-18T09:15:00Z"
    }
  ],
  "total": 12,
  "page": 1,
  "page_size": 20
}

Create Workflow 

POST /dag/workflows
Content-Type: application/json

Request Body:

{
  "name": "Invoice Processing Workflow",
  "description": "Automatically process and route invoices",
  "trigger": {
    "type": "document_upload",
    "conditions": {
      "folder_path": "/invoices/*",
      "file_types": ["pdf"]
    }
  },
  "nodes": [
    {
      "id": "extract",
      "type": "ai_extract",
      "config": {
        "document_id": "",
        "extraction_schema": {
          "vendor_name": "string",
          "invoice_number": "string",
          "amount": "number",
          "due_date": "date"
        }
      }
    },
    {
      "id": "route",
      "type": "condition",
      "config": {
        "condition": " > 10000"
      },
      "depends_on": ["extract"]
    },
    {
      "id": "high_value_approval",
      "type": "human_approval",
      "config": {
        "assignee_type": "role",
        "assignee_value": "finance_manager",
        "title": "High-Value Invoice Approval",
        "timeout_hours": 24
      },
      "depends_on": ["route"],
      "run_if": " == true"
    }
  ],
  "error_handling": {
    "on_failure": "pause",
    "notify_on_failure": ["admin@example.com"]
  }
}

Response:

{
  "id": "wf_def456",
  "name": "Invoice Processing Workflow",
  "status": "draft",
  "created_at": "2026-01-18T10:30:00Z"
}

Get Workflow 

GET /dag/workflows/{workflow_id}

Response:

{
  "id": "wf_abc123",
  "name": "Contract Review Workflow",
  "description": "AI analysis with human approval",
  "status": "active",
  "trigger": {
    "type": "document_upload",
    "conditions": {
      "folder_path": "/contracts/*",
      "file_types": ["pdf", "docx"]
    }
  },
  "nodes": [
    {
      "id": "analyze",
      "type": "ai_analyze",
      "config": {
        "document_id": "",
        "analysis_type": "contract"
      }
    }
  ],
  "error_handling": {
    "on_failure": "pause"
  },
  "statistics": {
    "total_executions": 156,
    "successful": 148,
    "failed": 3,
    "in_progress": 5,
    "avg_duration_seconds": 45
  },
  "created_at": "2026-01-15T10:00:00Z",
  "updated_at": "2026-01-18T09:30:00Z"
}

Update Workflow 

PUT /dag/workflows/{workflow_id}
Content-Type: application/json

Request Body:

{
  "name": "Contract Review Workflow v2",
  "description": "Updated workflow with additional checks",
  "nodes": [...]
}

Delete Workflow 

DELETE /dag/workflows/{workflow_id}

Note: Cannot delete workflows with active executions.

Validate Workflow 

POST /dag/workflows/{workflow_id}/validate

Response:

{
  "valid": true,
  "warnings": [
    "Node 'approval_1' has no timeout configured"
  ],
  "errors": []
}

Or with errors:

{
  "valid": false,
  "errors": [
    "Circular dependency detected: node_a -> node_b -> node_a",
    "Unknown node type: 'custom_invalid'"
  ]
}

Execution Management

Execute Workflow 

POST /dag/workflows/{workflow_id}/execute
Content-Type: application/json

Request Body:

{
  "trigger_data": {
    "document_id": "doc_xyz789",
    "document_name": "Contract-2026.pdf",
    "custom_param": "value"
  },
  "priority": "high"
}

Response:

{
  "execution_id": "exec_ghi789",
  "workflow_id": "wf_abc123",
  "status": "running",
  "started_at": "2026-01-18T10:35:00Z"
}

List Executions 

GET /dag/executions

Query Parameters:

Parameter Type Description
workflow_id string Filter by workflow
status string Filter: running, paused, completed, failed, cancelled
page integer Page number
page_size integer Items per page

Response:

{
  "data": [
    {
      "id": "exec_ghi789",
      "workflow_id": "wf_abc123",
      "workflow_name": "Contract Review Workflow",
      "status": "running",
      "current_node": "analyze",
      "progress_percent": 40,
      "started_at": "2026-01-18T10:35:00Z",
      "trigger_data": {
        "document_id": "doc_xyz789"
      }
    }
  ],
  "total": 156,
  "page": 1
}

Get Execution Status 

GET /dag/executions/{execution_id}

Response:

{
  "id": "exec_ghi789",
  "workflow_id": "wf_abc123",
  "status": "paused",
  "paused_reason": "awaiting_approval",
  "current_node": "approval_1",
  "nodes_completed": ["analyze", "route"],
  "nodes_pending": ["approval_1", "notify"],
  "progress_percent": 50,
  "started_at": "2026-01-18T10:35:00Z",
  "node_results": {
    "analyze": {
      "status": "completed",
      "output": {
        "risk_score": 8,
        "key_terms": ["30-day termination", "unlimited liability"]
      },
      "completed_at": "2026-01-18T10:35:15Z"
    },
    "route": {
      "status": "completed",
      "output": true,
      "completed_at": "2026-01-18T10:35:16Z"
    }
  }
}

Pause Execution 

POST /dag/executions/{execution_id}/pause

Response:

{
  "execution_id": "exec_ghi789",
  "status": "paused",
  "paused_at": "2026-01-18T10:40:00Z",
  "can_resume": true
}

Resume Execution 

POST /dag/executions/{execution_id}/resume
Content-Type: application/json

Request Body (optional):

{
  "modified_data": {
    "override_value": "new_value"
  }
}

Cancel Execution 

POST /dag/executions/{execution_id}/cancel
Content-Type: application/json

Request Body (optional):

{
  "reason": "User requested cancellation"
}

Human Task Management

List Pending Tasks 

GET /dag/tasks

Query Parameters:

Parameter Type Description
assignee string Filter by assignee user ID
role string Filter by assignee role
status string Filter: pending, completed, expired
page integer Page number

Response:

{
  "data": [
    {
      "id": "task_jkl012",
      "execution_id": "exec_ghi789",
      "workflow_name": "Contract Review Workflow",
      "node_id": "approval_1",
      "task_type": "approval",
      "title": "High-Risk Contract Review",
      "description": "Please review the AI-generated analysis",
      "context": {
        "risk_score": 8,
        "document_link": "/documents/doc_xyz789"
      },
      "assignee_type": "role",
      "assignee_value": "legal_director",
      "created_at": "2026-01-18T10:35:16Z",
      "due_at": "2026-01-19T10:35:16Z",
      "escalation_at": "2026-01-18T22:35:16Z"
    }
  ],
  "total": 5
}

Get Task Details 

GET /dag/tasks/{task_id}

Complete Task 

POST /dag/tasks/{task_id}/complete
Content-Type: application/json

Request Body:

{
  "decision": "approved",
  "comments": "Reviewed and approved with minor concerns noted",
  "modified_data": {
    "additional_review_notes": "Schedule follow-up in 30 days"
  }
}

Decision Values:

  • approved - Approve and continue
  • rejected - Reject and stop/branch
  • modified - Approve with modifications

Node Types Reference

AI Nodes

Type Description Config
ai_summarize Generate summary document_id, summary_type, max_length
ai_analyze Deep analysis document_id, analysis_type
ai_extract Extract entities document_id, extraction_schema
ai_classify Categorize document_id, categories
ai_qa Answer questions document_id, questions
ai_custom Custom prompt document_id, prompt, output_schema

Human Nodes

Type Description Config
human_approval Approve/Reject assignee_type, assignee_value, timeout_hours
human_review Review with edits assignee_type, editable_fields
human_assignment Route to user assignee_type, selection_criteria

Control Nodes

Type Description
condition If/else branching
switch Multi-way branching
parallel Parallel execution
join Wait for parallel branches
loop Iterate over collection
delay Wait duration
schedule Wait until time
transform Transform data
filter Filter collection
aggregate Combine results
set_variable Set workflow variable
http_request HTTP call
notification Send notification
end End workflow

Integration Node

Type Description Config
mcp_tool External MCP tool server_id, tool_name, parameters

Triggers Reference

Trigger Types

Type Description Conditions
manual User-initiated None
document_upload On upload folder_path, file_types, metadata
document_update On modification folder_path, fields
schedule Cron-based cron_expression, timezone
webhook External webhook secret, validation
api API-initiated None

Error Codes

Code Description
WORKFLOW_NOT_FOUND Workflow doesn’t exist
EXECUTION_NOT_FOUND Execution doesn’t exist
TASK_NOT_FOUND Task doesn’t exist
INVALID_WORKFLOW Workflow validation failed
EXECUTION_NOT_PAUSABLE Can’t pause this execution
EXECUTION_NOT_RESUMABLE Can’t resume this execution
TASK_ALREADY_COMPLETED Task was already completed
INSUFFICIENT_PERMISSIONS Missing required permissions
TIER_LIMIT_EXCEEDED Exceeded tier limits

Rate Limits

Endpoint Category Team Enterprise
Workflow CRUD 60/min 300/min
Execute 30/min 150/min
Execution status 120/min 600/min
Task operations 60/min 300/min

Webhooks

Workflow Events

Subscribe to DAG events via webhooks:

Event Description
dag.execution.started Execution started
dag.execution.completed Execution completed
dag.execution.failed Execution failed
dag.execution.paused Execution paused
dag.task.created Human task created
dag.task.completed Human task completed
dag.task.escalated Task escalated

Webhook Payload:

{
  "event": "dag.execution.completed",
  "timestamp": "2026-01-18T10:45:00Z",
  "data": {
    "execution_id": "exec_ghi789",
    "workflow_id": "wf_abc123",
    "workflow_name": "Contract Review Workflow",
    "status": "completed",
    "duration_seconds": 600,
    "final_output": { ... }
  }
}

Ready to automate? Start with a workflow template.