openapi: 3.0.3
info:
  title: CrewAI AMP API
  description: |
    REST API para interagir com suas crews implantadas no CrewAI AMP.

    ## Introdução

    1. **Encontre a URL da sua crew**: Obtenha sua URL única no painel do CrewAI AMP
    2. **Copie os exemplos**: Use os exemplos de cada endpoint como modelo
    3. **Substitua os placeholders**: Atualize URLs e tokens com seus valores reais
    4. **Teste com suas ferramentas**: Use cURL, Postman ou seu cliente preferido

    ## Autenticação

    Todas as requisições exigem um token bearer. Existem dois tipos:

    - **Bearer Token**: Token em nível de organização para operações completas
    - **User Bearer Token**: Token com escopo de usuário com permissões limitadas

    Você encontra os tokens na aba Status da sua crew no painel do CrewAI AMP.

    ## Documentação de Referência

    Este documento fornece exemplos completos para cada endpoint:

    - **Formatos de requisição** com parâmetros obrigatórios e opcionais
    - **Exemplos de resposta** para sucesso e erro
    - **Amostras de código** em várias linguagens
    - **Padrões de autenticação** com uso correto de Bearer token

    Copie os exemplos e personalize com sua URL e tokens reais.

    ## Fluxo

    1. **Descubra os inputs** usando `GET /inputs`
    2. **Inicie a execução** usando `POST /kickoff`
    3. **Monitore o progresso** usando `GET /status/{kickoff_id}`
  version: 1.0.0
  contact:
    name: CrewAI Suporte
    email: support@crewai.com
    url: https://crewai.com
servers:
  - url: https://your-actual-crew-name.crewai.com
    description: Substitua pela URL real da sua crew no painel do CrewAI AMP
security:
  - BearerAuth: []
paths:
  /inputs:
    get:
      summary: Obter Inputs Requeridos
      description: |
        **📋 Exemplo de Referência** - *Mostra o formato da requisição. Para testar com sua crew real, copie o cURL e substitua URL + token.*

        Retorna a lista de parâmetros de entrada que sua crew espera.
      operationId: getRequiredInputs
      responses:
        "200":
          description: Inputs requeridos obtidos com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  inputs:
                    type: array
                    items:
                      type: string
                    description: Nomes dos parâmetros de entrada
                    example: ["budget", "interests", "duration", "age"]
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          $ref: "#/components/responses/NotFoundError"
        "500":
          $ref: "#/components/responses/ServerError"

  /kickoff:
    post:
      summary: Iniciar 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.*

        Inicia uma nova execução da crew com os inputs fornecidos e retorna um kickoff ID.
      operationId: startCrewExecution
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - inputs
              properties:
                inputs:
                  type: object
                  additionalProperties:
                    type: string
                  example:
                    budget: "1000 USD"
                    interests: "games, tech, ai, relaxing hikes, amazing food"
                    duration: "7 days"
                    age: "35"

      responses:
        "200":
          description: Execução iniciada com sucesso
          content:
            application/json:
              schema:
                type: object
                properties:
                  kickoff_id:
                    type: string
                    format: uuid
                    example: "abcd1234-5678-90ef-ghij-klmnopqrstuv"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "500":
          $ref: "#/components/responses/ServerError"

  /status/{kickoff_id}:
    get:
      summary: Obter Status da Execução
      description: |
        **📋 Exemplo de Referência** - *Mostra o formato da requisição. Para testar com sua crew real, copie o cURL e substitua URL + token.*

        Retorna o status atual e os resultados de uma execução usando o kickoff ID.
      operationId: getExecutionStatus
      parameters:
        - name: kickoff_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Status recuperado com sucesso
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: "#/components/schemas/ExecutionRunning"
                  - $ref: "#/components/schemas/ExecutionCompleted"
                  - $ref: "#/components/schemas/ExecutionError"
        "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
      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.*

        Resume a paused crew execution with human feedback for Human-in-the-Loop (HITL) workflows.
        When a task with `human_input=True` completes, the crew execution pauses and waits for human feedback.

        **IMPORTANT**: You must provide the same webhook URLs (`taskWebhookUrl`, `stepWebhookUrl`, `crewWebhookUrl`)
        that were used in the original kickoff call. Webhook configurations are NOT automatically carried over -
        they must be explicitly provided in the resume request to continue receiving notifications.
      operationId: resumeCrewExecution
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - execution_id
                - task_id
                - human_feedback
                - is_approve
              properties:
                execution_id:
                  type: string
                  format: uuid
                  description: The unique identifier for the crew execution (from kickoff)
                  example: "abcd1234-5678-90ef-ghij-klmnopqrstuv"
                task_id:
                  type: string
                  description: The ID of the task that requires human feedback
                  example: "research_task"
                human_feedback:
                  type: string
                  description: Your feedback on the task output. This will be incorporated as additional context for subsequent task executions.
                  example: "Great research! Please add more details about recent developments in the field."
                is_approve:
                  type: boolean
                  description: "Whether you approve the task output: true = positive feedback (continue), false = negative feedback (retry task)"
                  example: true
                taskWebhookUrl:
                  type: string
                  format: uri
                  description: Callback URL executed after each task completion. MUST be provided to continue receiving task notifications.
                  example: "https://your-server.com/webhooks/task"
                stepWebhookUrl:
                  type: string
                  format: uri
                  description: Callback URL executed after each agent thought/action. MUST be provided to continue receiving step notifications.
                  example: "https://your-server.com/webhooks/step"
                crewWebhookUrl:
                  type: string
                  format: uri
                  description: Callback URL executed when the crew execution completes. MUST be provided to receive completion notification.
                  example: "https://your-server.com/webhooks/crew"
            examples:
              approve_and_continue:
                summary: Approve task and continue execution
                value:
                  execution_id: "abcd1234-5678-90ef-ghij-klmnopqrstuv"
                  task_id: "research_task"
                  human_feedback: "Excellent research! Proceed to the next task."
                  is_approve: true
                  taskWebhookUrl: "https://api.example.com/webhooks/task"
                  stepWebhookUrl: "https://api.example.com/webhooks/step"
                  crewWebhookUrl: "https://api.example.com/webhooks/crew"
              request_revision:
                summary: Request task revision with feedback
                value:
                  execution_id: "abcd1234-5678-90ef-ghij-klmnopqrstuv"
                  task_id: "analysis_task"
                  human_feedback: "Please include more quantitative data and cite your sources."
                  is_approve: false
                  taskWebhookUrl: "https://api.example.com/webhooks/task"
                  crewWebhookUrl: "https://api.example.com/webhooks/crew"
      responses:
        "200":
          description: Execution resumed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum: ["resumed", "retrying", "completed"]
                    description: Status of the resumed execution
                    example: "resumed"
                  message:
                    type: string
                    description: Human-readable message about the resume operation
                    example: "Execution resumed successfully"
              examples:
                resumed:
                  summary: Execution resumed with positive feedback
                  value:
                    status: "resumed"
                    message: "Execution resumed successfully"
                retrying:
                  summary: Task will be retried with negative feedback
                  value:
                    status: "retrying"
                    message: "Task will be retried with your feedback"
        "400":
          description: Invalid request body or execution not in pending state
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: "Invalid Request"
                message: "Execution is not in pending human input state"
        "401":
          $ref: "#/components/responses/UnauthorizedError"
        "404":
          description: Execution ID or Task ID not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                error: "Not Found"
                message: "Execution ID not found"
        "500":
          $ref: "#/components/responses/ServerError"

components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        **📋 Referência** - *Os tokens mostrados são apenas exemplos.*
        Use seus tokens reais do painel do CrewAI AMP.

  schemas:
    ExecutionRunning:
      type: object
      properties:
        status:
          type: string
          enum: ["running"]
        current_task:
          type: string
        progress:
          type: object
          properties:
            completed_tasks:
              type: integer
            total_tasks:
              type: integer

    ExecutionCompleted:
      type: object
      properties:
        status:
          type: string
          enum: ["completed"]
        result:
          type: object
          properties:
            output:
              type: string
            tasks:
              type: array
              items:
                $ref: "#/components/schemas/TaskResult"
        execution_time:
          type: number

    ExecutionError:
      type: object
      properties:
        status:
          type: string
          enum: ["error"]
        error:
          type: string
        execution_time:
          type: number

    TaskResult:
      type: object
      properties:
        task_id:
          type: string
        output:
          type: string
        agent:
          type: string
        execution_time:
          type: number

    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string

    ValidationError:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
        details:
          type: object
          properties:
            missing_inputs:
              type: array
              items:
                type: string

  responses:
    UnauthorizedError:
      description: Autenticação falhou
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotFoundError:
      description: Recurso não encontrado
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    ServerError:
      description: Erro interno do servidor
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"