REST API

Flowguard provides a RESTful API for managing and executing flows programmatically.

Base URL

All API endpoints are prefixed with:

/wp-json/flowguard/v1/

Example:

https://yoursite.com/wp-json/flowguard/v1/flows

Authentication

API endpoints require WordPress authentication:

For requests from the WordPress admin:

Automatically authenticated if logged in
Nonce verification required for write operations

Application Passwords

For external requests:

Create an Application Password in WordPress user profile
Use HTTP Basic Authentication
Username: WordPress username
Password: Application Password

Example with cURL:

bash

curl -u 'username:xxxx xxxx xxxx xxxx xxxx xxxx' \
  https://yoursite.com/wp-json/flowguard/v1/flows

Permissions

Flow Endpoints

Read operations - Requires edit_posts capability Write operations - Requires edit_posts capability

Settings Endpoints

Read operations - Requires manage_options capability Write operations - Requires manage_options capability

Flow Endpoints

List Flows

Get a list of all flows (uses WordPress built-in posts endpoint).

Endpoint:

GET /wp-json/wp/v2/flowguard_flow

Parameters:

Parameter	Type	Description
`per_page`	integer	Number of flows per page (default: 10)
`page`	integer	Page number (default: 1)
`search`	string	Search flows by title
`status`	string	Filter by status (publish, draft, etc.)

Response:

json

[
  {
    "id": 123,
    "title": {
      "rendered": "Login Test Flow"
    },
    "status": "publish",
    "date": "2024-12-06T10:00:00",
    "modified": "2024-12-06T15:30:00",
    "meta": {
      "flowguard_status": "active",
      "flowguard_steps": [...],
      "flowguard_settings": {...},
      "flowguard_last_run": {...}
    }
  }
]

Example:

bash

curl https://yoursite.com/wp-json/wp/v2/flowguard_flow?per_page=20

Get Single Flow

Retrieve a specific flow by ID.

Endpoint:

GET /wp-json/wp/v2/flowguard_flow/{id}

Parameters:

Parameter	Type	Description
`id`	integer	The flow post ID

Response:

json

{
  "id": 123,
  "title": {
    "rendered": "Login Test Flow"
  },
  "status": "publish",
  "meta": {
    "flowguard_status": "active",
    "flowguard_steps": [
      {
        "id": "step_1",
        "type": "navigate",
        "config": {
          "url": "https://yoursite.com/login"
        }
      }
    ],
    "flowguard_settings": {
      "timeout": 30000,
      "retries": 0,
      "screenshot": true
    },
    "flowguard_last_run": {
      "timestamp": "2024-12-06T15:30:00",
      "status": "passed",
      "duration": 3450,
      "error": "",
      "results": [...]
    }
  }
}

Example:

bash

curl https://yoursite.com/wp-json/wp/v2/flowguard_flow/123

Create Flow

Create a new flow.

Endpoint:

POST /wp-json/wp/v2/flowguard_flow

Request Body:

json

{
  "title": "New Test Flow",
  "status": "publish",
  "meta": {
    "flowguard_status": "active",
    "flowguard_steps": [
      {
        "id": "step_1",
        "type": "navigate",
        "config": {
          "url": "https://yoursite.com"
        }
      }
    ],
    "flowguard_settings": {
      "timeout": 30000,
      "retries": 0,
      "screenshot": true
    }
  }
}

Response: Returns the created flow object (same format as Get Single Flow).

Example:

bash

curl -X POST https://yoursite.com/wp-json/wp/v2/flowguard_flow \
  -H "Content-Type: application/json" \
  -d '{"title":"New Flow","status":"publish"}'

Update Flow

Update an existing flow.

Endpoint:

PUT /wp-json/wp/v2/flowguard_flow/{id}

Parameters:

Parameter	Type	Description
`id`	integer	The flow post ID

Request Body: Same format as Create Flow (only include fields you want to update).

Response: Returns the updated flow object.

Example:

bash

curl -X PUT https://yoursite.com/wp-json/wp/v2/flowguard_flow/123 \
  -H "Content-Type: application/json" \
  -d '{"title":"Updated Flow Title"}'

Delete Flow

Delete a flow.

Endpoint:

DELETE /wp-json/wp/v2/flowguard_flow/{id}

Parameters:

Parameter	Type	Description
`id`	integer	The flow post ID
`force`	boolean	Bypass trash and permanently delete (default: false)

Response:

json

{
  "deleted": true,
  "previous": {
    // Previous flow object
  }
}

Example:

bash

curl -X DELETE https://yoursite.com/wp-json/wp/v2/flowguard_flow/123?force=true

Flow Execution Endpoints

Run Single Flow

Execute a specific flow.

Endpoint:

POST /wp-json/flowguard/v1/flows/{id}/run

Parameters:

Parameter	Type	Description
`id`	integer	The flow post ID

Response:

json

{
  "success": true,
  "message": "Flow execution started.",
  "flow": {
    "id": 123,
    "title": "Login Test Flow",
    "steps": [...],
    "settings": {...},
    "siteUrl": "https://yoursite.com"
  }
}

Example:

bash

curl -X POST https://yoursite.com/wp-json/flowguard/v1/flows/123/run

Notes:

Returns immediately with flow data
Actual execution happens on external runner (Node.js server)
Updates flow meta with "running" status

Get Flow Results

Retrieve execution results for a flow.

Endpoint:

GET /wp-json/flowguard/v1/flows/{id}/results

Parameters:

Parameter	Type	Description
`id`	integer	The flow post ID

Response:

json

{
  "id": 123,
  "title": "Login Test Flow",
  "last_run": {
    "timestamp": "2024-12-06T15:30:00",
    "status": "passed",
    "duration": 3450,
    "error": "",
    "results": [
      {
        "step": 1,
        "type": "navigate",
        "status": "passed",
        "duration": 1200,
        "error": ""
      },
      {
        "step": 2,
        "type": "click",
        "status": "passed",
        "duration": 350,
        "error": ""
      }
    ]
  }
}

Example:

bash

curl https://yoursite.com/wp-json/flowguard/v1/flows/123/results

Run All Active Flows

Execute all flows with "active" status.

Endpoint:

POST /wp-json/flowguard/v1/flows/run-all

Response:

json

{
  "success": true,
  "message": "Started execution of 5 flows.",
  "flows": [
    {
      "id": 123,
      "title": "Login Test",
      "steps": [...],
      "settings": {...}
    },
    {
      "id": 124,
      "title": "Contact Form Test",
      "steps": [...],
      "settings": {...}
    }
  ],
  "siteUrl": "https://yoursite.com"
}

Example:

bash

curl -X POST https://yoursite.com/wp-json/flowguard/v1/flows/run-all

Get Flow Statistics

Get aggregated statistics for all flows.

Endpoint:

GET /wp-json/flowguard/v1/flows/stats

Response:

json

{
  "success": true,
  "stats": {
    "total": 10,
    "active": 7,
    "inactive": 3,
    "passed": 5,
    "failed": 2,
    "pending": 3,
    "running": 0
  }
}

Example:

bash

curl https://yoursite.com/wp-json/flowguard/v1/flows/stats

Settings Endpoints

Get Settings

Retrieve all plugin settings.

Endpoint:

GET /wp-json/flowguard/v1/settings

Response:

json

{
  "general": {
    "default_focus_mode": true
  },
  "test_mode": {
    "enabled": true,
    "email_strategy": "block",
    "test_email": "test@example.com",
    "capture_error_screenshots": true
  },
  "execution": {
    "mode": "remote",
    "local_api_path": "",
    "local_port": 3000,
    "local_host": "localhost",
    "remote_url": ""
  }
}

Example:

bash

curl https://yoursite.com/wp-json/flowguard/v1/settings

Permissions: Requires manage_options capability

Update Settings

Update plugin settings.

Endpoint:

PUT /wp-json/flowguard/v1/settings

Request Body:

json

{
  "general": {
    "default_focus_mode": false
  },
  "execution": {
    "mode": "local",
    "local_api_path": "/var/www/flowguard-api",
    "local_port": 3000
  }
}

Response: Returns the updated settings object.

Example:

bash

curl -X PUT https://yoursite.com/wp-json/flowguard/v1/settings \
  -H "Content-Type: application/json" \
  -d '{"general":{"default_focus_mode":true}}'

Permissions: Requires manage_options capability

Check System Requirements

Check system requirements for local execution mode.

Endpoint:

GET /wp-json/flowguard/v1/system/requirements

Response:

json

{
  "requirements": [
    {
      "id": "nodejs",
      "name": "Node.js",
      "status": "installed",
      "version": "v20.10.0",
      "required": ">=18.0.0",
      "message": "Node.js v20.10.0 is installed"
    },
    {
      "id": "npm",
      "name": "npm",
      "status": "installed",
      "version": "10.2.3",
      "required": ">=8.0.0",
      "message": "npm 10.2.3 is installed"
    },
    {
      "id": "api_directory",
      "name": "API Directory",
      "status": "installed",
      "version": "/var/www/flowguard-api",
      "required": "Valid path",
      "message": "API directory exists"
    },
    {
      "id": "package_json",
      "name": "package.json",
      "status": "installed",
      "version": null,
      "required": "Exists",
      "message": "package.json found"
    },
    {
      "id": "npm_package_express",
      "name": "npm package: express",
      "status": "installed",
      "version": "4.18.2",
      "required": "^4.18.2",
      "message": "express 4.18.2 is installed"
    },
    {
      "id": "npm_package_playwright",
      "name": "npm package: playwright",
      "status": "installed",
      "version": "1.40.0",
      "required": "^1.40.0",
      "message": "playwright 1.40.0 is installed"
    },
    {
      "id": "npm_package_axios",
      "name": "npm package: axios",
      "status": "installed",
      "version": "1.6.2",
      "required": "^1.6.2",
      "message": "axios 1.6.2 is installed"
    },
    {
      "id": "npm_package_dotenv",
      "name": "npm package: dotenv",
      "status": "installed",
      "version": "16.3.1",
      "required": "^16.3.1",
      "message": "dotenv 16.3.1 is installed"
    },
    {
      "id": "playwright_browsers",
      "name": "Playwright Browsers",
      "status": "installed",
      "version": "Version 1.40.0",
      "required": "Installed",
      "message": "Playwright browsers are installed"
    },
    {
      "id": "server_health",
      "name": "Local Server",
      "status": "installed",
      "version": "localhost:3000",
      "required": "Running",
      "message": "Local server is running and healthy"
    }
  ],
  "allMet": true,
  "canEnableLocal": true
}

Status Values:

installed - Requirement is met
not_installed - Requirement is not met
error - Error checking requirement

Example:

bash

curl https://yoursite.com/wp-json/flowguard/v1/system/requirements

Use Cases:

Verify local execution prerequisites before switching modes
Troubleshoot local setup issues
Monitor system health
Automate deployment validation

Permissions: Requires manage_options capability

Error Responses

Standard Error Format

json

{
  "code": "rest_forbidden",
  "message": "You do not have permission to run flows.",
  "data": {
    "status": 403
  }
}

Common Error Codes

Code	Status	Description
`rest_forbidden`	403	Insufficient permissions
`rest_no_route`	404	Endpoint not found
`rest_flow_not_found`	404	Flow ID doesn't exist
`rest_flow_empty`	400	Flow has no steps
`rest_invalid_param`	400	Invalid parameter value
`rest_cannot_update`	500	Update operation failed

Rate Limiting

Currently, no rate limiting is enforced. Future versions may implement:

Request limits per user
Execution throttling
Concurrent flow limits

Webhooks

INFO

Webhook support is planned for future versions. You'll be able to:

Receive notifications when flows complete
Trigger external actions based on results
Integrate with third-party services

Code Examples

JavaScript (Fetch API)

javascript

// Get all flows
fetch('/wp-json/wp/v2/flowguard_flow')
  .then(response => response.json())
  .then(flows => console.log(flows));

// Run a flow
fetch('/wp-json/flowguard/v1/flows/123/run', {
  method: 'POST',
  headers: {
    'X-WP-Nonce': wpApiSettings.nonce
  }
})
  .then(response => response.json())
  .then(result => console.log(result));

PHP

php

// Get flow results
$response = wp_remote_get(
  home_url('/wp-json/flowguard/v1/flows/123/results')
);
$results = json_decode(wp_remote_retrieve_body($response));

// Run all active flows
$response = wp_remote_post(
  home_url('/wp-json/flowguard/v1/flows/run-all')
);

Python

python

import requests
from requests.auth import HTTPBasicAuth

# Configuration
site_url = 'https://yoursite.com'
username = 'admin'
app_password = 'xxxx xxxx xxxx xxxx xxxx xxxx'

# Get flow statistics
response = requests.get(
    f'{site_url}/wp-json/flowguard/v1/flows/stats',
    auth=HTTPBasicAuth(username, app_password)
)
stats = response.json()
print(stats)

# Run a flow
response = requests.post(
    f'{site_url}/wp-json/flowguard/v1/flows/123/run',
    auth=HTTPBasicAuth(username, app_password)
)
result = response.json()
print(result)

cURL

bash

# Get all flows
curl https://yoursite.com/wp-json/wp/v2/flowguard_flow

# Run a flow with authentication
curl -X POST \
  -u 'username:xxxx xxxx xxxx xxxx xxxx xxxx' \
  https://yoursite.com/wp-json/flowguard/v1/flows/123/run

# Get stats
curl https://yoursite.com/wp-json/flowguard/v1/flows/stats

Best Practices

Use Appropriate HTTP Methods

GET for reading data
POST for creating and executing
PUT or PATCH for updating
DELETE for removing

Handle Errors Gracefully

Always check response status and handle errors:

javascript

fetch('/wp-json/flowguard/v1/flows/123/run', {
  method: 'POST'
})
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}`);
    }
    return response.json();
  })
  .then(data => console.log(data))
  .catch(error => console.error('Error:', error));

Respect Permissions

Ensure your user account has appropriate capabilities before making requests.

Use HTTPS

Always use HTTPS in production to protect authentication credentials.

WordPress Actions - Hook into flow execution
WordPress Filters - Modify API behavior
Running Flows - User guide for execution

Future Enhancements

Planned API improvements:

Batch operations
Webhook support
Real-time execution streaming
Flow versioning endpoints
Import/export endpoints
Scheduled execution management

Support

For API issues:

Check WordPress REST API is enabled
Verify authentication is working
Check error responses for details
Review WordPress and Flowguard logs
Test with a REST client (Postman, Insomnia)

REST API ​

Base URL ​

Authentication ​

Cookie Authentication ​

Application Passwords ​

Permissions ​

Flow Endpoints ​

Settings Endpoints ​

Flow Endpoints ​

List Flows ​

Get Single Flow ​

Create Flow ​

Update Flow ​

Delete Flow ​

Flow Execution Endpoints ​

Run Single Flow ​

Get Flow Results ​

Run All Active Flows ​

Get Flow Statistics ​

Settings Endpoints ​

Get Settings ​

Update Settings ​

Check System Requirements ​

Error Responses ​

Standard Error Format ​

Common Error Codes ​

Rate Limiting ​

Webhooks ​

Code Examples ​

JavaScript (Fetch API) ​

PHP ​

Python ​

cURL ​

Best Practices ​

Use Appropriate HTTP Methods ​

Handle Errors Gracefully ​

Respect Permissions ​

Use HTTPS ​

Related Documentation ​

Future Enhancements ​

Support ​

REST API

Base URL

Authentication

Cookie Authentication

Application Passwords

Permissions

Flow Endpoints

Settings Endpoints

Flow Endpoints

List Flows

Get Single Flow

Create Flow

Update Flow

Delete Flow

Flow Execution Endpoints

Run Single Flow

Get Flow Results

Run All Active Flows

Get Flow Statistics

Settings Endpoints

Get Settings

Update Settings

Check System Requirements

Error Responses

Standard Error Format

Common Error Codes

Rate Limiting

Webhooks

Code Examples

JavaScript (Fetch API)

PHP

Python

cURL

Best Practices

Use Appropriate HTTP Methods

Handle Errors Gracefully

Respect Permissions

Use HTTPS

Related Documentation

Future Enhancements

Support