AskUI agent-executions API

openapi: 3.2.0
info:
  title: AskUI Workspaces access-tokens Agent Executions API
  version: 0.2.15
servers:
- url: https://workspaces.askui.com
  description: Base URL declared by the provider in apis.yml (roadmap#122).
tags:
- name: agent-executions
paths:
  /api/v1/agent-executions:
    post:
      tags:
      - agent-executions
      summary: Create Agent Execution
      operationId: create_agent_execution_api_v1_agent_executions_post
      security:
      - Bearer: []
      - Basic: []
      parameters:
      - name: agent_id
        in: query
        required: true
        schema:
          type: string
          format: uuid4
          title: Agent Id
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_create_agent_execution_api_v1_agent_executions_post'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentExecution'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    get:
      tags:
      - agent-executions
      summary: List Agent Executions
      description: List all agent executions matching the query parameters sorted anti-chronologically by when they were last updated (`updated_at`).
      operationId: list_agent_executions_api_v1_agent_executions_get
      security:
      - Bearer: []
      - Basic: []
      parameters:
      - name: agent_execution_id
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
              format: uuid4
          - type: 'null'
          title: Agent Execution Id
      - name: agent_id
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
              format: uuid4
          - type: 'null'
          title: Agent Id
      - name: workspace_id
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              type: string
              format: uuid4
          - type: 'null'
          title: Workspace Id
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              enum:
              - PENDING_INPUTS
              - PENDING_DATA_EXTRACTION
              - PENDING_REVIEW
              - CANCELED
              - CONFIRMED
              - DELIVERED_TO_DESTINATION
              type: string
          - type: 'null'
          title: Status
      - name: skip
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Skip
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 100
          title: Limit
      - name: expand
        in: query
        required: false
        schema:
          anyOf:
          - type: array
            items:
              const: total_count
              type: string
          - type: 'null'
          description: 'total_count: Include the total number of agent executions that match the query, only accurate up to 100.'
          title: Expand
        description: 'total_count: Include the total number of agent executions that match the query, only accurate up to 100.'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentExecutionsListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/agent-executions/{agent_execution_id}:
    patch:
      tags:
      - agent-executions
      summary: Update Agent Execution
      operationId: update_agent_execution_api_v1_agent_executions__agent_execution_id__patch
      security:
      - Bearer: []
      - Basic: []
      parameters:
      - name: agent_execution_id
        in: path
        required: true
        schema:
          type: string
          format: uuid4
          title: Agent Execution Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentExecutionUpdateCommand'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentExecution'
        '404':
          description: Agent execution not found
        '409':
          description: Agent schema not set
        '422':
          description: Schema validation error
        '400':
          description: Could not deliver data to destination
components:
  schemas:
    AgentExecutionPendingReview:
      properties:
        status:
          type: string
          const: PENDING_REVIEW
          title: Status
          default: PENDING_REVIEW
        dataExtracted:
          additionalProperties: true
          type: object
          minProperties: 1
          title: Dataextracted
      type: object
      required:
      - dataExtracted
      title: AgentExecutionPendingReview
    AgentExecutionCancel:
      properties:
        status:
          type: string
          const: CANCELED
          title: Status
          default: CANCELED
      type: object
      title: AgentExecutionCancel
    AgentExecutionStateCanceled:
      properties:
        status:
          type: string
          const: CANCELED
          title: Status
          description: The agent execution was canceled by the user.
          default: CANCELED
        dataExtracted:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Dataextracted
      type: object
      title: AgentExecutionStateCanceled
    DataDestinationDeliveryAskUiWorkflow:
      properties:
        type:
          type: string
          const: ASKUI_WORKFLOW
          title: Type
          default: ASKUI_WORKFLOW
        scheduleId:
          type: string
          title: Scheduleid
      type: object
      required:
      - scheduleId
      title: DataDestinationDeliveryAskUiWorkflow
    workspaces__use_cases__agent_executions__update_agent_execution__AgentExecutionStateDeliveredToDestination:
      properties:
        status:
          type: string
          const: DELIVERED_TO_DESTINATION
          title: Status
          default: DELIVERED_TO_DESTINATION
        deliveries:
          items:
            oneOf:
            - $ref: '#/components/schemas/DataDestinationDeliveryAskUiWorkflow'
            - $ref: '#/components/schemas/DataDestinationDeliveryWebhook'
            discriminator:
              propertyName: type
              mapping:
                ASKUI_WORKFLOW: '#/components/schemas/DataDestinationDeliveryAskUiWorkflow'
                WEBHOOK: '#/components/schemas/DataDestinationDeliveryWebhook'
          type: array
          title: Deliveries
      type: object
      title: AgentExecutionStateDeliveredToDestination
    AgentExecutionConfirm:
      properties:
        status:
          type: string
          const: CONFIRMED
          title: Status
          default: CONFIRMED
        dataConfirmed:
          additionalProperties: true
          type: object
          minProperties: 1
          title: Dataconfirmed
      type: object
      required:
      - dataConfirmed
      title: AgentExecutionConfirm
    workspaces__domain__entities__AgentExecutionStateDeliveredToDestination:
      properties:
        status:
          type: string
          const: DELIVERED_TO_DESTINATION
          title: Status
          description: The extracted data was successfully delivered to the destination(s), e.g., an AskUI workflow invoked with the data.
          default: DELIVERED_TO_DESTINATION
        dataExtracted:
          additionalProperties: true
          type: object
          title: Dataextracted
        dataConfirmed:
          additionalProperties: true
          type: object
          title: Dataconfirmed
        deliveries:
          items:
            oneOf:
            - $ref: '#/components/schemas/DataDestinationDeliveryAskUiWorkflow'
            - $ref: '#/components/schemas/DataDestinationDeliveryWebhook'
            discriminator:
              propertyName: type
              mapping:
                ASKUI_WORKFLOW: '#/components/schemas/DataDestinationDeliveryAskUiWorkflow'
                WEBHOOK: '#/components/schemas/DataDestinationDeliveryWebhook'
          type: array
          title: Deliveries
      type: object
      required:
      - dataExtracted
      - dataConfirmed
      title: AgentExecutionStateDeliveredToDestination
    AgentExecution:
      properties:
        id:
          type: string
          format: uuid4
          title: Id
        createdAt:
          type: string
          format: date-time
          title: Createdat
        updatedAt:
          type: string
          format: date-time
          title: Updatedat
        agentId:
          type: string
          format: uuid4
          title: Agentid
        workspaceId:
          type: string
          format: uuid4
          title: Workspaceid
        state:
          oneOf:
          - $ref: '#/components/schemas/AgentExecutionStatePendingInputs'
          - $ref: '#/components/schemas/AgentExecutionStatePendingDataExtraction'
          - $ref: '#/components/schemas/AgentExecutionStatePendingReview'
          - $ref: '#/components/schemas/AgentExecutionStateCanceled'
          - $ref: '#/components/schemas/AgentExecutionStateConfirmed'
          - $ref: '#/components/schemas/workspaces__domain__entities__AgentExecutionStateDeliveredToDestination'
          title: State
          discriminator:
            propertyName: status
            mapping:
              CANCELED: '#/components/schemas/AgentExecutionStateCanceled'
              CONFIRMED: '#/components/schemas/AgentExecutionStateConfirmed'
              DELIVERED_TO_DESTINATION: '#/components/schemas/AgentExecutionStateDeliveredToDestination-Output'
              PENDING_DATA_EXTRACTION: '#/components/schemas/AgentExecutionStatePendingDataExtraction'
              PENDING_INPUTS: '#/components/schemas/AgentExecutionStatePendingInputs'
              PENDING_REVIEW: '#/components/schemas/AgentExecutionStatePendingReview'
      type: object
      required:
      - agentId
      - workspaceId
      - state
      title: AgentExecution
    AgentExecutionUpdateCommand:
      properties:
        state:
          oneOf:
          - $ref: '#/components/schemas/AgentExecutionPendingReview'
          - $ref: '#/components/schemas/AgentExecutionCancel'
          - $ref: '#/components/schemas/AgentExecutionConfirm'
          - $ref: '#/components/schemas/workspaces__use_cases__agent_executions__update_agent_execution__AgentExecutionStateDeliveredToDestination'
          title: State
          discriminator:
            propertyName: status
            mapping:
              CANCELED: '#/components/schemas/AgentExecutionCancel'
              CONFIRMED: '#/components/schemas/AgentExecutionConfirm'
              DELIVERED_TO_DESTINATION: '#/components/schemas/AgentExecutionStateDeliveredToDestination-Input'
              PENDING_REVIEW: '#/components/schemas/AgentExecutionPendingReview'
      type: object
      required:
      - state
      title: AgentExecutionUpdateCommand
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AgentExecutionStatePendingDataExtraction:
      properties:
        status:
          type: string
          const: PENDING_DATA_EXTRACTION
          title: Status
          description: The agent has all inputs at hand and is about to or already extracting data from inputs. An agent may stay in this state in failure cases, e.g., if data extraction fails.
          default: PENDING_DATA_EXTRACTION
      type: object
      title: AgentExecutionStatePendingDataExtraction
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    AgentExecutionStatePendingInputs:
      properties:
        status:
          type: string
          const: PENDING_INPUTS
          title: Status
          description: The agent is waiting for inputs, e.g., files to be uploaded. An agent may stay in this state in failure cases, e.g., if file upload fails.
          default: PENDING_INPUTS
      type: object
      title: AgentExecutionStatePendingInputs
    WebhookResponse:
      properties:
        statusCode:
          type: integer
          title: Statuscode
        headers:
          additionalProperties:
            type: string
          type: object
          title: Headers
        body:
          type: string
          title: Body
      type: object
      required:
      - statusCode
      - headers
      - body
      title: WebhookResponse
    AgentExecutionStateConfirmed:
      properties:
        status:
          type: string
          const: CONFIRMED
          title: Status
          description: The user confirmed the extracted data.
          default: CONFIRMED
        dataExtracted:
          additionalProperties: true
          type: object
          minProperties: 1
          title: Dataextracted
        dataConfirmed:
          additionalProperties: true
          type: object
          minProperties: 1
          title: Dataconfirmed
      type: object
      required:
      - dataExtracted
      - dataConfirmed
      title: AgentExecutionStateConfirmed
    AgentExecutionStatePendingReview:
      properties:
        status:
          type: string
          const: PENDING_REVIEW
          title: Status
          description: The agent is waiting for the user to review the extracted data. An agent may stay if the user never confirms the data or cancels the execution.
          default: PENDING_REVIEW
        dataExtracted:
          additionalProperties: true
          type: object
          minProperties: 1
          title: Dataextracted
      type: object
      required:
      - dataExtracted
      title: AgentExecutionStatePendingReview
    AgentExecutionsListResponse:
      properties:
        data:
          items:
            $ref: '#/components/schemas/AgentExecution'
          type: array
          title: Data
        hasMore:
          type: boolean
          title: Hasmore
          description: Whether there are more agent executions that match the query that were not included in this response.
          default: false
        totalCount:
          anyOf:
          - type: integer
          - type: 'null'
          title: Totalcount
          description: The total number of agent executions that match the query, only accurate up to 100.
      type: object
      required:
      - data
      title: AgentExecutionsListResponse
    Body_create_agent_execution_api_v1_agent_executions_post:
      properties:
        input_files:
          items:
            type: string
            format: binary
          type: array
          minItems: 1
          title: Input Files
          description: 'Files to extract data from. Supported file extensions: {''.jpeg'', ''.txt'', ''.jpg'', ''.webp'', ''.pdf'', ''.png'', ''.gif'', ''.eml''}. Maximum total size: 100 MiB. We process the .eml files as text files, i.e., we don''t process non-textual attachments and content properly. For that, extract them from the .eml files separating them into different files.'
      type: object
      required:
      - input_files
      title: Body_create_agent_execution_api_v1_agent_executions_post
    DataDestinationDeliveryWebhook:
      properties:
        type:
          type: string
          const: WEBHOOK
          title: Type
          default: WEBHOOK
        response:
          $ref: '#/components/schemas/WebhookResponse'
      type: object
      required:
      - response
      title: DataDestinationDeliveryWebhook
  securitySchemes:
    Bearer:
      type: http
      scheme: bearer
    Basic:
      type: apiKey
      in: header
      name: Authorization