docs: update REST API spec (#5104)

Co-authored-by: tmetzke <tmetzke@users.noreply.github.com>

api/camunda/camunda-openapi.yaml

@@ -26,6 +26,7 @@ servers:
         description: The schema of the Camunda 8 REST API server.
 
 tags:
+  - name: Ad-hoc subprocess
   - name: Authentication
   - name: Authorization
   - name: Clock
@@ -1391,6 +1392,10 @@ paths:
             This can happen if the `awaitCompletion` request parameter is set to `true`
             and the created process instance did not complete within the defined request timeout.
             This often happens when the created instance is not fully automated or contains wait states.
+          content:
+            application/problem+json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetail"
 
   /process-instances/{processInstanceKey}:
     get:
@@ -3266,6 +3271,51 @@ paths:
         "500":
           $ref: "#/components/responses/InternalServerError"
 
+  /element-instances/ad-hoc-activities/search:
+    post:
+      tags:
+        - Ad-hoc subprocess
+      operationId: findAdHocSubprocessActivities
+      summary: Query activatable activities (alpha)
+      description: |
+        Search for activatable activities within ad-hoc subprocesses based on given criteria.
+
+        Note that this API currently requires filters for both process definition key and ad-hoc
+        subprocess ID and does not support paging or sorting.
+
+        :::note
+        This endpoint is an [alpha feature](/components/early-access/alpha/alpha-features.md) and may be subject to change
+        in future releases.
+        :::
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/AdHocSubprocessActivitySearchQuery"
+      responses:
+        "200":
+          description: >
+            The ad-hoc subprocess activities search result.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/AdHocSubprocessActivitySearchQueryResult"
+        "400":
+          description: >
+            The ad-hoc subprocess activities search query failed.
+            More details are provided in the response body.
+          content:
+            application/problem+json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetail"
+        "401":
+          $ref: "#/components/responses/Unauthorized"
+        "403":
+          $ref: "#/components/responses/Forbidden"
+        "500":
+          $ref: "#/components/responses/InternalServerError"
+
   /signals/broadcast:
     post:
       tags:
@@ -4439,6 +4489,83 @@ components:
         incidentKey:
           description: Incident key associated with this flow node instance.
           type: string
+    AdHocSubprocessActivitySearchQuery:
+      description: Ad-hoc subprocess activities search request.
+      type: object
+      required:
+        - filter
+      properties:
+        filter:
+          description: The ad-hoc subprocess activity search filters.
+          allOf:
+            - $ref: "#/components/schemas/AdHocSubprocessActivityFilter"
+    AdHocSubprocessActivityFilter:
+      description: Flow node instance filter.
+      type: object
+      required:
+        - processDefinitionKey
+        - adHocSubprocessId
+      properties:
+        processDefinitionKey:
+          description: The process definition key.
+          type: string
+        adHocSubprocessId:
+          description: The ad-hoc subprocess element ID.
+          type: string
+    AdHocSubprocessActivitySearchQueryResult:
+      type: object
+      properties:
+        items:
+          description: The matching ad-hoc subprocess activities.
+          type: array
+          items:
+            $ref: "#/components/schemas/AdHocSubprocessActivityResult"
+    AdHocSubprocessActivityResult:
+      type: object
+      properties:
+        processDefinitionKey:
+          description: The process definition key associated to this activity.
+          type: string
+        processDefinitionId:
+          description: The process definition ID associated to this activity.
+          type: string
+        adHocSubprocessId:
+          description: The ad-hoc subprocess element ID.
+          type: string
+        elementId:
+          description: The element ID for this activity.
+          type: string
+        elementName:
+          description: The element name for this activity.
+          type: string
+        type:
+          description: Type of activity with a defined set of values.
+          type: string
+          enum:
+            - UNSPECIFIED
+            - PROCESS
+            - SUB_PROCESS
+            - EVENT_SUB_PROCESS
+            - INTERMEDIATE_CATCH_EVENT
+            - INTERMEDIATE_THROW_EVENT
+            - BOUNDARY_EVENT
+            - SERVICE_TASK
+            - RECEIVE_TASK
+            - USER_TASK
+            - MANUAL_TASK
+            - TASK
+            - MULTI_INSTANCE_BODY
+            - CALL_ACTIVITY
+            - BUSINESS_RULE_TASK
+            - SCRIPT_TASK
+            - SEND_TASK
+            - UNKNOWN
+        documentation:
+          description: The documentation for this activity.
+          type: string
+        tenantId:
+          description: The tenant ID for this activity.
+          type: string
     DecisionDefinitionSearchQuerySortRequest:
       type: object
       properties:

docs/apis-tools/camunda-api-rest/specifications/create-process-instance.api.mdx

@@ -5,7 +5,7 @@ description: "Creates and starts an instance of the specified process."
 sidebar_label: "Create process instance"
 hide_title: true
 hide_table_of_contents: true
-api: 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
+api: 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
 sidebar_class_name: "post api-method"
 info_path: docs/apis-tools/camunda-api-rest/specifications/camunda-8-rest-api
 custom_edit_url: null
@@ -280,6 +280,44 @@ when awaitCompletion is enabled.
     "504": {
       description:
         "The process instance creation request timed out in the gateway.\n\nThis can happen if the `awaitCompletion` request parameter is set to `true`\nand the created process instance did not complete within the defined request timeout.\nThis often happens when the created instance is not fully automated or contains wait states.\n",
+      content: {
+        "application/problem+json": {
+          schema: {
+            description:
+              "A Problem detail object as described in [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457). There may be additional properties specific to the problem type.\n",
+            type: "object",
+            properties: {
+              type: {
+                type: "string",
+                format: "uri",
+                description: "A URI identifying the problem type.",
+                default: "about:blank",
+              },
+              title: {
+                type: "string",
+                description: "A summary of the problem type.",
+              },
+              status: {
+                type: "integer",
+                format: "int32",
+                description: "The HTTP status code for this problem.",
+                minimum: 400,
+                maximum: 600,
+              },
+              detail: {
+                type: "string",
+                description: "An explanation of the problem in more detail.",
+              },
+              instance: {
+                type: "string",
+                format: "uri",
+                description: "A URI identifying the origin of the problem.",
+              },
+            },
+            title: "ProblemDetail",
+          },
+        },
+      },
     },
   }}
 ></StatusCodes>