Implementation: inc/Api/Execute.php

Base URL: /wp-json/datamachine/v1/execute

Overview

The Execute endpoint provides workflow execution capabilities for both database flows and ephemeral workflows. It handles immediate execution and delayed (one-time) execution via Action Scheduler.

Authentication

Requires WordPress authentication with manage_options capability.

Request Parameters

Method: POST

Content-Type: application/json

Core Parameters (Provide one)

• flow_id (integer): The ID of a saved database flow to trigger.
• workflow (object): A temporary workflow structure (ephemeral) containing a steps array.

Execution Control

• timestamp (integer, optional): Unix timestamp for delayed one-time execution. If omitted, execution is immediate.
• initial_data (object, optional): Initial engine data to merge into the job’s stored engine_data before execution.

Trigger Logic

• Database Flow: If flow_id is provided, the engine loads the saved flow and pipeline configuration.
• Ephemeral Workflow: If workflow is provided, the engine dynamically generates a configuration on-the-fly. This is useful for testing or one-off tasks generated by AI agents.
• Action IDs: All executions return a job_id for tracking. Delayed executions also return an action_id (Action Scheduler ID).

Ephemeral Workflow Structure

An ephemeral workflow must contain a steps array:

{
  "workflow": {
    "steps": [
      {
        "type": "fetch",
        "handler_slug": "rss",
        "handler_config": { "feed_url": "https://example.com/feed" }
      },
      {
        "type": "ai",
        "provider": "anthropic",
        "model": "claude-3-5-sonnet-20240620",
        "system_prompt": "Summarize this content"
      },
      {
        "type": "publish",
        "handler_slug": "wordpress-post",
        "handler_config": { "post_status": "draft" }
      }
    ]
  }
}

Example Responses

Immediate Database Flow

{
  "success": true,
  "data": {
    "execution_type": "immediate",
    "flow_id": 123,
    "flow_name": "Daily News Sync",
    "job_id": 456,
    "action_id": 789
  },
  "message": "Flow queued for immediate background execution via Action Scheduler"
}

Immediate Ephemeral Workflow

{
  "success": true,
  "data": {
    "execution_type": "immediate",
    "job_id": 457,
    "step_count": 3
  },
  "message": "Ephemeral workflow execution started"
}

Response Fields

• success (boolean): Whether the request was accepted.
• data.execution_type (string): immediate or delayed.
• data.job_id (int): The unique ID of the job record created for this execution.
• data.action_id (int, optional): The Action Scheduler action ID.
• data.flow_id (int, optional): The ID of the database flow (for flow executions).
• data.step_count (int, optional): Number of steps (for ephemeral workflows).
• message (string): Human-readable confirmation.

Endpoint: POST /datamachine/v1/execute
Permission: manage_options capability required
Implementation: inc/Api/Execute.php