---
title: "submit playbook via the api"
method: POST
path: "/playbook/"
tags: ["playbook"]
---

# submit playbook via the api

`POST /playbook/`

submit a new playbook api

## 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

- 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

## Other responses

- `400` — Bad Request

## Changes

> 4 revisions in range; 1 not diffed.

- **2024-12-19** `94cf0fc80e59` — 1 info
  - added the non-success response with the status `400`
- **2024-04-08** `ac576881adde` — 1 info
  - endpoint added
- **2024-03-06** `53bae137e6cc` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/cossas/apis/soarca-api/changes/playbook/post.md)

---

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