openapi: 3.1.0
info:
  title: CrewAI AMP REST API
  version: '1.0'
  description: |
    Per-crew REST API exposed by every crew deployed to CrewAI AMP (Cloud or Factory).

    Each deployed crew is reachable at its own hostname
    (`https://{crew-name}.crewai.com` for AMP Cloud, or your private hostname for AMP Factory)
    and supports four operations:

    - `GET  /inputs` — list the input parameter names this crew expects.
    - `POST /kickoff` — launch a crew execution and return a `kickoff_id`.
    - `GET  /status/{kickoff_id}` — poll execution status and retrieve results.
    - `POST /resume` — submit human feedback (approve or retry) for a HITL-paused task.

    All endpoints require Bearer token authentication. Tokens are issued from the AMP dashboard
    Status tab and come in two flavors: organization-level (full crew operations) and user-scoped
    (limited permissions).
  contact:
    name: CrewAI Support
    url: https://docs.crewai.com/en/api-reference/introduction
  license:
    name: Commercial
    url: https://www.crewai.com/legal/terms-of-use
servers:
  - url: https://{crewName}.crewai.com
    description: AMP Cloud per-crew endpoint
    variables:
      crewName:
        default: your-crew-name
        description: The crew slug from the AMP dashboard.
  - url: https://{crewName}.{factoryHost}
    description: AMP Factory (self-hosted) per-crew endpoint
    variables:
      crewName:
        default: your-crew-name
      factoryHost:
        default: amp.example.com
security:
  - bearerAuth: []
tags:
  - name: Inputs
    description: Discover the input parameters this crew accepts.
  - name: Kickoff
    description: Launch a crew execution.
  - name: Status
    description: Inspect execution progress and retrieve results.
  - name: Resume
    description: Deliver human-in-the-loop feedback on a paused task.
paths:
  /inputs:
    get:
      tags:
        - Inputs
      operationId: listInputs
      summary: List Required Crew Inputs
      description: |
        Retrieves the list of input parameter names this crew expects when you kick it off.
        Use this to discover the keys you must populate in the `inputs` object on `POST /kickoff`.
      responses:
        '200':
          description: Input parameter list returned.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InputsResponse'
              examples:
                research:
                  summary: Research crew inputs
                  value:
                    inputs:
                      - topic
                      - target_audience
                      - depth
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /kickoff:
    post:
      tags:
        - Kickoff
      operationId: kickoffCrew
      summary: Kick Off Crew Execution
      description: |
        Launches a crew execution with the supplied inputs and optional webhook callback URLs.
        Returns a `kickoff_id` you can use with `GET /status/{kickoff_id}` to poll progress
        or to correlate webhook events.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/KickoffRequest'
            examples:
              minimal:
                summary: Minimal kickoff
                value:
                  inputs:
                    topic: Open banking in Brazil
              webhooks:
                summary: Kickoff with all three webhooks
                value:
                  inputs:
                    topic: Open banking in Brazil
                    audience: Banking executives
                  meta:
                    requestId: 7a2c-9f1b
                  taskWebhookUrl: https://hooks.example.com/crewai/task
                  stepWebhookUrl: https://hooks.example.com/crewai/step
                  crewWebhookUrl: https://hooks.example.com/crewai/crew
      responses:
        '200':
          description: Kickoff accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KickoffResponse'
              examples:
                accepted:
                  value:
                    kickoff_id: abcd1234-5678-90ef-ghij-klmnopqrstuv
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/ValidationError'
        '500':
          $ref: '#/components/responses/ServerError'
  /status/{kickoff_id}:
    get:
      tags:
        - Status
      operationId: getKickoffStatus
      summary: Get Kickoff Status
      description: |
        Returns the current status of a crew execution identified by `kickoff_id`. The response
        shape varies by state: `running` includes current task and progress; `completed` includes
        per-task outputs and total execution time; `error` includes an error message.
      parameters:
        - in: path
          name: kickoff_id
          required: true
          description: UUID returned by `POST /kickoff`.
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Execution status.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StatusResponse'
              examples:
                running:
                  summary: Running execution
                  value:
                    status: running
                    current_task: Research market trends
                    progress:
                      completed_tasks: 2
                      total_tasks: 5
                completed:
                  summary: Completed execution
                  value:
                    status: completed
                    result:
                      output: Final report text...
                      tasks:
                        - task_id: t-1
                          agent: Researcher
                          output: Market summary...
                          execution_time: 12.4
                    execution_time: 64.1
                error:
                  summary: Errored execution
                  value:
                    status: error
                    error: Tool timeout in step 4
                    execution_time: 41.0
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /resume:
    post:
      tags:
        - Resume
      operationId: resumeKickoff
      summary: Resume Crew with Human Feedback
      description: |
        Resumes a crew execution that paused for human-in-the-loop review. Supply
        `execution_id` and `task_id`, the reviewer's `human_feedback`, and `is_approve`
        (`true` to proceed, `false` to retry the task with the feedback as additional context).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResumeRequest'
            examples:
              approve:
                summary: Approve the task output
                value:
                  execution_id: abcd1234-5678-90ef-ghij-klmnopqrstuv
                  task_id: t-3
                  human_feedback: Looks good, ship it.
                  is_approve: true
              retry:
                summary: Retry with feedback
                value:
                  execution_id: abcd1234-5678-90ef-ghij-klmnopqrstuv
                  task_id: t-3
                  human_feedback: Tone is off — make it more formal.
                  is_approve: false
      responses:
        '200':
          description: Resume accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResumeResponse'
              examples:
                resumed:
                  value:
                    status: resumed
                    message: Execution resumed at task t-3
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: opaque
      description: |
        Bearer token from the AMP dashboard Status tab. Use either an organization-level
        Bearer Token (full crew operations) or a User Bearer Token (user-scoped access).
  schemas:
    InputsResponse:
      type: object
      required:
        - inputs
      properties:
        inputs:
          type: array
          description: List of input parameter names the crew expects.
          items:
            type: string
    KickoffRequest:
      type: object
      required:
        - inputs
      properties:
        inputs:
          type: object
          description: Key-value pairs of all required inputs for the crew.
          additionalProperties: true
        meta:
          type: object
          description: Additional metadata to attach to the kickoff (echoed in events).
          additionalProperties: true
        taskWebhookUrl:
          type: string
          format: uri
          description: Callback URL invoked after each task completes.
        stepWebhookUrl:
          type: string
          format: uri
          description: Callback URL invoked after each agent thought or action.
        crewWebhookUrl:
          type: string
          format: uri
          description: Callback URL invoked when the crew execution completes.
    KickoffResponse:
      type: object
      required:
        - kickoff_id
      properties:
        kickoff_id:
          type: string
          format: uuid
          description: Unique identifier for the kickoff. Use with `/status/{kickoff_id}`.
    StatusResponse:
      oneOf:
        - $ref: '#/components/schemas/StatusRunning'
        - $ref: '#/components/schemas/StatusCompleted'
        - $ref: '#/components/schemas/StatusError'
      discriminator:
        propertyName: status
        mapping:
          running: '#/components/schemas/StatusRunning'
          completed: '#/components/schemas/StatusCompleted'
          error: '#/components/schemas/StatusError'
    StatusRunning:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          enum:
            - running
        current_task:
          type: string
          description: Name or id of the task currently executing.
        progress:
          type: object
          properties:
            completed_tasks:
              type: integer
              minimum: 0
            total_tasks:
              type: integer
              minimum: 0
    StatusCompleted:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          enum:
            - completed
        result:
          type: object
          properties:
            output:
              type: string
              description: Final aggregated crew output.
            tasks:
              type: array
              items:
                $ref: '#/components/schemas/TaskResult'
        execution_time:
          type: number
          format: double
          description: Total execution time in seconds.
    StatusError:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          enum:
            - error
        error:
          type: string
          description: Human-readable error message.
        execution_time:
          type: number
          format: double
    TaskResult:
      type: object
      properties:
        task_id:
          type: string
        agent:
          type: string
          description: Agent role that executed the task.
        output:
          type: string
        execution_time:
          type: number
          format: double
    ResumeRequest:
      type: object
      required:
        - execution_id
        - task_id
        - human_feedback
        - is_approve
      properties:
        execution_id:
          type: string
          format: uuid
          description: The `kickoff_id` returned by `/kickoff`.
        task_id:
          type: string
          description: Identifier of the task awaiting human feedback.
        human_feedback:
          type: string
          description: Feedback to incorporate as additional context.
        is_approve:
          type: boolean
          description: '`true` to proceed; `false` to retry the task with the feedback.'
        taskWebhookUrl:
          type: string
          format: uri
        stepWebhookUrl:
          type: string
          format: uri
        crewWebhookUrl:
          type: string
          format: uri
    ResumeResponse:
      type: object
      required:
        - status
      properties:
        status:
          type: string
          enum:
            - resumed
            - retrying
            - completed
        message:
          type: string
    Error:
      type: object
      properties:
        error:
          type: string
        details:
          type: object
          additionalProperties: true
  responses:
    BadRequest:
      description: Invalid request body or missing required inputs.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication failed; check Bearer token validity.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Resource not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ValidationError:
      description: Validation error with missing or malformed input fields.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    ServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'