Merge branch 'main' into docs/stop-execution-endpoint

docs/en/enterprise/guides/kickoff-crew.mdx

@@ -146,6 +146,36 @@ curl -X GET \
   https://your-crew-url.crewai.com/status/abcd1234-5678-90ef-ghij-klmnopqrstuv
 ```
 
+## Stopping a Running Execution
+
+You can stop or cancel a running crew or flow execution at any time using the stop endpoint. This is useful when you need to abort a long-running execution or cancel one that is no longer needed.
+
+### Stop an Execution
+
+Send a POST request with the `kickoff_id` of the execution you want to stop:
+
+```bash
+curl -X POST \
+  -H "Authorization: Bearer YOUR_CREW_TOKEN" \
+  https://your-crew-url.crewai.com/stop/abcd1234-5678-90ef-ghij-klmnopqrstuv
+```
+
+**Success Response:**
+
+```json
+{"status": "stopped", "kickoffId": "abcd1234-5678-90ef-ghij-klmnopqrstuv"}
+```
+
+**Error Response** (when the execution has already finished):
+
+```json
+{"detail": "Cannot stop execution. Current state: SUCCESS"}
+```
+
+<Note>
+  You cannot stop executions that have already completed (`SUCCESS`), failed (`FAILURE`), or been revoked (`REVOKED`). The API returns a `400` status code in those cases.
+</Note>
+
 ## Handling Executions
 
 ### Long-Running Executions

docs/enterprise-api.base.yaml

@@ -36,6 +36,7 @@ info:
     1. **Discover inputs** using `GET /inputs`
     2. **Start execution** using `POST /kickoff`
     3. **Monitor progress** using `GET /{kickoff_id}/status`
+    4. **Stop execution** (if needed) using `POST /stop/{kickoff_id}`
   version: 1.0.0
   contact:
     name: CrewAI Support
@@ -284,6 +285,56 @@ paths:
         "500":
           $ref: "#/components/responses/ServerError"
 
+  /stop/{kickoff_id}:
+    post:
+      summary: Stop Crew Execution
+      description: |
+        **📋 Reference Example Only** - *This shows the request format. To test with your actual crew, copy the cURL example and replace the URL + token with your real values.*
+
+        Stops or cancels a running crew or flow execution. The execution must be in an active state
+        (not SUCCESS, FAILURE, or REVOKED).
+      operationId: stopCrewExecution
+      parameters:
+        - name: kickoff_id
+          in: path
+          required: true
+          description: The kickoff ID of the execution to stop
+          schema:
+            type: string
+            format: uuid
+            example: "abcd1234-5678-90ef-ghij-klmnopqrstuv"
+      responses:
+        "200":
+          description: Successfully stopped the execution
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StopExecutionResponse"
+              example:
+                status: "stopped"
+                kickoffId: "abcd1234-5678-90ef-ghij-klmnopqrstuv"
+        "400":
+          description: Execution is already in a terminal state (SUCCESS, FAILURE, or REVOKED)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+              example:
+                detail: "Cannot stop execution. Current state: SUCCESS"
+        "401":
+          $ref: "#/components/responses/UnauthorizedError"
+        "404":
+          description: Kickoff ID not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+              example:
+                error: "Execution not found"
+                message: "No execution found with ID: abcd1234-5678-90ef-ghij-klmnopqrstuv"
+        "500":
+          $ref: "#/components/responses/ServerError"
+
   /resume:
     post:
       summary: Resume Crew Execution with Human Feedback
@@ -508,6 +559,19 @@ components:
           description: Time taken to execute this task in seconds
           example: 45.2
 
+    StopExecutionResponse:
+      type: object
+      properties:
+        status:
+          type: string
+          enum: ["stopped"]
+          description: Indicates the execution was successfully stopped
+          example: "stopped"
+        kickoffId:
+          type: string
+          description: The kickoff ID of the stopped execution
+          example: "abcd1234-5678-90ef-ghij-klmnopqrstuv"
+
     Error:
       type: object
       properties:

docs/enterprise-api.en.yaml

@@ -36,6 +36,7 @@ info:
     1. **Discover inputs** using `GET /inputs`
     2. **Start execution** using `POST /kickoff`
     3. **Monitor progress** using `GET /{kickoff_id}/status`
+    4. **Stop execution** (if needed) using `POST /stop/{kickoff_id}`
   version: 1.0.0
   contact:
     name: CrewAI Support
@@ -284,6 +285,56 @@ paths:
         "500":
           $ref: "#/components/responses/ServerError"
 
+  /stop/{kickoff_id}:
+    post:
+      summary: Stop Crew Execution
+      description: |
+        **📋 Reference Example Only** - *This shows the request format. To test with your actual crew, copy the cURL example and replace the URL + token with your real values.*
+
+        Stops or cancels a running crew or flow execution. The execution must be in an active state
+        (not SUCCESS, FAILURE, or REVOKED).
+      operationId: stopCrewExecution
+      parameters:
+        - name: kickoff_id
+          in: path
+          required: true
+          description: The kickoff ID of the execution to stop
+          schema:
+            type: string
+            format: uuid
+            example: "abcd1234-5678-90ef-ghij-klmnopqrstuv"
+      responses:
+        "200":
+          description: Successfully stopped the execution
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StopExecutionResponse"
+              example:
+                status: "stopped"
+                kickoffId: "abcd1234-5678-90ef-ghij-klmnopqrstuv"
+        "400":
+          description: Execution is already in a terminal state (SUCCESS, FAILURE, or REVOKED)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+              example:
+                detail: "Cannot stop execution. Current state: SUCCESS"
+        "401":
+          $ref: "#/components/responses/UnauthorizedError"
+        "404":
+          description: Kickoff ID not found
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+              example:
+                error: "Execution not found"
+                message: "No execution found with ID: abcd1234-5678-90ef-ghij-klmnopqrstuv"
+        "500":
+          $ref: "#/components/responses/ServerError"
+
   /resume:
     post:
       summary: Resume Crew Execution with Human Feedback
@@ -508,6 +559,19 @@ components:
           description: Time taken to execute this task in seconds
           example: 45.2
 
+    StopExecutionResponse:
+      type: object
+      properties:
+        status:
+          type: string
+          enum: ["stopped"]
+          description: Indicates the execution was successfully stopped
+          example: "stopped"
+        kickoffId:
+          type: string
+          description: The kickoff ID of the stopped execution
+          example: "abcd1234-5678-90ef-ghij-klmnopqrstuv"
+
     Error:
       type: object
       properties:

docs/enterprise-api.ko.yaml

@@ -120,6 +120,46 @@ paths:
         '500':
           $ref: '#/components/responses/ServerError'
 
+  /stop/{kickoff_id}:
+    post:
+      summary: 실행 중지
+      description: |
+        **📋 참조 예제만 제공** - *요청 형식을 보여줍니다. 실제 호출은 cURL 예제를 복사해 URL과 토큰을 교체하세요.*
+
+        실행 중인 crew 또는 flow 실행을 중지하거나 취소합니다. 실행이 활성 상태여야 합니다
+        (SUCCESS, FAILURE, REVOKED 상태가 아닌 경우).
+      operationId: stopCrewExecution
+      parameters:
+        - name: kickoff_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        '200':
+          description: 실행을 성공적으로 중지
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/StopExecutionResponse'
+        '400':
+          description: 실행이 이미 종료 상태 (SUCCESS, FAILURE, REVOKED)
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '401':
+          $ref: '#/components/responses/UnauthorizedError'
+        '404':
+          description: Kickoff ID를 찾을 수 없음
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '500':
+          $ref: '#/components/responses/ServerError'
+
   /resume:
     post:
       summary: Resume Crew Execution with Human Feedback
@@ -314,6 +354,15 @@ components:
         execution_time:
           type: number
 
+    StopExecutionResponse:
+      type: object
+      properties:
+        status:
+          type: string
+          enum: ["stopped"]
+        kickoffId:
+          type: string
+
     Error:
       type: object
       properties:

docs/enterprise-api.pt-BR.yaml

@@ -36,6 +36,7 @@ info:
     1. **Descubra os inputs** usando `GET /inputs`
     2. **Inicie a execução** usando `POST /kickoff`
     3. **Monitore o progresso** usando `GET /{kickoff_id}/status`
+    4. **Pare a execução** (se necessário) usando `POST /stop/{kickoff_id}`
   version: 1.0.0
   contact:
     name: CrewAI Suporte
@@ -156,6 +157,46 @@ paths:
         "500":
           $ref: "#/components/responses/ServerError"
 
+  /stop/{kickoff_id}:
+    post:
+      summary: Parar Execução da Crew
+      description: |
+        **📋 Exemplo de Referência** - *Mostra o formato da requisição. Para testar com sua crew real, copie o cURL e substitua URL + token.*
+
+        Para ou cancela uma execução de crew ou flow em andamento. A execução deve estar em um estado ativo
+        (não SUCCESS, FAILURE ou REVOKED).
+      operationId: stopCrewExecution
+      parameters:
+        - name: kickoff_id
+          in: path
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        "200":
+          description: Execução parada com sucesso
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StopExecutionResponse"
+        "400":
+          description: Execução já em estado terminal (SUCCESS, FAILURE ou REVOKED)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "401":
+          $ref: "#/components/responses/UnauthorizedError"
+        "404":
+          description: Kickoff ID não encontrado
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+        "500":
+          $ref: "#/components/responses/ServerError"
+
   /resume:
     post:
       summary: Resume Crew Execution with Human Feedback
@@ -351,6 +392,15 @@ components:
         execution_time:
           type: number
 
+    StopExecutionResponse:
+      type: object
+      properties:
+        status:
+          type: string
+          enum: ["stopped"]
+        kickoffId:
+          type: string
+
     Error:
       type: object
       properties: