OpenProject Custom actions API

openapi: 3.2.0
info:
  description: You're looking at the current **stable** documentation of the OpenProject APIv3.
  title: OpenProject API V3 (Stable) Custom actions API
  version: '3'
servers:
- url: https://qa.openproject-edge.com
  description: Edge QA instance
- url: https://qa.openproject-stage.com
  description: Staging instance
- url: https://community.openproject.org
  description: Community instance
security:
- BasicAuth: []
tags:
- description: Custom actions are a preconfigured set of changes that are applied to a work package.
  name: Custom Actions
paths:
  /api/v3/custom_actions/{id}:
    get:
      summary: Get a custom action
      tags:
      - Custom Actions
      description: Retrieves a custom action by id.
      operationId: get_custom_action
      parameters:
      - name: id
        description: The id of the custom action to fetch
        in: path
        required: true
        schema:
          type: integer
        example: 42
      responses:
        '200':
          description: OK
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/CustomActionModel'
        '403':
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                message: You are not authorized to access this resource.
          description: 'Returned if the client does not have sufficient permissions.


            **Required permission:** edit work packages in any project'
        '404':
          description: Returned if the custom action does not exist.
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                _type: Error
                errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                message: The requested resource could not be found.
  /api/v3/custom_actions/{id}/execute:
    post:
      parameters:
      - description: The id of the custom action to execute
        example: 1
        in: path
        name: id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          headers: {}
        '400':
          $ref: '#/components/responses/InvalidRequestBody'
        '403':
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:MissingPermission
                    message: You are not authorized to access this resource.
          description: 'Returned if the client does not have sufficient permissions.


            **Required permission:** edit work packages - Additional permissions might be required based on the custom action.'
          headers: {}
        '404':
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:NotFound
                    message: The requested resource could not be found.
          description: Returned if the custom action does not exist.
          headers: {}
        '406':
          $ref: '#/components/responses/MissingContentType'
        '409':
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:UpdateConflict
                    message: Couldn't update the resource because of conflicting modifications.
          description: Returned if the client provided an outdated lockVersion or no lockVersion at all.
          headers: {}
        '415':
          $ref: '#/components/responses/UnsupportedMediaType'
        '422':
          content:
            application/hal+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                response:
                  value:
                    _embedded:
                      details:
                        attribute: lag
                    _type: Error
                    errorIdentifier: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
                    message: Lag must be a number greater than or equal to 0
          description: Returned if the custom action was not executed successfully e.g. when a constraint on a work package property was violated.
          headers: {}
      tags:
      - Custom Actions
      description: 'A POST to this endpoint executes the custom action on the work package provided in the payload. The altered work package will be returned. In order to avoid executing

        the custom action unbeknown to a change that has already taken place, the client has to provide the work package''s current lockVersion.'
      operationId: Execute_custom_action
      requestBody:
        content:
          application/json:
            schema:
              example:
                _links:
                  workPackage:
                    href: /api/v3/work_packages/42
                lockVersion: '3'
              properties:
                _links:
                  properties:
                    workPackage:
                      properties:
                        href:
                          type: string
                      type: object
                  type: object
                lockVersion:
                  type: string
              type: object
      summary: Execute custom action
components:
  responses:
    MissingContentType:
      description: Occurs when the client did not send a Content-Type header
      content:
        text/plain:
          schema:
            type: string
          example: Missing content-type header
    UnsupportedMediaType:
      description: Occurs when the client sends an unsupported Content-Type header.
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            _type: Error
            errorIdentifier: urn:openproject-org:api:v3:errors:TypeNotSupported
            message: Expected CONTENT-TYPE to be (expected value) but got (actual value).
    InvalidRequestBody:
      description: Occurs when the client did not send a valid JSON object in the request body.
      content:
        application/hal+json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            _type: Error
            errorIdentifier: urn:openproject-org:api:v3:errors:InvalidRequestBody
            message: The request body was not a single JSON object.
  schemas:
    Link:
      type: object
      required:
      - href
      properties:
        href:
          type:
          - string
          - 'null'
          description: URL to the referenced resource (might be relative)
        title:
          type: string
          description: Representative label for the resource
        templated:
          type: boolean
          default: false
          description: If true the href contains parts that need to be replaced by the client
        method:
          type: string
          default: GET
          description: The HTTP verb to use when requesting the resource
        payload:
          type: object
          description: The payload to send in the request to achieve the desired result
        identifier:
          type: string
          description: An optional unique identifier to the link object
        type:
          type: string
          description: The MIME-Type of the returned resource.
      example:
        href: /api/v3/work_packages
        method: POST
    CustomActionModel:
      type: object
      properties:
        _type:
          type: string
          enum:
          - CustomAction
        name:
          type: string
          description: The name of the custom action
        description:
          type: string
          description: The description for the custom action
        _links:
          type: object
          required:
          - self
          - executeImmediately
          properties:
            self:
              allOf:
              - $ref: '#/components/schemas/Link'
              - description: 'This custom action


                  **Resource**: CustomAction'
            executeImmediately:
              allOf:
              - $ref: '#/components/schemas/Link'
              - description: Execute this custom action.
      example:
        _type: CustomAction
        name: Change project and type
        description: Changes project and type in one go
        _links:
          executeImmediately:
            href: /api/v3/custom_actions/2/execute
            title: Execute Change project and type
            method: post
          self:
            href: /api/v3/custom_actions/2
            title: Change project and type
    ErrorResponse:
      type: object
      required:
      - _type
      - errorIdentifier
      - message
      properties:
        _embedded:
          type: object
          properties:
            details:
              type: object
              properties:
                attribute:
                  type: string
                  example: project
        _type:
          type: string
          enum:
          - Error
        errorIdentifier:
          type: string
          example: urn:openproject-org:api:v3:errors:PropertyConstraintViolation
        message:
          type: string
          example: Project can't be blank.
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic