API Reference

Complete API reference for De. Pipeline Orchestration System.

Base URL

https://api.dedot.io/v1/pipelines

Authentication

All requests require authentication via Bearer token:

typescript

Authorization: Bearer YOUR_API_KEY

Pipeline Templates

Create Template

Create a new pipeline template.

Endpoint: POST /templates

Request Body:

typescript

{
  name: string                    // Template name
  description?: string            // Template description
  version: string                 // Semantic version (e.g., "1.0.0")
  stages: Stage[]                 // Array of stage definitions
  config?: PipelineConfig         // Pipeline configuration
  health?: HealthConfig           // Health monitoring config
  metadata?: Record<string, any>  // Custom metadata
}

Response:

typescript

{
  id: string
  name: string
  version: string
  status: 'DRAFT' | 'PUBLISHED' | 'DEPRECATED'
  stages: Stage[]
  config: PipelineConfig
  health: HealthConfig
  created: {
    at: {
      timestamp: number
      datetime: string
      timezone: string
    }
    by: string
  }
  updated: {
    at: {
      timestamp: number
      datetime: string
      timezone: string
    }
    by: string
  }
}

Example:

typescript

const template = await fetch('https://api.dedot.io/v1/pipelines/templates', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "Order Fulfillment",
    version: "1.0.0",
    stages: [
      {
        name: "Validate Inventory",
        action: "QUERY",
        query: {
          resource: "INVENTORY",
          filters: { sku: "${execution.metadata.sku}" },
          strategy: "BEST_MATCH"
        },
        transitions: {
          onSuccess: { type: "CONTINUE", next: "Select Warehouse" }
        }
      }
    ]
  })
})

List Templates

Get all pipeline templates.

Endpoint: GET /templates

Query Parameters:

typescript

{
  status?: 'DRAFT' | 'PUBLISHED' | 'DEPRECATED'
  version?: string
  page?: number        // Default: 1
  limit?: number       // Default: 20, Max: 100
  sortBy?: string      // Default: 'created.at.timestamp'
  sortOrder?: 'ASC' | 'DESC'  // Default: 'DESC'
}

Response:

typescript

{
  data: PipelineTemplate[]
  pagination: {
    page: number
    limit: number
    total: number
    pages: number
  }
}

Get Template

Get a specific template by ID.

Endpoint: GET /templates/:templateId

Response: PipelineTemplate

Update Template

Update template (only DRAFT templates can be modified).

Endpoint: PATCH /templates/:templateId

Request Body: Partial PipelineTemplate

Response: PipelineTemplate

Publish Template

Mark template as published.

Endpoint: POST /templates/:templateId/publish

Response: PipelineTemplate with status: 'PUBLISHED'

Validate Template

Validate template configuration.

Endpoint: POST /templates/:templateId/validate

Response:

typescript

{
  valid: boolean
  errors: string[]
  warnings: string[]
  checks: {
    stageValidation: boolean
    queryValidation: boolean
    webhookValidation: boolean
    transitionValidation: boolean
    resourceAvailability: boolean
  }
  suggestions?: string[]
}

Delete Template

Delete a template (only DRAFT templates).

Endpoint: DELETE /templates/:templateId

Response: { success: true }

Pipelines

Deploy Pipeline

Deploy a pipeline from template.

Endpoint: POST /deploy

Request Body:

typescript

{
  templateId: string              // Template to deploy from
  name: string                    // Pipeline name
  description?: string            // Pipeline description
  config?: Partial<PipelineConfig>  // Override template config
}

Response:

typescript

{
  id: string
  templateId: string
  name: string
  description?: string
  status: {
    current: 'ACTIVE' | 'DEGRADED' | 'DISABLED' | 'SIMULATING'
    lastChanged: Timestamp
    reason?: string
  }
  stages: Stage[]
  config: PipelineConfig
  health: HealthConfig
  healthScore: number
  metrics: PipelineMetrics
  baseline: {
    duration: number
    successRate: number
  }
  created: Timestamp
  updated: Timestamp
}

List Pipelines

Get all deployed pipelines.

Endpoint: GET /

Query Parameters:

typescript

{
  status?: 'ACTIVE' | 'DEGRADED' | 'DISABLED' | 'SIMULATING'
  templateId?: string
  healthScore?: { min?: number, max?: number }
  page?: number
  limit?: number
  sortBy?: string
  sortOrder?: 'ASC' | 'DESC'
}

Response:

typescript

{
  data: Pipeline[]
  pagination: PaginationMeta
}

Get Pipeline

Get specific pipeline by ID.

Endpoint: GET /:pipelineId

Response: Pipeline

Update Pipeline

Update pipeline configuration.

Endpoint: PATCH /:pipelineId

Request Body:

typescript

{
  name?: string
  description?: string
  status?: 'ACTIVE' | 'DISABLED'
  config?: Partial<PipelineConfig>
  health?: Partial<HealthConfig>
}

Response: Pipeline

Delete Pipeline

Delete a pipeline (stops all executions).

Endpoint: DELETE /:pipelineId

Response: { success: true }

Pipeline Executions

Create Execution

Execute a pipeline.

Endpoint: POST /:pipelineId/execute

Request Body:

typescript

{
  metadata: Record<string, any>   // Execution context data
  config?: {
    timeout?: number              // Override pipeline timeout
    priority?: 'LOW' | 'NORMAL' | 'HIGH'
  }
  tags?: string[]                 // Tags for filtering
  debug?: boolean                 // Enable debug logging
}

Response:

typescript

{
  id: string
  pipelineId: string
  status: 'PENDING' | 'RUNNING' | 'SUCCESS' | 'FAILED' | 'TIMEOUT'
  currentStageIndex: number
  stages: StageExecution[]
  context: Context
  metadata: Record<string, any>
  results: Record<string, any>    // Stage results by stage name
  error?: ExecutionError
  startedAt: Timestamp
  completedAt?: Timestamp
  duration?: number
  retryAttempts: number
  tags: string[]
}

List Executions

Get pipeline executions.

Endpoint: GET /:pipelineId/executions

Query Parameters:

typescript

{
  status?: 'PENDING' | 'RUNNING' | 'SUCCESS' | 'FAILED' | 'TIMEOUT'
  tags?: string[]
  startDate?: string    // ISO 8601
  endDate?: string      // ISO 8601
  page?: number
  limit?: number
}

Response:

typescript

{
  data: PipelineExecution[]
  pagination: PaginationMeta
}

Get Execution

Get specific execution.

Endpoint: GET /executions/:executionId

Response: PipelineExecution

Retry Execution

Retry failed execution.

Endpoint: POST /executions/:executionId/retry

Request Body:

typescript

{
  fromStage?: string    // Stage to retry from (default: failed stage)
}

Response: PipelineExecution

Cancel Execution

Cancel running execution.

Endpoint: POST /executions/:executionId/cancel

Response: PipelineExecution with status: 'FAILED'

Execution Logs

Get detailed execution logs.

Endpoint: GET /executions/:executionId/logs

Response:

typescript

{
  executionId: string
  logs: {
    timestamp: number
    level: 'DEBUG' | 'INFO' | 'WARN' | 'ERROR'
    stage?: string
    message: string
    data?: any
  }[]
}

Dry Run

Test execution without side effects.

Endpoint: POST /:pipelineId/dry-run

Request Body:

typescript

{
  metadata: Record<string, any>
}

Response:

typescript

{
  stages: {
    name: string
    predictedResult: any
    estimatedDuration: number
  }[]
  estimatedDuration: number
  warnings: string[]
}

Pipeline Queries

Execute Query

Execute standalone query (outside pipeline).

Endpoint: POST /queries/execute

Request Body:

typescript

{
  resource: ResourceType
  filters: Record<string, any>
  strategy: SelectionStrategy
  fallbackOptions?: FallbackOption[]
  context?: Record<string, any>
}

Response:

typescript

{
  resource: any          // Selected resource
  score: number          // Selection score
  strategy: string       // Strategy used
  alternatives: any[]    // Other candidates
}

Webhooks

List Webhook Events

Get webhook delivery history.

Endpoint: GET /webhooks

Query Parameters:

typescript

{
  executionId?: string
  status?: 'PENDING' | 'DELIVERED' | 'FAILED'
  startDate?: string
  endDate?: string
  page?: number
  limit?: number
}

Response:

typescript

{
  data: {
    id: string
    executionId: string
    stage: string
    url: string
    method: string
    status: 'PENDING' | 'DELIVERED' | 'FAILED'
    attempts: number
    lastAttempt?: Timestamp
    response?: {
      statusCode: number
      body: any
      headers: Record<string, string>
    }
    error?: string
  }[]
  pagination: PaginationMeta
}

Retry Webhook

Manually retry failed webhook.

Endpoint: POST /webhooks/:webhookId/retry

Response: Webhook with updated status

Monitoring

Pipeline Health

Get pipeline health metrics.

Endpoint: GET /:pipelineId/health

Response:

typescript

{
  pipelineId: string
  status: 'HEALTHY' | 'DEGRADED' | 'CRITICAL' | 'UNKNOWN'
  healthScore: number
  lastCheck: Timestamp
  metrics: {
    totalExecutions: number
    successRate: number
    errorRate: number
    avgDuration: number
    p95Duration: number
    p99Duration: number
    activeExecutions: number
  }
  alerts: {
    severity: 'INFO' | 'WARNING' | 'CRITICAL'
    message: string
    timestamp: Timestamp
    acknowledged: boolean
  }[]
  lastSimulation?: {
    success: boolean
    duration: number
    completedAt: Timestamp
  }
}

Pipeline Analytics

Get detailed analytics.

Endpoint: GET /:pipelineId/analytics

Query Parameters:

typescript

{
  startDate?: string
  endDate?: string
  groupBy?: 'hour' | 'day' | 'week'
}

Response:

typescript

{
  timeSeries: {
    timestamp: number
    executions: number
    successes: number
    failures: number
    avgDuration: number
  }[]
  stageMetrics: {
    stage: string
    executions: number
    successRate: number
    avgDuration: number
    errors: string[]
  }[]
  resourceUsage: {
    resource: string
    selections: number
    avgScore: number
  }[]
}

Escalations

Get execution escalations (failures, timeouts).

Endpoint: GET /escalations

Query Parameters:

typescript

{
  severity?: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL'
  status?: 'OPEN' | 'ACKNOWLEDGED' | 'RESOLVED'
  page?: number
  limit?: number
}

Response:

typescript

{
  data: {
    id: string
    executionId: string
    pipelineId: string
    severity: string
    reason: string
    stage?: string
    status: string
    createdAt: Timestamp
    resolvedAt?: Timestamp
  }[]
  pagination: PaginationMeta
}

Workers

Get Worker Stats

Get worker system statistics.

Endpoint: GET /workers/stats

Response:

typescript

{
  workers: {
    name: string
    enabled: boolean
    intervalMs: number
    stats: {
      activeExecutions?: number
      stalledStages?: number
      timedOutStages?: number
      completedToday?: number
      failedToday?: number
      pipelinesChecked?: number
      healthScoresCalculated?: number
      statusChanges?: number
      alertsGenerated?: number
      transitionsProcessed?: number
      transitionErrors?: number
      webhooksDelivered?: number
      webhookRetries?: number
      webhookFailures?: number
    }
    lastRun?: Timestamp
  }[]
}

Initialize Workers

Initialize workers for current workspace.

Endpoint: POST /workers/initialize

Response: { success: true, workersInitialized: number }

Start Workers

Start all workers.

Endpoint: POST /workers/start

Response: { success: true }

Stop Workers

Stop all workers.

Endpoint: POST /workers/stop

Response: { success: true }

Type Definitions

Stage

typescript

interface Stage {
  name: string
  description?: string
  action: 'QUERY' | 'WEBHOOK' | 'WAIT'
  query?: QueryConfig
  webhook?: WebhookConfig
  wait?: WaitConfig
  transitions: {
    onSuccess?: Transition
    onFailure?: Transition
    onTimeout?: Transition
  }
  timeout?: number
  retries?: number
  retryDelay?: number
}

QueryConfig

typescript

interface QueryConfig {
  resource: 'WAREHOUSE' | 'CARRIER' | 'TERMINAL' | 'ROUTE' | 'INVENTORY' | 'VEHICLE'
  filters: Record<string, any>
  strategy: 'BEST_MATCH' | 'CLOSEST' | 'FASTEST' | 'CHEAPEST' | 'HIGHEST_CAPACITY' | 'HIGHEST_RATED' | 'RANDOM'
  fallbackOptions?: FallbackOption[]
  cacheDuration?: number
}

WebhookConfig

typescript

interface WebhookConfig {
  url: string
  method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'
  headers?: Record<string, string>
  body?: any
  timeout?: number
  retries?: number
}

WaitConfig

typescript

interface WaitConfig {
  type: 'DURATION' | 'CONDITION'
  duration?: number          // Milliseconds
  condition?: TransitionCondition
  timeout?: number
  checkInterval?: number     // For condition checks
}

Transition

typescript

interface Transition {
  type: 'CONTINUE' | 'SKIP' | 'RETRY' | 'FAIL' | 'COMPLETE'
  next?: string              // Stage name
  condition?: TransitionCondition
  retries?: number
  retryDelay?: number
}

TransitionCondition

typescript

interface TransitionCondition {
  field: string
  operator: 'EQUALS' | 'NOT_EQUALS' | 'GREATER_THAN' | 'LESS_THAN' | 'CONTAINS' | 'EXISTS'
  value: any
  logic?: 'AND' | 'OR'
  conditions?: TransitionCondition[]
}

PipelineConfig

typescript

interface PipelineConfig {
  timeout?: number           // Max execution time (ms)
  concurrency?: number       // Max parallel executions
  maxExecutionsPerHour?: number
  retryPolicy?: {
    maxAttempts: number
    backoffMultiplier: number
    initialDelay: number
  }
}

HealthConfig

typescript

interface HealthConfig {
  simulationEnabled: boolean
  simulationInterval: number  // Seconds
  testData?: Record<string, any>
  alertThresholds: {
    healthScore: number
    errorRate: number
    avgDuration: number
  }
}

Error Codes

Code	Description	Action
`TEMPLATE_INVALID`	Template validation failed	Fix template configuration
`PIPELINE_NOT_FOUND`	Pipeline does not exist	Check pipeline ID
`EXECUTION_FAILED`	Execution failed	Check execution logs
`STAGE_TIMEOUT`	Stage exceeded timeout	Increase timeout or optimize stage
`QUERY_NO_RESULTS`	No resources matched query	Adjust filters or add fallback
`WEBHOOK_FAILED`	Webhook delivery failed	Check webhook URL and credentials
`RESOURCE_NOT_AVAILABLE`	Required resource unavailable	Check resource status
`CONCURRENCY_LIMIT`	Max concurrent executions reached	Wait or increase limit
`RATE_LIMIT_EXCEEDED`	Too many requests	Implement rate limiting

Rate Limits

Template Operations: 100 requests/minute
Pipeline Deployments: 10 deployments/minute
Execution Creation: 1,000 executions/minute
Query Operations: 500 queries/minute
Webhook Deliveries: Unlimited (handled by workers)

SDK Usage

JavaScript/TypeScript

typescript

import { DeClient } from '@dedot/sdk'

const client = new DeClient({
  apiKey: 'your-api-key',
  workspace: 'your-workspace-id'
})

// Templates
const template = await client.pipelines.templates.create({...})
const validation = await client.pipelines.templates.validate(template.id)

// Pipelines
const pipeline = await client.pipelines.deploy({...})
const pipelines = await client.pipelines.list()

// Executions
const execution = await client.pipelines.execute(pipeline.id, {...})
const status = await client.pipelines.executions.get(execution.id)

// Health
const health = await client.pipelines.getHealth(pipeline.id)

API Reference ​

Base URL ​

Authentication ​

Pipeline Templates ​

Create Template ​

List Templates ​

Get Template ​

Update Template ​

Publish Template ​

Validate Template ​

Delete Template ​

Pipelines ​

Deploy Pipeline ​

List Pipelines ​

Get Pipeline ​

Update Pipeline ​

Delete Pipeline ​

Pipeline Executions ​

Create Execution ​

List Executions ​

Get Execution ​

Retry Execution ​

Cancel Execution ​

Execution Logs ​

Dry Run ​

Pipeline Queries ​

Execute Query ​

Webhooks ​

List Webhook Events ​

Retry Webhook ​

Monitoring ​

Pipeline Health ​

Pipeline Analytics ​

Escalations ​

Workers ​

Get Worker Stats ​

Initialize Workers ​

Start Workers ​

Stop Workers ​

Type Definitions ​

Stage ​

QueryConfig ​

WebhookConfig ​

WaitConfig ​

Transition ​

TransitionCondition ​

PipelineConfig ​

HealthConfig ​

Error Codes ​

Rate Limits ​

SDK Usage ​

JavaScript/TypeScript ​

Next Steps ​

API Reference

Base URL

Authentication

Pipeline Templates

Create Template

List Templates

Get Template

Update Template

Publish Template

Validate Template

Delete Template

Pipelines

Deploy Pipeline

List Pipelines

Get Pipeline

Update Pipeline

Delete Pipeline

Pipeline Executions

Create Execution

List Executions

Get Execution

Retry Execution

Cancel Execution

Execution Logs

Dry Run

Pipeline Queries

Execute Query

Webhooks

List Webhook Events

Retry Webhook

Monitoring

Pipeline Health

Pipeline Analytics

Escalations

Workers

Get Worker Stats

Initialize Workers

Start Workers

Stop Workers

Type Definitions

Stage

QueryConfig

WebhookConfig

WaitConfig

Transition

TransitionCondition

PipelineConfig

HealthConfig

Error Codes

Rate Limits

SDK Usage

JavaScript/TypeScript

Next Steps