openapi.yaml

openapi: 3.0.0
info:
  title: Camunda Platform REST API
  description: >-
    REST API to interact with Camunda Platform 8.


    :::caution


    This API is not yet stable - we may break backward compatibility in newer releases of `v0`.


    :::
  version: 0.3.0-SNAPSHOT
externalDocs:
  description: Find out more
  url: https://korthout.github.io/camunda-platform-rest-api/
paths:
  /status:
    get:
      summary: Retrieve the Zeebe cluster status
      description: Retrieves the Topology of a Zeebe cluster from the Gateway. This
        provides insights into the current status of the cluster
      operationId: getStatus
      responses:
        "200":
          description: successfully retrieved
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/StatusResponse"
        "503":
          description: Unable to connect to Zeebe cluster
      tags:
        - Cluster
  /process-instances:
    post:
      summary: Create a new Process Instance
      description: >-
        Creates a new process instance. This does not await for the process
        instance to complete,

        i.e. it will be executed asynchronously.
      operationId: createProcessInstance
      requestBody:
        $ref: "#/components/requestBodies/CreateProcessInstanceRequest"
      x-codegen-request-body-name: body
      responses:
        "200":
          description: successfully created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProcessInstanceResponse"
        "503":
          description: Unable to connect to Zeebe cluster
      tags:
        - Automation
  "/process-instances/{key}":
    get:
      summary: Retrieve the details of a process instance
      description: >-
        Retrieve the details of a process instance.

        Note that this data may lag behind the actual process instance's status, but is eventually consistent.
      operationId: getProcessInstance
      parameters:
        - name: key
          description: Key (unique identifier) of the process instance
          in: path
          required: true
          schema:
            type: integer
            format: int64
      responses:
        "200":
          description: The details of the process instance.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProcessInstanceDetailsResponse"
        "404":
          description: Unable to find the process instance. Are you sure an instance with
            this key was created? Note that this data may lag behind due to
            eventual consistency. Please try this request again in a few
            moments.
        "503":
          description: Unable to connect to Operate
      tags:
        - Insights
  /jobs:
    get:
      summary: Activate Jobs of a specific type
      description: >-
        Will activate available jobs of the specific type, and returns the
        activated jobs.


        If no jobs of this type are available, then the connection may be kept open until one or

        more jobs become available, or the request times out due to long polling.
      operationId: activateJobs
      parameters:
        - name: type
          description: The type of the job to activate
          in: query
          style: form
          required: true
          schema:
            type: string
        - name: maxJobsToActivate
          description: The maximum number of jobs to activate in this request
          in: query
          style: form
          required: false
          schema:
            type: integer
            format: int32
            default: 32
        - name: worker
          description: The name of the worker requesting to activate the jobs
          in: query
          style: form
          required: false
          schema:
            type: string
            default: default
        - name: jobTimeout
          description: Duration during which the activated jobs are claimed by this worker
          in: query
          style: form
          required: false
          schema:
            type: string
            default: 5m
          examples:
            durationTenSeconds:
              $ref: "#/components/examples/durationTenSeconds"
            durationFiveMin:
              $ref: "#/components/examples/durationFiveMin"
            durationOneAndAHalfHour:
              $ref: "#/components/examples/durationOneAndAHalfHour"
        - name: fetchVariables
          description: >-
            Names of the variables to fetch with each job.


            If empty, all visible variables at the time of activation for the scope of the job will

            be returned.
          in: query
          style: form
          required: false
          schema:
            type: array
            items:
              type: string
      responses:
        "200":
          description: Zero or more jobs activated
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ActivatedJobsResponse"
        "503":
          description: Unable to connect to Zeebe cluster
      tags:
        - Automation
  "/jobs/{key}":
    patch:
      summary: Update a Job
      description: |-
        Can be used to:

        ### Complete the job

        Set the `status` of the job to `completed`, with:
          - (optionally) `variables`

        ### Fail the job

        Set the `status` of the job to `failed`, with:
          - `retries`
          - (optionally) `retryBackoff`
          - (optionally) `errorMessage`

        ### Throw an error for the job

        Set the `status` of the job to `error_thrown`, with:
          - `errorCode`
          - (optionally) `errorMessage`
      operationId: updateJob
      parameters:
        - name: key
          description: Key (unique identifier) of the job to update
          in: path
          required: true
          schema:
            type: integer
            format: int64
      requestBody:
        $ref: "#/components/requestBodies/UpdateJobRequest"
      x-codegen-request-body-name: body
      responses:
        "204":
          description: Successfully updated the job
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UpdateJobResponse"
        "503":
          description: Unable to connect to Zeebe cluster
      tags:
        - Automation
tags:
  - name: Cluster
    description: Find out the status of your cluster.
  - name: Automation
    description: Everything to automate your processes.
  - name: Insights
    description: Insights into your processes.
components:
  requestBodies:
    CreateProcessInstanceRequest:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/CreateProcessInstanceRequest"
      description: A request to create a new process instance
      required: true
    UpdateJobRequest:
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/UpdateJobRequest"
      description: A request to update a job
      required: true
  schemas:
    StatusResponse:
      title: A response to GET /status
      description: A response to GET /status
      type: object
      properties:
        data:
          $ref: "#/components/schemas/Topology"
        error:
          type: string
    Topology:
      title: A topology for a Zeebe cluster
      description: A topology for a Zeebe cluster
      type: object
      properties:
        clusterSize:
          type: integer
          format: int32
          description: The expected number of brokers (nodes) in the cluster
        partitionsCount:
          type: integer
          format: int32
          description: The number of partitions spread across the cluster
        replicationFactor:
          type: integer
          format: int32
          description: The number of replicas that should exist of each partition.
        gatewayVersion:
          type: string
          description: The version of the gateway's software
        brokers:
          type: array
          items:
            $ref: "#/components/schemas/TopologyBroker"
          description: The list of brokers that are part of the cluster
    TopologyBroker:
      type: object
      properties:
        address:
          type: string
          description: The address of the broker (host:port)
        host:
          type: string
          description: The hostname of the broker
        port:
          type: integer
          format: int32
          description: The port at which the broker can be contacted
        version:
          type: string
          description: The version of the broker's software
        partitions:
          type: array
          items:
            $ref: "#/components/schemas/TopologyPartition"
          description: The list of partitions managed or replicated on this broker
        nodeId:
          type: integer
          format: int32
          description: The unique (within the cluster) ID for the broker
    TopologyPartition:
      type: object
      properties:
        partitionId:
          type: integer
          format: int32
          description: The unique (within a cluster) ID of the partition
        role:
          type: string
          enum:
            - LEADER
            - FOLLOWER
            - INACTIVE
          description: The RAFT role of the broker for the partition
        leader:
          type: boolean
          description: Whether the broker is leader for the partition, or not
        health:
          type: string
          enum:
            - HEALTHY
            - UNHEALTHY
            - DEAD
          description: The health of the partition on the broker
    CreateProcessInstanceRequest:
      title: A request to create a new process instance
      description: A request to create a new process instance
      type: object
      properties:
        bpmnProcessId:
          type: string
          description: BPMN process id of the process to instantiate
        processDefinitionKey:
          type: integer
          format: int64
          description: Key of the process to instantiate
        variables:
          description: Variables to instantiate the process with
    ProcessInstanceResponse:
      title: A response to a CreateProcessInstanceRequest
      description: A response to a CreateProcessInstanceRequest
      type: object
      properties:
        data:
          $ref: "#/components/schemas/ProcessInstance"
        error:
          type: string
    ProcessInstance:
      title: A process instance
      description: A process instance
      type: object
      properties:
        processDefinitionKey:
          type: integer
          format: int64
          description: Key of the process which this instance was created for
        bpmnProcessId:
          type: string
          description: BPMN process id of the process which this instance was created for
        version:
          type: integer
          description: Version of the process which this instance was created for
        processInstanceKey:
          type: integer
          format: int64
          description: Unique key of the created process instance on the partition
    ProcessInstanceDetailsResponse:
      title: A response to a request to retrieve ProcessInstanceDetails
      description: A response to a request to retrieve ProcessInstanceDetails
      type: object
      properties:
        data:
          $ref: "#/components/schemas/ProcessInstanceDetails"
        error:
          type: string
    ProcessInstanceDetails:
      title: A process instance
      description: A process instance
      type: object
      properties:
        processDefinitionKey:
          type: integer
          format: int64
          description: Key of the process which this instance belongs to
        bpmnProcessId:
          type: string
          description: BPMN process id of the process which this instance belongs to
        version:
          type: integer
          description: Version of the process which this instance belongs to
        processInstanceKey:
          type: integer
          format: int64
          description: Unique key of the process instance on the partition
        parentInstanceKey:
          type: integer
          format: int64
          description: Unique key of the process instance which this instance is a part of
            (e.g. called from call activity), or null if it has no parent
            instance
        status:
          type: string
          description: The status of the process instance
          enum:
            - activated
            - has_incident
            - completed
            - terminated
        startedAt:
          type: string
          description: Timestamp when the process instance was started, in ISO 8601
            representation
        endedAt:
          type: string
          description: Timestamp when the process instance was ended, in ISO 8601
            representation, or null if it has yet ended
    ActivatedJobsResponse:
      title: A response to a request to Activate Jobs
      description: A response to a request to Activate Jobs
      type: object
      properties:
        data:
          type: object
          properties:
            jobs:
              type: array
              items:
                $ref: "#/components/schemas/Job"
        error:
          type: string
    Job:
      title: A unit of work within a process
      description: >-
        A job represents a distinct unit of work within a business process.


        Service tasks represent such jobs in your process and are identified by a unique id.

        A job has a type to allow specific job workers to find jobs that they can work on.
      type: object
      properties:
        key:
          type: integer
          format: int64
          description: Key of the job
        status:
          type: string
          description: The status of the job
          enum:
            - activatable
            - activated
            - failed
            - error_thrown
            - completed
        type:
          type: string
          description: Type of the job
        processInstanceKey:
          type: integer
          format: int64
          description: Key of the process instance which this job belongs to
        bpmnProcessId:
          type: string
          description: BPMN process id of the process which this job belongs to
        processDefinitionVersion:
          type: integer
          format: int32
          description: Version number of the process which this job belongs to
        processDefinitionKey:
          type: integer
          format: int64
          description: Key of the process which this job belongs to
        elementId:
          type: string
          description: Id of the element in the process which this job belongs to
        elementInstanceKey:
          type: integer
          format: int64
          description: Key of the element instance which this job belongs to
        customHeaders:
          type: object
          description: >
            Set of custom headers defined during modelling; returned as a
            serialized JSON document
        worker:
          type: string
          description: Name of the worker that activated this job
        retries:
          type: integer
          format: int32
          description: Number of retries left for this job
        deadline:
          type: integer
          format: int64
          description: UNIX epoch timestamp specifying when the job can be activated again
        variables:
          type: object
          description: >
            JSON document consisting of all variables visible to the task scope
            at the time of job

            activation
    UpdateJobRequest:
      title: A request to update a job
      description: A request to update a job
      type: object
      properties:
        status:
          type: string
          example: completed
          description: Requested state for the job, either one of `completed`, `failed`,
            or `error_thrown`
        retries:
          type: integer
          format: int32
          description: Number of retries for the job when it `failed`
        retryBackoff:
          type: string
          default: 0ms
          example: 2s 500ms
          description: Duration after which the job becomes `activatable` again when it
            `failed`
        errorCode:
          type: string
          description: Code to match an error catch event when job state `error_thrown`
            requested
        errorMessage:
          type: string
          description: Message to describe the error when job state `error_thrown` requested
        variables:
          type: object
          additionalProperties: true
          description: Variables to set for the job
      required:
        - status
    UpdateJobResponse:
      title: A response to an UpdateJobRequest
      description: A response to an UpdateJobRequest
      type: object
      properties:
        data: {}
        error:
          type: string
  examples:
    durationTenSeconds:
      summary: Duration of ten seconds
      value: 10s
    durationFiveMin:
      summary: Duration of five minutes
      value: 5m
    durationOneAndAHalfHour:
      summary: Duration of one hour and thirty minutes
      value: 1h30m