Integrating with Coalface Tasks

Coalface Tasks exposes a PHP function and a REST API endpoint so other plugins, or external tools, can create and manage tasks automatically.

Creating a task from another WordPress plugin

Call cft_create_task() from anywhere in your plugin after WordPress has loaded. It returns the new task ID on success, or a WP_Error on failure.

$task_id = cft_create_task([
    'title'       => 'Issue found on checkout page',
    'description' => 'The coupon field throws a PHP notice when left empty.',
    'priority'    => 'high',    // '', 'low', 'medium', or 'high'
    'column_id'   => 3,         // optional — defaults to the first column
    'due_date'    => '2026-06-30', // optional — YYYY-MM-DD
]);

if ( is_wp_error( $task_id ) ) {
    // handle the error
} else {
    // $task_id is the integer ID of the new task
}

The calling user needs the Edit Tasks permission in Coalface Tasks → Settings → Permissions. Administrators always have access.

Modifying a task before it’s saved

Use the cft_pre_create_task filter to change the task data before it hits the database — useful for prefixing titles, overriding the column, or adding context.

add_filter( 'cft_pre_create_task', function ( array $args ): array {
    $args['title'] = '[My Plugin] ' . $args['title'];
    return $args;
} );

Running code after a task is created

The cft_task_created action fires after every task is created, regardless of where it came from.

add_action( 'cft_task_created', function ( array $task ): void {
    $task_id = (int) $task['id'];
    // e.g. log it, send a webhook, store a reference
} );

Available hooks

• cft_pre_create_task – (Filter) modify task data before insert
• cft_task_created – (Action) fires after a task is created
• cft_task_updated – (Action) fires after a task is updated
• cft_task_deleted – (Action) fires after a task is deleted
• cft_note_created – (Action) fires after a note is added to a task

Creating a task via the REST API

If you’re working outside WordPress, send a POST request to:

POST https://your-site.com/wp-json/tm/v1/tasks

Authenticate using WordPress Application Passwords (HTTP Basic Auth). Generate one under Users → Your Profile → Application Passwords.

Request body (JSON):

{
    "title":       "Issue title",
    "description": "Details about the issue.",
    "priority":    "high",
    "column_id":   3,
    "due_date":    "2026-06-30"
}

To find your board and column IDs:

GET /wp-json/tm/v1/boards
GET /wp-json/tm/v1/columns?board_id=1

The user account used for authentication must have the Edit Tasks permission in Coalface Tasks → Settings → Permissions.