> For the complete documentation index, see [llms.txt](https://docs.airops.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.airops.com/mcp-server/tools-and-support/tools/playbooks-and-workflows.md).
# Playbooks & Workflows
Read and edit Playbooks and Artifacts, review feedback, and run Playbooks and Workflows.
Read and edit Playbooks and Artifacts, review feedback, and run Playbooks and Workflows.
See [plan access](broken://pages/GlhqboJgu5fTfPseY3y1#plan-access) and [query options](broken://pages/GlhqboJgu5fTfPseY3y1#query-options) for shared requirements.
## Playbooks & Feedback
Read and edit Playbook drafts, inspect and edit Session outputs, review comments, and run or publish Playbooks with your existing workspace permissions. Draft edits, Artifact edits, publishing, and running require user OAuth authentication. Runs can consume workspace credits and perform the actions configured in the Playbook.
### `list_playbooks`
List editable Playbooks, including draft and active-version metadata.
**Requires:** `workspace_id`
**Optional:** `search` (title), `page` (default 1), `per_page` (default 20, maximum 50).
### `get_playbook`
Read a Playbook's configuration and definition as Markdown. Integration references do not expose credentials.
**Requires:** `playbook_id`
**Optional:** `version_number`. Omit it to read the current draft (**Latest**); provide a number to read an immutable published version.
### `read_playbook_draft_content`
Read live editor nodes before editing a Playbook's draft. Use `get_playbook` for the complete configuration or a published version.
**Requires:** `playbook_id`
**Optional:** `fragment` (`definition`, `title`, or `description`; defaults to `definition`) and `from` (zero-based top-level node index, default 0).
The returned nodes include `attrs._hash` targets for definition edits. Read the relevant fragment again after an edit to verify the saved content.
### `edit_playbook_definition`
Apply targeted edits to the draft instructions. Other configuration and existing Human Review settings are preserved. The changes remain a draft until you publish.
**Requires:** `playbook_id`, `operations`, and user OAuth authentication with permission to update the Playbook.
Each operation contains `type` (`replace`, `insertBefore`, or `insertAfter`), `target`, and `content` (editor JSON nodes). Use targets from `read_playbook_draft_content`; an empty replacement removes the selected node. Preserve existing reference IDs and section identities when copying content.
Node hashes identify targets, not content revisions. Coordinate edits to the same content and read back the result. If an edit reports an uncertain outcome, read the draft before retrying because the change may already have applied.
### `edit_playbook_title` and `edit_playbook_description`
Replace only the selected draft fragment. Read it first with `read_playbook_draft_content`.
**Requires:** `playbook_id`, `content` (the replacement editor nodes), and user OAuth authentication with update permission.
These tools do not publish the Playbook or replace its other fields.
### `list_playbook_references`
List the draft's input, artifact, or trigger references and their IDs.
**Requires:** `playbook_id`, `reference_type` (`input`, `artifact`, or `trigger`).
Use returned IDs when editing configuration or inserting references into the definition. Content Review configuration bodies are not exposed.
### `manage_playbook_input_reference`
Create one Input or update an existing Input without replacing the rest of the collection.
**Requires:** `playbook_id`, `name`, `label`, and `interface`.
**Optional:** `id` to update an existing Input, plus the optional fields advertised in the tool schema. Omitted optional fields retain their current values.
Mutations require user OAuth and update permission. After creating an Input, use its returned ID with `edit_playbook_definition` to reference it in the instructions. Changes remain a draft.
### `delete_playbook_input_reference`
Delete one draft Input after removing its references from the definition. If Content Review uses the Input, update that configuration in the web editor first.
**Requires:** `playbook_id`, `id`, and user OAuth with update permission.
The tool rejects deletion while the Input is still in use. Other Inputs and published versions remain unchanged.
### `manage_playbook_artifact_reference`
Create or update the configuration for one draft Artifact. This tool changes the expected output, not an existing Session's output file.
**Requires:** `playbook_id`, `name`, `artifact_type`, and user OAuth with update permission.
**Optional:** `id` to update an existing Artifact. Use the tool schema for any supported comparison fields.
Other Artifacts and retained Content Review configurations remain unchanged. Use the returned ID with `edit_playbook_definition` to reference a new Artifact. The tool does not publish.
### `delete_playbook_artifact_reference`
Delete one draft Artifact configuration after removing its references from the definition.
**Requires:** `playbook_id`, `id`, and user OAuth with update permission.
Deletion also removes that Artifact's Content Review configuration. Other Artifacts, published versions, and existing Session output files remain unchanged.
### `list_playbook_tools`
Inspect the workspace-aware tool catalog before adding tools to a Playbook.
**Requires:** `playbook_id`
Each entry includes an ID, a category (`step`, `mcp`, or `sdk`), and a status. `enabled` tools are already configured; `available` tools can be enabled; `installable` connectors must first be installed in the workspace.
### `update_playbook_tools`
Enable tools without removing those already configured.
**Requires:** `playbook_id`, `tools` (entries containing `id` and `category` copied from the catalog), and user OAuth with update permission.
Install connectors marked `installable` in the app first. This tool changes draft tool configuration; use `edit_playbook_definition` to add instruction references and `publish_playbook` when the draft is ready.
### `list_playbook_sessions`
List Sessions in reverse chronological order.
**Requires:** `workspace_id`
**Optional:** `playbook_id`, `status`, `search` (Session or creator name), `page` (default 1), `per_page` (default 20, maximum 50). Archived Sessions use the public status `archived`.
### `get_playbook_session`
Inspect Session metadata and a page of events, including text, tool results, artifacts, and completion state.
**Requires:** `session_id`
**Optional:** `after_id` (event cursor), `limit` (default 20, maximum 50).
Pass the returned `next_after_id` as `after_id` to continue until it is `null`. Text previews are capped at 2,000 characters; `content_truncated: true` indicates that more text exists. Use `read_playbook_output` for the full output.
### `read_playbook_output`
Read one text output in character-based pages. Collaborative text artifacts reflect current editor content, including edits made after the run. Binary artifacts are unsupported.
**Requires:** `session_id` and exactly one of `event_id` or `artifact_path`. Artifact paths must identify a file under `artifacts/external/`.
**Optional:** `offset` (default 0), `max_chars` (default 20,000, maximum 200,000).
**Returns:** `content`, `offset`, `total_chars`, and `next_offset`. Pass `next_offset` back as `offset` until it is `null`.
### `read_artifact`
Read editable nodes from a collaborative Markdown, HTML, or CSV Artifact before changing its contents. Use `read_playbook_output` for ordinary text reads.
**Requires:** `session_id`, `artifact_path` (the exact emitted path under `artifacts/external/`).
**Optional:** `from` (zero-based top-level node index, default 0).
Use `get_playbook_session` to discover the emitted path. The Session must be settled and the collaborative Artifact must exist. The response includes node hashes and `content_type`; CSV Artifacts use table, row, and cell nodes. Binary and JSON Artifact editing are unsupported.
### `edit_artifact`
Edit selected nodes in an existing Session Artifact. Changes apply directly to that collaborative Artifact, preserving unrelated content and the Playbook configuration.
**Requires:** `session_id`, `artifact_path`, `operations`, and user OAuth with Session update and collaborative-editor write permission.
Read the Artifact first with `read_artifact`. Each operation uses `replace`, `insertBefore`, or `insertAfter`, a returned node hash as `target`, and editor nodes as `content`. An empty replacement removes the selected node. Whole-document targets are not accepted.
The editor creates a checkpoint before changes. Read back the Artifact to verify the result. Node hashes do not provide revision locking, so coordinate concurrent edits. After an uncertain write outcome, read again before deciding whether to retry.
### `list_artifact_comments`
Read reviewer comments with author, timestamps, resolution state, and available anchor or surrounding-text context.
**Requires:** `session_id`
**Optional:** `artifact_path` to limit results to one artifact.
Use the comments alongside `read_playbook_output` to review feedback in context. Tracked-change suggestions are counted separately in `suggestions_count`; they are not comment threads. This tool reads feedback without modifying it.
### `publish_playbook`
Publish the current draft as a new active version.
**Requires:** `playbook_id` and user OAuth authentication.
**Optional:** `notes` for the published version.
**Returns:** The active version ID and version metadata. Confirm the draft and publication intent before calling this tool; publishing makes the pending draft active.
### `run_playbook`
Start an asynchronous Session. Each call starts a new run.
**Requires:** `playbook_id` and user OAuth authentication.
**Optional:** `inputs` keyed by input name, `message`, and `version_number`.
By default, this runs the current draft (**Latest**). Pass `version_number` to run a specific published version. Running a draft does not publish it. Confirm the intended version, inputs, and execution before starting.
**Returns:** `session_id`, `session_uuid`, status, and version information. Poll `get_playbook_session`, then read outputs and comments as needed.
## Workflows
List executable Workflows and start or inspect runs with your workspace permissions. Runs can consume credits and perform the Workflow's configured actions.
### `list_workflows`
List published Workflows you can execute. Draft-only, deleted, agent, and legacy resources are excluded.
**Requires:** `workspace_id`
**Optional:** `search`, `page` (default 1), `per_page` (default 20, maximum 50).
### `run_workflow`
Start an asynchronous execution. Each call starts a new run.
**Requires:** `workflow_id`
**Optional:** `inputs` keyed by input name and `version_number`.
The default is the active published version. Pass `version_number` to select another published version. Confirm the intended Workflow, inputs, and execution before starting.
**Returns:** `execution_id`, status, and Workflow/version information.
### `get_workflow_execution`
Inspect a run's status, output, or error.
**Requires:** `execution_id` returned by `run_workflow`.
Poll this tool to follow the run through states such as `pending`, `running`, `review_needed`, `success`, `error`, or `cancelled`. A returned execution ID means the run started; check its status before treating its output as complete.
## Example: apply feedback and review a Playbook run
1. Find the Playbook with `list_playbooks` and inspect its definition with `get_playbook`.
2. Find a Session with `list_playbook_sessions`, then read its events with `get_playbook_session`.
3. Read the full text with `read_playbook_output` and reviewer feedback with `list_artifact_comments`.
4. For an instruction change, read the draft with `read_playbook_draft_content`, make a targeted definition edit, and verify it. For an output correction, use `read_artifact`, then `edit_artifact`, and read back the result.
5. Publish the draft when approved, run the intended version, and inspect its output to check whether it addresses the feedback. Editing a draft does not publish or run it automatically.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.airops.com/mcp-server/tools-and-support/tools/playbooks-and-workflows.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.