Playbooks

Playbooks are the reusable workflow definitions behind launches.

If workflows are execution records, playbooks are the durable authored process contract that those records instantiate.

Main Routes

• POST /api/v1/playbooks
• GET /api/v1/playbooks
• GET /api/v1/playbooks/:id
• PATCH /api/v1/playbooks/:id
• PUT /api/v1/playbooks/:id
• PATCH /api/v1/playbooks/:id/archive
• GET /api/v1/playbooks/:id/delete-impact
• DELETE /api/v1/playbooks/:id
• DELETE /api/v1/playbooks/:id/permanent

Community Catalog Overlay

The platform also exposes a catalog-import overlay for agirunner-playbooks.

These routes do not replace normal playbook CRUD. They exist to browse the shared catalog, preview one import at a time, and materialize tenant-local copies.

Catalog Routes

• GET /api/v1/community-catalog/playbooks
• GET /api/v1/community-catalog/playbooks/:id
• POST /api/v1/community-catalog/playbooks/:id/import-preview
• POST /api/v1/community-catalog/playbooks/:id/import

List Community Playbooks

GET /api/v1/community-catalog/playbooks

Scope: admin

Response:

{
  "data": [
    {
      "id": "bug-fix",
      "name": "Bug Fix",
      "summary": "Diagnose and fix a bounded defect with review, security review, QA verification, and human release approval.",
      "category": "engineering",
      "stability": "experimental",
      "version": "1.0.0"
    }
  ]
}

Catalog List Fields

Field	Contract	Meaning
id	fixed string	Flat catalog id for the community playbook.
name	string	Human-facing catalog name.
summary	string	Short operator-facing explanation used in import browsing.
category	enum-like string	Catalog category such as engineering, operations, research, compliance, or content.
stability	enum-like string	Catalog stability marker such as stable or experimental.
version	string	Catalog version, separate from the local tenant playbook revision counter.

Get Community Playbook Detail

GET /api/v1/community-catalog/playbooks/:id

Scope: admin

Response:

{
  "data": {
    "id": "bug-fix",
    "name": "Bug Fix",
    "summary": "Diagnose and fix a bounded defect with review, security review, QA verification, and human release approval.",
    "category": "engineering",
    "stability": "experimental",
    "version": "1.0.0",
    "readme_markdown": "# Bug Fix\n\nUse this playbook for a bounded defect...",
    "stages": [
      "reproduce",
      "implementation",
      "review",
      "verification",
      "release-approval"
    ],
    "specialist_ids": [
      "developer",
      "reviewer",
      "security-reviewer",
      "qa-reviewer"
    ],
    "skill_ids": [
      "bug-reproduction-discipline",
      "code-review-rubric",
      "security-review-rubric",
      "regression-proof-required"
    ]
  }
}

Detail Fields

Field	Contract	Meaning
readme_markdown	string	Human-facing catalog README shown on demand in the import flow.
stages	string[]	Preview-only stage names extracted from the catalog artifact.
specialist_ids	fixed string[]	Catalog specialist references this playbook depends on.
skill_ids	fixed string[]	Catalog skill references that arrive through imported specialists.

Import Preview

POST /api/v1/community-catalog/playbooks/:id/import-preview

Scope: admin

No request body is required.

Response:

{
  "data": {
    "playbook": {
      "id": "bug-fix",
      "version": "1.0.0"
    },
    "conflicts": [
      {
        "artifact_type": "playbook",
        "catalog_id": "bug-fix",
        "local_match": {
          "id": "11111111-1111-1111-1111-111111111111",
          "name": "Bug Fix",
          "version": 3
        },
        "allowed_actions": [
          "create_new",
          "override_existing"
        ]
      }
    ]
  }
}

Preview Fields

Field	Contract	Meaning
artifact_type	enum-like string	Which imported artifact type has a local conflict: playbook, specialist, or skill.
catalog_id	fixed string	Catalog artifact id that may be imported.
local_match	server-generated object or null	Existing tenant-local artifact that conflicts with the import candidate.
allowed_actions	fixed string[]	Conflict actions supported by the importer, currently create_new and override_existing.

Import

POST /api/v1/community-catalog/playbooks/:id/import

Scope: admin

Request:

{
  "decisions": [
    {
      "artifact_type": "playbook",
      "catalog_id": "bug-fix",
      "action": "create_new"
    },
    {
      "artifact_type": "specialist",
      "catalog_id": "developer",
      "action": "override_existing"
    }
  ]
}

Import Request Fields

Field	Required	Contract	Meaning
decisions	No	structured object[]	Optional conflict-resolution decisions chosen from the preview step.
artifact_type	Yes	enum-like string	Imported artifact type being resolved.
catalog_id	Yes	fixed string	Catalog artifact id being resolved.
action	Yes	fixed string	Conflict action, currently create_new or override_existing.

Response:

{
  "data": {
    "import_batch_id": "22222222-2222-2222-2222-222222222222",
    "playbook": {
      "id": "33333333-3333-3333-3333-333333333333",
      "name": "Bug Fix",
      "version": 1
    },
    "imported_specialists": [
      "developer",
      "reviewer",
      "security-reviewer",
      "qa-reviewer"
    ],
    "imported_skills": [
      "bug-reproduction-discipline",
      "code-review-rubric",
      "security-review-rubric",
      "regression-proof-required"
    ],
    "provenance": {
      "source_repository": "agirunner/agirunner-playbooks",
      "catalog_version": "1.0.0"
    }
  }
}

Imported artifacts become normal tenant-local copies after this route returns. The platform keeps quiet provenance metadata, but v1 does not try to maintain live upstream sync.

Create Playbook

POST /api/v1/playbooks

Scope: admin

Request body

{
  "name": "Release Review",
  "slug": "release-review",
  "description": "Review release readiness and route follow-up work.",
  "outcome": "A release decision with explicit follow-up tasks.",
  "lifecycle": "planned",
  "definition": {
    "roles": [
      {
        "name": "reviewer"
      }
    ],
    "stages": [
      {
        "name": "Review"
      }
    ]
  }
}

Required fields

• name
• outcome
• definition

Request fields

Field	Required	Contract	Meaning
name	Yes	string	Human-facing playbook name.
slug	No	string	Stable short identifier for URLs and operator references.
description	No	string	Operator-facing explanation of what the playbook is for.
outcome	Yes	string	The intended end result of the workflow family this playbook defines.
lifecycle	No	enum	High-level execution model for the playbook, currently planned or ongoing.
definition	Yes	authored structured object	The actual playbook definition. The route accepts JSON, but the platform interprets stage, role, board, and workflow structure from it.

Response

{
  "data": {
    "id": "11111111-1111-1111-1111-111111111111",
    "name": "Release Review",
    "slug": "release-review",
    "description": "Review release readiness and route follow-up work.",
    "outcome": "A release decision with explicit follow-up tasks.",
    "lifecycle": "planned",
    "version": 1,
    "is_active": true,
    "definition": {
      "roles": [
        {
          "name": "reviewer"
        }
      ],
      "stages": [
        {
          "name": "Review"
        }
      ]
    },
    "created_at": "2026-03-31T18:55:00.000Z",
    "updated_at": "2026-03-31T18:55:00.000Z"
  }
}

Response fields

Field	Contract	Meaning
id	server-generated	Canonical playbook id.
version	server-generated	Active revision number for the playbook family.
is_active	server-generated	Whether this revision is currently active.
definition	authored structured object	Stored playbook definition for this revision.

List And Get

List

GET /api/v1/playbooks

Scope: agent

Response:

{
  "data": [
    {
      "id": "11111111-1111-1111-1111-111111111111",
      "name": "Release Review",
      "slug": "release-review",
      "version": 1,
      "is_active": true
    }
  ]
}

Get

GET /api/v1/playbooks/:id

Scope: agent

Returns the full active revision, including definition.

Patch Vs Replace

Patch

PATCH /api/v1/playbooks/:id

Scope: admin

Use patch when changing only selected fields:

{
  "description": "Expanded release review process.",
  "outcome": "A release decision with follow-up records."
}

Replace

PUT /api/v1/playbooks/:id

Scope: admin

Use replace when sending a full new declarative revision. The route uses the same body shape as create.

Both patch and replace create a new active revision in the playbook family rather than mutating history in place.

Archive

PATCH /api/v1/playbooks/:id/archive

Scope: admin

Request body

{
  "archived": true
}

Archive fields

Field	Contract	Meaning
archived	boolean	Whether the playbook should move into or out of archived state.

Response

Returns the resulting playbook record with is_active updated.

Delete Impact

GET /api/v1/playbooks/:id/delete-impact

Scope: admin

Use this route before destructive changes. It returns a structured impact summary describing downstream dependencies.

Delete

Soft dependency-aware delete

DELETE /api/v1/playbooks/:id

Scope: admin

If workflows still reference the playbook, the route can return a conflict instead of deleting it.

Success response:

{
  "data": {
    "id": "11111111-1111-1111-1111-111111111111",
    "deleted": true
  }
}

Permanent delete

DELETE /api/v1/playbooks/:id/permanent

Scope: admin

This route is the more forceful destructive path and is intended for explicit cleanup flows rather than normal operator editing.