---
title: "trigger a playbook by supplying a cacao playbook payload"
method: POST
path: "/trigger/playbook"
tags: ["trigger"]
---

# trigger a playbook by supplying a cacao playbook payload

`POST /trigger/playbook`

trigger playbook

## Request body

- CacaoPlaybook
  - `agent_definitions` CacaoAgentTargets
  - `authentication_info_definitions` CacaoAuthenticationInformations
  - `created` string, required — Timestamp of the creation of the playbook
  - `created_by` string, required — UUID referring to identity
  - `data_marking_definitions` CacaoDataMarkings
  - `derived_from` string[] — Playbook id that this playbook is derived from
  - `description` string — A descriptive text to indicate what your playbook does
  - `extension_definitions` CacaoExtensionDefinitions
  - `external_references` CacaoExternalReferences[] — List of external reference objects
    - `description` string
    - `external_id` string
    - `name` string, required
    - `reference_id` string
    - `source` string
    - `url` string
  - `id` string, required — Used by SOARCA so refer to the object while loading it from the database
  - `impact` integer — A priority number ranging 0 - 100
  - `labels` string[] — List of labels to label playbook
  - `markings` string[] — List of datamarking identifiers
  - `modified` string, required — Timestamp of the last modification of the playbook
  - `name` string, required — An indicative name of the playbook
  - `playbook_extensions` CacaoExtensions
  - `playbook_types` string[] — Should be of the CACAO playbook-type-ov
  - `playbook_variables` CacaoVariables
  - `priority` integer — A priority number ranging 0 - 100
  - `severity` integer — A priority number ranging 0 - 100
  - `spec_version` string, required — Indicate the specification version cacao-2.0 is the only supported version at this time
  - `target_definitions` CacaoAgentTargets
  - `type` string, required — Must be playbook
  - `valid_from` string — Timestamp from when the playbook is valid
  - `valid_until` string — Timestamp until when the playbook is valid
  - `workflow` CacaoWorkflow, required
  - `workflow_exception` string — Step that marks the actions that need to be taken when an exception occurs
  - `workflow_start` string, required — Start step of the playbook MUST be of step type START

## Response `200`

OK

- ApiExecution
  - `execution_id` string, required
  - `payload` string, required

## Other responses

- `400` — Bad Request

---

[API](https://skmtc.net/cossas/apis/soarca-api.md) · [All operations](https://skmtc.net/cossas/apis/soarca-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cossas/soarca-api/versions/5f7892d12e12/schema)