Playbook Triggers and Delivery

Your playbooks, callable from anywhere. Playbooks can be triggered by external systems, deliver results automatically, and are fully manageable through MCP tools – making them building blocks for larger automation workflows.

Trigger URLs

Trigger URLs give each playbook a dedicated HTTP endpoint that external systems can POST to. This turns any playbook into an on-demand API.

How They Work

1. Open a playbook and go to the Delivery tab
2. Enable Trigger URL
3. Copy the generated URL and bearer token

External systems POST to the trigger URL with input values. Promptmark validates the inputs against the playbook’s ## INPUTS schema, queues the execution, and returns immediately.

Request Format

curl -X POST https://promptmark.ai/api/playbooks/{id}/trigger \
  -H "Authorization: Bearer {trigger_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "topic": "Kubernetes security",
      "audience": "senior engineers"
    },
    "model_id": "anthropic/claude-sonnet-4"
  }'

Response

{
  "execution_id": "exec_abc123",
  "status": "queued"
}

The response is 202 Accepted. The execution runs asynchronously. Poll the execution status via the REST API or configure output delivery (below) to receive results.

Authentication

Each trigger URL has its own bearer token, independent of your account JWT. You can regenerate the token at any time (which invalidates the previous one). Trigger tokens grant access only to that specific playbook’s execution endpoint – they cannot read, modify, or delete any data.

Rate Limiting

Trigger URLs are rate-limited per playbook. Exceeding the limit returns 429 Too Many Requests with a Retry-After header.

Use Cases

• CI/CD pipelines – Run a code review playbook on every pull request
• Slack bots – Trigger a content brief from a slash command
• Zapier / Make / n8n – Wire playbooks into no-code workflows
• Cron jobs – Schedule weekly report generation

Output Delivery

Instead of polling for results, configure a playbook to push its output somewhere when execution completes (or fails).

Webhook

Fire an HTTP POST to a URL of your choice on completion or failure.

Configuration:

• URL – The endpoint to receive the payload
• Bearer token – Sent in the Authorization header

Payload format:

{
  "event": "execution.completed",
  "execution_id": "exec_abc123",
  "playbook_id": "pb_xyz789",
  "playbook_title": "Code Review",
  "status": "completed",
  "started_at": "2026-03-26T10:00:00Z",
  "completed_at": "2026-03-26T10:02:15Z",
  "steps": [
    {
      "number": 1,
      "title": "Analyze PR Diff",
      "status": "completed",
      "tokens": 1250,
      "cost": 0.0038
    }
  ],
  "outputs": {
    "summary": "No critical issues found. Two style suggestions.",
    "risk_level": "low"
  },
  "artifact": {
    "type": "markdown",
    "content": "## Code Review Summary\n..."
  },
  "totals": {
    "tokens": 4800,
    "cost": 0.0142,
    "latency_ms": 135000
  }
}

The event field is either execution.completed or execution.failed. Failed executions include an error field with the failure reason and the last successful step number.

Email

Send results to one or more email addresses when execution completes. The email contains a formatted summary with step results, outputs, and a link to the full execution in Promptmark.

GitHub

Push artifacts to a repository on completion. Useful for playbooks that generate documentation, config files, or reports that belong in version control.

Configuration

All delivery methods are configured per-playbook in Settings > Delivery. You can enable multiple methods simultaneously – for example, webhook to your Slack bot and email to stakeholders.

MCP Tools

Playbooks are fully manageable via MCP. The 13 playbook tools cover the complete lifecycle: authoring, validation, execution, breakpoints, elicitation, versioning, and result retrieval.

CRUD Tools

Execution Tools

Version Tools

Execution Flow via MCP

A typical MCP execution looks like this:

1. execute_playbook(playbook_id, input_values, breakpoints: "3")
   → status: "paused", execution_id: "exec_abc123"

2. get_playbook_execution(execution_id)
   → review step 1-2 results, inspect variables

3. resume_playbook_execution(execution_id, variables: {override: "new value"})
   → status: "awaiting_input" (step 4 has @elicit)

4. respond_to_elicitation(execution_id, response: "yes, proceed")
   → status: "completed", outputs: {...}, artifact: {...}

For full parameter schemas, defaults, and return types, see the MCP Reference.

Use Cases

Run a Code Review Playbook from CI on Every PR

Set up a CI step that triggers a code review playbook when a pull request is opened. The playbook analyzes the diff across multiple steps – security review, style check, complexity analysis – and posts a summary comment.

With trigger URLs :

# GitHub Actions example
- name: Run code review playbook
  run: |
    curl -X POST https://promptmark.example.com/api/playbooks/pb_review/trigger \
      -H "Authorization: Bearer ${{ secrets.PLAYBOOK_TRIGGER_TOKEN }}" \
      -d '{"inputs": {"diff": "${{ steps.diff.outputs.content }}"}}'

With MCP today: An AI assistant with MCP access can call execute_playbook with the diff as input, then post the results back to the PR.

Generate Weekly Reports and Email Them

A playbook that gathers metrics, analyzes trends, and produces a formatted report. Schedule it with a cron job or workflow automation tool.

Steps in the playbook:

1. Gather raw data (provided as input)
2. Analyze trends and anomalies
3. Generate executive summary
4. Format as a polished report (artifact type: markdown)

With output delivery : Configure email delivery to send the artifact to your team every Monday morning.

Slack Bot Triggers a Content Brief

A Slack bot listens for a slash command like /brief "Q2 product launch", triggers a content brief playbook, and webhooks the result back to the channel.

Flow:

1. User types /brief "Q2 product launch" in Slack
2. Bot POSTs to the playbook’s trigger URL with {"inputs": {"topic": "Q2 product launch"}}
3. Playbook runs: research step, outline step, draft step
4. Webhook fires on completion, bot posts the brief back to the channel

With MCP today: Connect your Slack bot to an AI assistant that has Promptmark MCP access. The assistant calls execute_playbook and returns the result to Slack.