> ## Documentation Index
> Fetch the complete documentation index at: https://docs.webagent.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Run Agent



## OpenAPI

````yaml self-hosted-api-reference/openapi.json post /api/runs
openapi: 3.1.0
info:
  title: Webagent API
  description: API to execute automated tasks on browser using different LLM providers.
  version: 0.1.0
servers: []
security: []
paths:
  /api/runs:
    post:
      summary: Run Agent
      operationId: run_agent_api_runs_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                anyOf:
                  - $ref: '#/components/schemas/AgentResponse'
                  - $ref: '#/components/schemas/AsyncAgentResponse'
                title: Response Run Agent Api Runs Post
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    AgentRequest:
      properties:
        prompt:
          type: string
          minLength: 3
          title: Prompt
          description: The task to be performed by the agent
        model:
          type: string
          title: Model
          default: o3
        provider:
          $ref: '#/components/schemas/ProviderEnum'
          default: openai
        wait_for_completion:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Wait For Completion
          description: >-
            Whether to wait for the task to complete before returning the
            response. If false, the task will be executed in the background and
            the response will contain only the task ID.
          default: true
        webhook_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Webhook Url
          description: URL to send webhook notification when task is complete
        response_format:
          anyOf:
            - type: string
            - type: 'null'
          title: Response Format
          description: Whether to return the result as text or JSON
          default: text
        json_schema:
          anyOf:
            - type: string
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Json Schema
          description: The JSON schema for the task result
        use_cached_workflow:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Use Cached Workflow
          description: 'Internal field: whether to use cached workflow'
        cached_workflow:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Cached Workflow
          description: 'Internal field: the cached workflow data'
      type: object
      required:
        - prompt
      title: AgentRequest
    AgentResponse:
      properties:
        task_id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Task Id
          description: The ID of the task
        task_run_id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Task Run Id
          description: The ID of the task run
        history:
          anyOf:
            - items:
                $ref: '#/components/schemas/HistoryItem'
              type: array
            - type: 'null'
          title: History
          description: List of steps in the history
        result:
          anyOf:
            - {}
            - type: 'null'
          title: Result
          description: The final result of the agent's task
        is_done:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Done
          description: Whether the agent has completed its task
        is_successful:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Successful
          description: Whether the agent was successful in completing its task
        status:
          $ref: '#/components/schemas/StatusEnum'
          description: The status of the agent's task
          default: in_progress
      type: object
      title: AgentResponse
      description: Represents the complete response from the agent.
    AsyncAgentResponse:
      properties:
        task_id:
          type: integer
          title: Task Id
          description: The ID of the created task
        task_run_id:
          type: integer
          title: Task Run Id
          description: The ID of the created task run
      type: object
      required:
        - task_id
        - task_run_id
      title: AsyncAgentResponse
      description: Represents the response from the async agent endpoint.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ProviderEnum:
      type: string
      enum:
        - openai
        - deepseek
        - anthropic
        - google
        - groq
        - mistral
        - together
      title: ProviderEnum
    HistoryItem:
      properties:
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: Description of the step
        actions:
          anyOf:
            - items:
                $ref: '#/components/schemas/Action'
              type: array
            - type: 'null'
          title: Actions
          description: List of actions taken in this step
      type: object
      title: HistoryItem
      description: Represents an individual step in the agent's history.
    StatusEnum:
      type: string
      enum:
        - success
        - failure
        - in_progress
      title: StatusEnum
    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
    Action:
      properties:
        name:
          type: string
          title: Name
          description: Name of the action
        params:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Params
          description: Parameters for the action
        is_done:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Is Done
          description: Whether the action is done
        success:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Success
          description: Whether the action was successful
        extracted_content:
          anyOf:
            - type: string
            - type: 'null'
          title: Extracted Content
          description: Content extracted from the action
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
          description: Error message if any
        include_in_memory:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Include In Memory
          description: Whether to include this action in memory
      type: object
      required:
        - name
      title: Action
      description: Represents an action

````