Cognition Labs Playbooks API

openapi: 3.2.0
info:
  title: Cognition Labs Playbooks API
  version: '1.0'
  description: 'Operations tagged Playbooks across 2 of this provider''s published API definitions: cognition-labs-openapi.yml, cognition-labs-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.devin.ai/v1
  description: Legacy v1 API (apk_user_*/apk_* keys)
- url: https://api.devin.ai/v3
  description: Current v3 organizations/enterprise API (cog_ keys)
- url: https://api.devin.ai
  description: Devin Production Server
security:
- bearerAuth: []
tags:
- name: Playbooks
  description: Reusable team playbooks that seed new sessions.
paths:
  /playbooks:
    get:
      operationId: listPlaybooks
      tags:
      - Playbooks
      summary: List all team playbooks
      responses:
        '200':
          description: The organization's playbooks.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Playbook'
    post:
      operationId: createPlaybook
      tags:
      - Playbooks
      summary: Create a playbook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlaybookInput'
      responses:
        '200':
          description: The created playbook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Playbook'
        '422':
          $ref: '#/components/responses/ValidationError'
    servers:
    - url: https://api.devin.ai/v1
      description: Legacy v1 API (apk_user_*/apk_* keys)
    - url: https://api.devin.ai/v3
      description: Current v3 organizations/enterprise API (cog_ keys)
  /playbooks/{playbook_id}:
    parameters:
    - name: playbook_id
      in: path
      required: true
      schema:
        type: string
    get:
      operationId: getPlaybook
      tags:
      - Playbooks
      summary: Get a playbook
      responses:
        '200':
          description: The requested playbook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Playbook'
        '422':
          $ref: '#/components/responses/ValidationError'
    put:
      operationId: updatePlaybook
      tags:
      - Playbooks
      summary: Update a playbook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlaybookInput'
      responses:
        '200':
          description: The updated playbook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Playbook'
        '422':
          $ref: '#/components/responses/ValidationError'
    delete:
      operationId: deletePlaybook
      tags:
      - Playbooks
      summary: Delete a playbook
      responses:
        '200':
          description: Deletion confirmation.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
        '422':
          $ref: '#/components/responses/ValidationError'
    servers:
    - url: https://api.devin.ai/v1
      description: Legacy v1 API (apk_user_*/apk_* keys)
    - url: https://api.devin.ai/v3
      description: Current v3 organizations/enterprise API (cog_ keys)
  /v1/playbooks:
    get:
      tags:
      - Playbooks
      summary: List playbooks
      description: Retrieve all team playbooks accessible to your organization. Only team playbooks are returned via the API.
      responses:
        '200':
          description: List of playbooks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PlaybookResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
      operationId: getV1Playbooks
      x-operation-id-source: derived
    post:
      tags:
      - Playbooks
      summary: Create playbook
      description: Create a new team playbook. Requires ManageOrgPlaybooks permission.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePlaybookRequest'
      responses:
        '200':
          description: Playbook created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaybookResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
      operationId: postV1Playbooks
      x-operation-id-source: derived
    servers:
    - url: https://api.devin.ai
      description: Devin Production Server
  /v1/playbooks/{playbook_id}:
    get:
      tags:
      - Playbooks
      summary: Get playbook
      description: Retrieve details of a specific playbook by its ID.
      parameters:
      - name: playbook_id
        in: path
        required: true
        description: The ID of the playbook to retrieve
        schema:
          type: string
      responses:
        '200':
          description: Playbook details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlaybookResponse'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      operationId: getV1PlaybooksByPlaybookId
      x-operation-id-source: derived
    put:
      tags:
      - Playbooks
      summary: Update playbook
      description: 'Update an existing team playbook. Requires ManageOrgPlaybooks permission.

        Only team playbooks can be updated.'
      parameters:
      - name: playbook_id
        in: path
        required: true
        description: The ID of the playbook to update
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePlaybookRequest'
      responses:
        '200':
          description: Playbook updated successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      operationId: putV1PlaybooksByPlaybookId
      x-operation-id-source: derived
    delete:
      tags:
      - Playbooks
      summary: Delete playbook
      description: 'Delete a team playbook. Requires ManageOrgPlaybooks permission.

        This marks the playbook as deleted and removes any associated macro.'
      parameters:
      - name: playbook_id
        in: path
        required: true
        description: The ID of the playbook to delete
        schema:
          type: string
      responses:
        '200':
          description: Playbook deleted successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    example: success
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
      operationId: deleteV1PlaybooksByPlaybookId
      x-operation-id-source: derived
    servers:
    - url: https://api.devin.ai
      description: Devin Production Server
components:
  schemas:
    Playbook:
      allOf:
      - $ref: '#/components/schemas/PlaybookInput'
      - type: object
        properties:
          playbook_id:
            type: string
          status:
            type: string
          org_id:
            type: string
          created_at:
            type:
            - string
            - 'null'
            format: date-time
          updated_at:
            type:
            - string
            - 'null'
            format: date-time
          created_by_user_id:
            type:
            - string
            - 'null'
          created_by_user_name:
            type:
            - string
            - 'null'
    ValidationErrorBody:
      type: object
      properties:
        detail:
          type: array
          items:
            type: object
            properties:
              loc:
                type: array
                items:
                  type: string
              msg:
                type: string
              type:
                type: string
    PlaybookInput:
      type: object
      required:
      - title
      - body
      properties:
        title:
          type: string
        body:
          type: string
        macro:
          type: string
        access_type:
          type: string
    PlaybookResponse:
      type: object
      description: Response object for playbook operations
      properties:
        playbook_id:
          type: string
          description: Unique identifier for the playbook
        title:
          type: string
          description: The title of the playbook
        body:
          type: string
          description: The content/instructions of the playbook
        status:
          type: string
          description: Status of the playbook (published, deleted, etc.)
        access_type:
          type: string
          description: Access level of the playbook (team, community, etc.)
        org_id:
          type: string
          description: Organization ID that owns the playbook
        created_at:
          type: string
          format: date-time
          description: When the playbook was created
        updated_at:
          type: string
          format: date-time
          description: When the playbook was last updated
        created_by_user_id:
          type: string
          nullable: true
          description: ID of the user who created the playbook
        created_by_user_name:
          type: string
          nullable: true
          description: Name of the user who created the playbook
        updated_by_user_id:
          type: string
          nullable: true
          description: ID of the user who last updated the playbook
        updated_by_user_name:
          type: string
          nullable: true
          description: Name of the user who last updated the playbook
        macro:
          type: string
          nullable: true
          description: Optional macro shortcut for the playbook
    CreatePlaybookRequest:
      type: object
      description: Request body for creating or updating a playbook
      properties:
        title:
          type: string
          minLength: 1
          description: The title of the playbook
        body:
          type: string
          minLength: 1
          description: The content/instructions of the playbook
        macro:
          type: string
          nullable: true
          description: Optional macro shortcut for the playbook (e.g., !deploy)
      required:
      - title
      - body
  responses:
    ValidationError:
      description: The request payload failed validation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ValidationErrorBody'
    BadRequestError:
      description: Bad Request
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: string
                example: Invalid input or request
    UnauthorizedError:
      description: Unauthorized - Invalid or missing API key
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: string
                example: Missing or invalid Authorization header
    NotFoundError:
      description: Resource not found
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: string
                example: The requested resource does not exist
    ForbiddenError:
      description: Forbidden - User does not have permission to access the resource
      content:
        application/json:
          schema:
            type: object
            properties:
              detail:
                type: string
                example: You do not have permission to access this resource
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'v1/v2 keys are prefixed apk_user_* (personal) or apk_* (service). The current v3 API uses service-user or personal access tokens prefixed cog_. Passed as `Authorization: Bearer YOUR_API_KEY`.'
externalDocs:
  description: Visit Devin's documentation page for more info
  url: https://docs.devin.ai
x-refined-from:
- cognition-labs-openapi.yml
- cognition-labs-openapi.yaml