Schedule a Playbook Run

POST

v2.0

playbooks

{playbookId}

schedule

Schedule a Playbook Run

curl --request POST \
  --url https://api-trial.cognigy.ai/new/v2.0/playbooks/{playbookId}/schedule \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "entrypoint": "61f25579055c2f43c249a181",
  "flowId": "010d1970-89b9-4012-892b-53c78ef6c117",
  "localeId": "8b3b45e2-48f9-446d-a4c5-35d8284a01b2"
}
'

import requests

url = "https://api-trial.cognigy.ai/new/v2.0/playbooks/{playbookId}/schedule"

payload = {
    "entrypoint": "61f25579055c2f43c249a181",
    "flowId": "010d1970-89b9-4012-892b-53c78ef6c117",
    "localeId": "8b3b45e2-48f9-446d-a4c5-35d8284a01b2"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    entrypoint: '61f25579055c2f43c249a181',
    flowId: '010d1970-89b9-4012-892b-53c78ef6c117',
    localeId: '8b3b45e2-48f9-446d-a4c5-35d8284a01b2'
  })
};

fetch('https://api-trial.cognigy.ai/new/v2.0/playbooks/{playbookId}/schedule', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-trial.cognigy.ai/new/v2.0/playbooks/{playbookId}/schedule",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'entrypoint' => '61f25579055c2f43c249a181',
    'flowId' => '010d1970-89b9-4012-892b-53c78ef6c117',
    'localeId' => '8b3b45e2-48f9-446d-a4c5-35d8284a01b2'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-trial.cognigy.ai/new/v2.0/playbooks/{playbookId}/schedule"

	payload := strings.NewReader("{\n  \"entrypoint\": \"61f25579055c2f43c249a181\",\n  \"flowId\": \"010d1970-89b9-4012-892b-53c78ef6c117\",\n  \"localeId\": \"8b3b45e2-48f9-446d-a4c5-35d8284a01b2\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-trial.cognigy.ai/new/v2.0/playbooks/{playbookId}/schedule")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"entrypoint\": \"61f25579055c2f43c249a181\",\n  \"flowId\": \"010d1970-89b9-4012-892b-53c78ef6c117\",\n  \"localeId\": \"8b3b45e2-48f9-446d-a4c5-35d8284a01b2\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-trial.cognigy.ai/new/v2.0/playbooks/{playbookId}/schedule")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"entrypoint\": \"61f25579055c2f43c249a181\",\n  \"flowId\": \"010d1970-89b9-4012-892b-53c78ef6c117\",\n  \"localeId\": \"8b3b45e2-48f9-446d-a4c5-35d8284a01b2\"\n}"

response = http.request(request)
puts response.read_body

{
  "_id": "<string>",
  "status": "queued",
  "type": "runPlaybook",
  "parameters": {},
  "createdAt": 123,
  "lastChangedAt": 123,
  "progress": 50,
  "job": {
    "name": "<string>",
    "namespace": "<string>",
    "timeoutInMs": 123
  }
}

{
  "type": "Bad Request",
  "title": "Bad Request Error",
  "status": 400,
  "detail": "Validation failed. Missing payload.",
  "instance": "/v2.0/flows/5ce7c2d833ea1e04d7e6c432",
  "code": 1000,
  "traceId": "api--f84324f4-98eb-4f02-abdd-375a2e6c3c1f",
  "details": {}
}

{
  "type": "Unauthorized",
  "title": "Unauthorized Error",
  "status": 401,
  "detail": "<string>",
  "instance": "/v2.0/flows/5ce7c2d833ea1e04d7e6c432",
  "code": 401,
  "traceId": "api--f84324f4-98eb-4f02-abdd-375a2e6c3c1f",
  "details": {}
}

{
  "type": "Payment Required",
  "title": "Payment Required Error",
  "status": 402,
  "detail": "Validation failed. Missing payload.",
  "instance": "/v2.0/flows/5ce7c2d833ea1e04d7e6c432",
  "code": 402,
  "traceId": "api--f84324f4-98eb-4f02-abdd-375a2e6c3c1f",
  "details": {}
}

{
  "type": "Forbidden",
  "title": "Forbidden Error",
  "status": 403,
  "detail": "<string>",
  "instance": "/v2.0/flows/5ce7c2d833ea1e04d7e6c432",
  "code": 1000,
  "traceId": "api--f84324f4-98eb-4f02-abdd-375a2e6c3c1f",
  "details": {}
}

{
  "type": "Not Found",
  "title": "Not Found Error",
  "status": 404,
  "detail": "<string>",
  "instance": "/v2.0/flows/5ce7c2d833ea1e04d7e6c432",
  "code": 1000,
  "traceId": "api--f84324f4-98eb-4f02-abdd-375a2e6c3c1f",
  "details": {},
  "logLevel": "error"
}

{
  "type": "Method Not Allowed",
  "title": "Method Not Allowed Error",
  "status": 405,
  "detail": "<string>",
  "instance": "/v2.0/flows/5ce7c2d833ea1e04d7e6c432",
  "code": 1000,
  "traceId": "api--f84324f4-98eb-4f02-abdd-375a2e6c3c1f",
  "details": {}
}

{
  "type": "Conflict",
  "title": "Conflict Error",
  "status": 409,
  "detail": "<string>",
  "instance": "/v2.0/flows/5ce7c2d833ea1e04d7e6c432",
  "code": 1004,
  "traceId": "api--f84324f4-98eb-4f02-abdd-375a2e6c3c1f",
  "details": {}
}

{
  "type": "Payload Too Large",
  "title": "Payload Too Large Error",
  "status": 413,
  "detail": "<string>",
  "instance": "/v2.0/flows/5ce7c2d833ea1e04d7e6c432",
  "code": 1000,
  "traceId": "api--f84324f4-98eb-4f02-abdd-375a2e6c3c1f",
  "details": {}
}

{
  "type": "Internal Server Error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "<string>",
  "instance": "/v2.0/flows/5ce7c2d833ea1e04d7e6c432",
  "code": 1000,
  "traceId": "api--f84324f4-98eb-4f02-abdd-375a2e6c3c1f",
  "details": {}
}

{
  "type": "Not Implemented",
  "title": "Not Implemented Error",
  "status": 501,
  "detail": "<string>",
  "instance": "/v2.0/flows/5ce7c2d833ea1e04d7e6c432",
  "code": 1009,
  "traceId": "api--f84324f4-98eb-4f02-abdd-375a2e6c3c1f",
  "details": {}
}

{
  "type": "Bad Gateway",
  "title": "Bad Gateway Error",
  "status": 502,
  "detail": "<string>",
  "instance": "/v2.0/flows/5ce7c2d833ea1e04d7e6c432",
  "code": 1000,
  "traceId": "api--f84324f4-98eb-4f02-abdd-375a2e6c3c1f",
  "details": {}
}

{
  "type": "Service Unavailable",
  "title": "Service Unavailable Error",
  "status": 503,
  "detail": "<string>",
  "instance": "/v2.0/flows/5ce7c2d833ea1e04d7e6c432",
  "code": 503,
  "traceId": "api--f84324f4-98eb-4f02-abdd-375a2e6c3c1f",
  "details": {}
}

{
  "type": "Gateway Timeout",
  "title": "Gateway Timeout Error",
  "status": 504,
  "detail": "<string>",
  "instance": "/v2.0/flows/5ce7c2d833ea1e04d7e6c432",
  "code": 1000,
  "traceId": "api--f84324f4-98eb-4f02-abdd-375a2e6c3c1f",
  "details": {}
}

Authorizations

X-API-Key

string

header

required

Supply the API Key in the HTTP-Header

Headers

enum<string>

The Accept header specifies the media type that the client expects in the response. Available options: application/json, application/hal+json, application/xml, text/xml, text/csv. The default value is application/json.

Available options:

application/json,

application/hal+json,

application/xml,

text/xml,

text/csv

Path Parameters

playbookId

string

required

The unique identifier for the Playbook.

Required string length: 24

Pattern: ^[a-z0-9]{24}$

Body

application/json

entrypoint

string

The unique identifier for the Snapshot or Project used for the Playbook run.

Example:

"61f25579055c2f43c249a181"

flowId

string

The Flow ID for the Playbook run.

Example:

"010d1970-89b9-4012-892b-53c78ef6c117"

localeId

string

The Locale ID for the Playbook run.

Example:

"8b3b45e2-48f9-446d-a4c5-35d8284a01b2"

Response

Playbook run successfully scheduled.

Created task metadata (same shape as ITaskReturnValue).

_id

string

Required string length: 24

Pattern: ^[a-z0-9]{24}$

status

string

Task status (e.g. queued, active, done)

Example:

"queued"

type

string

Task type (e.g. runPlaybook)

Example:

"runPlaybook"

parameters

object

Task payload (playbookId, projectId, entrypoint, flowId, localeId, etc.)

createdAt

number

Unix timestamp in seconds when the task was created

lastChangedAt

number

Unix timestamp in seconds when the task was last updated

progress

integer

Task progress (0-100)

Required range: 0 <= x <= 100

job

object

Present only when the task runs as a Kubernetes job

Show child attributes

Last modified on July 22, 2026

Create a Playbook StepCreates a step in a [Playbook](https://docs.cognigy.com/ai/agents/test/playbooks).

Schedule a Playbook Run

curl --request POST \
  --url https://api-trial.cognigy.ai/new/v2.0/playbooks/{playbookId}/schedule \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "entrypoint": "61f25579055c2f43c249a181",
  "flowId": "010d1970-89b9-4012-892b-53c78ef6c117",
  "localeId": "8b3b45e2-48f9-446d-a4c5-35d8284a01b2"
}
'

import requests

url = "https://api-trial.cognigy.ai/new/v2.0/playbooks/{playbookId}/schedule"

payload = {
    "entrypoint": "61f25579055c2f43c249a181",
    "flowId": "010d1970-89b9-4012-892b-53c78ef6c117",
    "localeId": "8b3b45e2-48f9-446d-a4c5-35d8284a01b2"
}
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    entrypoint: '61f25579055c2f43c249a181',
    flowId: '010d1970-89b9-4012-892b-53c78ef6c117',
    localeId: '8b3b45e2-48f9-446d-a4c5-35d8284a01b2'
  })
};

fetch('https://api-trial.cognigy.ai/new/v2.0/playbooks/{playbookId}/schedule', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api-trial.cognigy.ai/new/v2.0/playbooks/{playbookId}/schedule",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'entrypoint' => '61f25579055c2f43c249a181',
    'flowId' => '010d1970-89b9-4012-892b-53c78ef6c117',
    'localeId' => '8b3b45e2-48f9-446d-a4c5-35d8284a01b2'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api-trial.cognigy.ai/new/v2.0/playbooks/{playbookId}/schedule"

	payload := strings.NewReader("{\n  \"entrypoint\": \"61f25579055c2f43c249a181\",\n  \"flowId\": \"010d1970-89b9-4012-892b-53c78ef6c117\",\n  \"localeId\": \"8b3b45e2-48f9-446d-a4c5-35d8284a01b2\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api-trial.cognigy.ai/new/v2.0/playbooks/{playbookId}/schedule")
  .header("X-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"entrypoint\": \"61f25579055c2f43c249a181\",\n  \"flowId\": \"010d1970-89b9-4012-892b-53c78ef6c117\",\n  \"localeId\": \"8b3b45e2-48f9-446d-a4c5-35d8284a01b2\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api-trial.cognigy.ai/new/v2.0/playbooks/{playbookId}/schedule")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"entrypoint\": \"61f25579055c2f43c249a181\",\n  \"flowId\": \"010d1970-89b9-4012-892b-53c78ef6c117\",\n  \"localeId\": \"8b3b45e2-48f9-446d-a4c5-35d8284a01b2\"\n}"

response = http.request(request)
puts response.read_body

{
  "_id": "<string>",
  "status": "queued",
  "type": "runPlaybook",
  "parameters": {},
  "createdAt": 123,
  "lastChangedAt": 123,
  "progress": 50,
  "job": {
    "name": "<string>",
    "namespace": "<string>",
    "timeoutInMs": 123
  }
}

{
  "type": "Bad Request",
  "title": "Bad Request Error",
  "status": 400,
  "detail": "Validation failed. Missing payload.",
  "instance": "/v2.0/flows/5ce7c2d833ea1e04d7e6c432",
  "code": 1000,
  "traceId": "api--f84324f4-98eb-4f02-abdd-375a2e6c3c1f",
  "details": {}
}

{
  "type": "Unauthorized",
  "title": "Unauthorized Error",
  "status": 401,
  "detail": "<string>",
  "instance": "/v2.0/flows/5ce7c2d833ea1e04d7e6c432",
  "code": 401,
  "traceId": "api--f84324f4-98eb-4f02-abdd-375a2e6c3c1f",
  "details": {}
}

{
  "type": "Payment Required",
  "title": "Payment Required Error",
  "status": 402,
  "detail": "Validation failed. Missing payload.",
  "instance": "/v2.0/flows/5ce7c2d833ea1e04d7e6c432",
  "code": 402,
  "traceId": "api--f84324f4-98eb-4f02-abdd-375a2e6c3c1f",
  "details": {}
}

{
  "type": "Forbidden",
  "title": "Forbidden Error",
  "status": 403,
  "detail": "<string>",
  "instance": "/v2.0/flows/5ce7c2d833ea1e04d7e6c432",
  "code": 1000,
  "traceId": "api--f84324f4-98eb-4f02-abdd-375a2e6c3c1f",
  "details": {}
}

{
  "type": "Not Found",
  "title": "Not Found Error",
  "status": 404,
  "detail": "<string>",
  "instance": "/v2.0/flows/5ce7c2d833ea1e04d7e6c432",
  "code": 1000,
  "traceId": "api--f84324f4-98eb-4f02-abdd-375a2e6c3c1f",
  "details": {},
  "logLevel": "error"
}

{
  "type": "Method Not Allowed",
  "title": "Method Not Allowed Error",
  "status": 405,
  "detail": "<string>",
  "instance": "/v2.0/flows/5ce7c2d833ea1e04d7e6c432",
  "code": 1000,
  "traceId": "api--f84324f4-98eb-4f02-abdd-375a2e6c3c1f",
  "details": {}
}

{
  "type": "Conflict",
  "title": "Conflict Error",
  "status": 409,
  "detail": "<string>",
  "instance": "/v2.0/flows/5ce7c2d833ea1e04d7e6c432",
  "code": 1004,
  "traceId": "api--f84324f4-98eb-4f02-abdd-375a2e6c3c1f",
  "details": {}
}

{
  "type": "Payload Too Large",
  "title": "Payload Too Large Error",
  "status": 413,
  "detail": "<string>",
  "instance": "/v2.0/flows/5ce7c2d833ea1e04d7e6c432",
  "code": 1000,
  "traceId": "api--f84324f4-98eb-4f02-abdd-375a2e6c3c1f",
  "details": {}
}

{
  "type": "Internal Server Error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "<string>",
  "instance": "/v2.0/flows/5ce7c2d833ea1e04d7e6c432",
  "code": 1000,
  "traceId": "api--f84324f4-98eb-4f02-abdd-375a2e6c3c1f",
  "details": {}
}

{
  "type": "Not Implemented",
  "title": "Not Implemented Error",
  "status": 501,
  "detail": "<string>",
  "instance": "/v2.0/flows/5ce7c2d833ea1e04d7e6c432",
  "code": 1009,
  "traceId": "api--f84324f4-98eb-4f02-abdd-375a2e6c3c1f",
  "details": {}
}

{
  "type": "Bad Gateway",
  "title": "Bad Gateway Error",
  "status": 502,
  "detail": "<string>",
  "instance": "/v2.0/flows/5ce7c2d833ea1e04d7e6c432",
  "code": 1000,
  "traceId": "api--f84324f4-98eb-4f02-abdd-375a2e6c3c1f",
  "details": {}
}

{
  "type": "Service Unavailable",
  "title": "Service Unavailable Error",
  "status": 503,
  "detail": "<string>",
  "instance": "/v2.0/flows/5ce7c2d833ea1e04d7e6c432",
  "code": 503,
  "traceId": "api--f84324f4-98eb-4f02-abdd-375a2e6c3c1f",
  "details": {}
}

{
  "type": "Gateway Timeout",
  "title": "Gateway Timeout Error",
  "status": 504,
  "detail": "<string>",
  "instance": "/v2.0/flows/5ce7c2d833ea1e04d7e6c432",
  "code": 1000,
  "traceId": "api--f84324f4-98eb-4f02-abdd-375a2e6c3c1f",
  "details": {}
}

Overview

Core Resources

Simulator

Authorizations

Headers

Path Parameters

Body

Response