openapi: 3.0.0
info:
  title: ProcessMaker Platform RESTful Environment Variables Processes API
  description: 'The ProcessMaker Platform RESTful API provides programmatic access to all platform functionality including process design, case management, task handling, user management, and enterprise integrations. The API is BPMN 2.0 compliant and follows the OpenAPI specification with interactive Swagger UI documentation auto-generated by Swagger/L5-Swagger.

    '
  version: 1.0.0
  contact:
    email: info@processmaker.com
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://{organization}.processmaker.net/api/1.0
  description: ProcessMaker Cloud instance
  variables:
    organization:
      default: myorg
      description: Your ProcessMaker organization subdomain
security:
- bearerAuth: []
tags:
- name: Processes
  description: BPMN 2.0 process design and management
paths:
  /processes:
    get:
      tags:
      - Processes
      summary: Returns all processes that the user has access to
      operationId: getProcesses
      parameters:
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/order_by'
      - $ref: '#/components/parameters/order_direction'
      - $ref: '#/components/parameters/per_page'
      - $ref: '#/components/parameters/status'
      - $ref: '#/components/parameters/include'
      - name: simplified_data_for_selector
        in: query
        description: Return simplified data for process selector UI
        schema:
          type: boolean
      responses:
        '200':
          description: List of processes
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessCollection'
    post:
      tags:
      - Processes
      summary: Save a new process
      operationId: createProcess
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProcessEditable'
      responses:
        '201':
          description: Process created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Process'
        '422':
          $ref: '#/components/responses/422'
  /processes/{processId}:
    get:
      tags:
      - Processes
      summary: Get single process by ID
      operationId: getProcessById
      parameters:
      - name: processId
        in: path
        required: true
        schema:
          type: integer
      - $ref: '#/components/parameters/include'
      responses:
        '200':
          description: Single process resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Process'
        '404':
          $ref: '#/components/responses/404'
    put:
      tags:
      - Processes
      summary: Update a process
      operationId: updateProcess
      parameters:
      - name: processId
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProcessEditable'
      responses:
        '200':
          description: Updated process resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Process'
        '404':
          $ref: '#/components/responses/404'
        '422':
          $ref: '#/components/responses/422'
    delete:
      tags:
      - Processes
      summary: Delete a process
      operationId: deleteProcess
      parameters:
      - name: processId
        in: path
        required: true
        schema:
          type: integer
      responses:
        '204':
          description: No content
        '404':
          $ref: '#/components/responses/404'
  /processes/{processId}/draft:
    put:
      tags:
      - Processes
      summary: Update a draft process
      operationId: updateDraftProcess
      parameters:
      - name: processId
        in: path
        required: true
        schema:
          type: integer
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProcessEditable'
      responses:
        '200':
          description: Updated draft process resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Process'
  /processes/{processId}/restore:
    put:
      tags:
      - Processes
      summary: Restore an inactive process
      operationId: restoreProcess
      parameters:
      - name: processId
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Restored process resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Process'
  /processes/{processId}/export:
    post:
      tags:
      - Processes
      summary: Export a single process by ID and return a URL to download it
      operationId: exportProcess
      parameters:
      - name: processId
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: Export URL
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    format: uri
  /processes/import:
    post:
      tags:
      - Processes
      summary: Import a new process
      operationId: importProcess
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Process import result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessImport'
  /processes/import/validation:
    post:
      tags:
      - Processes
      summary: Validate a process import file
      operationId: validateImport
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                file:
                  type: string
                  format: binary
      responses:
        '200':
          description: Import validation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessImport'
  /processes/{processId}/start_events:
    get:
      tags:
      - Processes
      summary: Get start events of a process by ID
      operationId: getStartEventsProcessById
      parameters:
      - name: processId
        in: path
        required: true
        schema:
          type: integer
      - $ref: '#/components/parameters/include'
      responses:
        '200':
          description: Collection of process start events
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
  /processes/{processId}/bpmn:
    get:
      tags:
      - Processes
      summary: Download the BPMN definition of a process
      operationId: processBpmn
      parameters:
      - name: processId
        in: path
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: BPMN download URL
          content:
            application/json:
              schema:
                type: object
                properties:
                  url:
                    type: string
                    format: uri
  /start_processes:
    get:
      tags:
      - Processes
      summary: Returns the list of processes that the user can start
      operationId: startProcesses
      parameters:
      - $ref: '#/components/parameters/filter'
      - $ref: '#/components/parameters/order_by'
      - $ref: '#/components/parameters/order_direction'
      - $ref: '#/components/parameters/per_page'
      - $ref: '#/components/parameters/include'
      - name: without_event_definitions
        in: query
        schema:
          type: boolean
      responses:
        '200':
          description: Processes with start events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessCollection'
  /process_events/{process_id}:
    post:
      tags:
      - Processes
      summary: Start a new process
      operationId: triggerStartEvent
      parameters:
      - name: process_id
        in: path
        required: true
        schema:
          type: integer
      - name: event
        in: query
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: Optional request data
      responses:
        '200':
          description: New process request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProcessRequest'
components:
  responses:
    '422':
      description: Unprocessable Entity
      content:
        application/json:
          schema:
            type: object
            properties:
              message:
                type: string
              errors:
                type: object
    '404':
      description: Not Found
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
  schemas:
    ProcessImport:
      type: object
      properties:
        status:
          type: object
        assignable:
          type: array
          items:
            type: object
        process:
          $ref: '#/components/schemas/Process'
    ProcessEditable:
      type: object
      required:
      - name
      - status
      - bpmn
      - process_category_id
      properties:
        name:
          type: string
        description:
          type: string
        status:
          type: string
          enum:
          - ACTIVE
          - INACTIVE
        bpmn:
          type: string
          description: BPMN 2.0 XML string
        process_category_id:
          type: integer
        manager_id:
          type: integer
        cancel_screen_id:
          type: integer
        request_detail_screen_id:
          type: integer
        is_valid:
          type: boolean
        warnings:
          type: array
          items:
            type: string
    ProcessCollection:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Process'
        meta:
          $ref: '#/components/schemas/Metadata'
    ProcessRequest:
      allOf:
      - $ref: '#/components/schemas/ProcessRequestEditable'
      - type: object
        properties:
          id:
            type: integer
          process_id:
            type: integer
          user_id:
            type: integer
          process_collaboration_id:
            type: integer
            nullable: true
          callable_id:
            type: string
          created_at:
            type: string
            format: date-time
          updated_at:
            type: string
            format: date-time
          completed_at:
            type: string
            format: date-time
            nullable: true
    Process:
      allOf:
      - $ref: '#/components/schemas/ProcessEditable'
      - type: object
        properties:
          id:
            type: integer
          user_id:
            type: integer
          created_at:
            type: string
            format: date-time
          updated_at:
            type: string
            format: date-time
          deleted_at:
            type: string
            format: date-time
            nullable: true
    ProcessRequestEditable:
      type: object
      properties:
        status:
          type: string
          enum:
          - ACTIVE
          - COMPLETED
          - ERROR
          - CANCELED
        data:
          type: object
        name:
          type: string
    Metadata:
      type: object
      properties:
        total:
          type: integer
        count:
          type: integer
        per_page:
          type: integer
        current_page:
          type: integer
        total_pages:
          type: integer
        sort_by:
          type: string
        sort_order:
          type: string
        search:
          type: string
  parameters:
    status:
      name: status
      in: query
      description: Filter by status - ACTIVE or INACTIVE
      schema:
        type: string
        enum:
        - ACTIVE
        - INACTIVE
    per_page:
      name: per_page
      in: query
      schema:
        type: integer
        default: 10
    filter:
      name: filter
      in: query
      description: 'Filter results by string. Searches Name, Description, and Status. Status must match exactly. Others can be a substring.

        '
      schema:
        type: string
    order_by:
      name: order_by
      in: query
      description: Field to order results by
      schema:
        type: string
    include:
      name: include
      in: query
      description: Include data from related models in payload. Comma separated list.
      schema:
        type: string
        default: ''
    order_direction:
      name: order_direction
      in: query
      schema:
        type: string
        enum:
        - asc
        - desc
        default: asc
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT