# Execute AI agent

## OpenAPI Specification

```yaml
openapi: 3.0.1
info:
  title: ''
  description: ''
  version: 1.0.0
paths:
  /agent/execute:
    post:
      summary: Execute AI agent
      deprecated: false
      description: >
        Run Claude Code, Codex CLI or Cursor CLI agent on a running environment.


        ### Project Path Structure

        Each environment has a `/workspace/` directory where projects live:

        - When you create an environment with a GitHub repo, it's cloned to
        `/workspace/{sanitized-name}`

        - You can have multiple projects in one environment under `/workspace/`

        - Specify only the project name (not full path) - we'll automatically
        prefix it with `/workspace/`


        ### Example

        If your environment was created with GitHub repo `mycompany/backend`:

        - The repo is cloned to: `/workspace/backend/`

        - Set `projectName: "backend"` (just the name, not the full path)


        If you create a new project in the environment:

        - You might create it at: `/workspace/new-feature/`

        - Set `projectName: "new-feature"`
      tags:
        - Agents
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AgentExecuteRequest'
            examples:
              basic:
                value:
                  environmentId: bded3eef-fa6d-4edf-8299-9f20091a6dd5
                  projectName: MyProject2
                  message: create a hello world
                  provider: claude
                  model: opus
                summary: Basic agent execution
              with_pr:
                value:
                  environmentId: 123e4567-e89b-12d3-a456-426614174000
                  projectName: backend
                  message: Refactor database queries
                  provider: claude
                  createBranch: true
                  createPR: true
                  githubToken: ghp_...
                summary: With GitHub PR creation
      responses:
        '200':
          description: Agent execution started (streaming response)
          content:
            text/event-stream:
              schema:
                type: string
                description: Server-sent events stream with agent progress
          headers: {}
          x-apidog-name: OK
        '400':
          description: Bad request - Missing fields or environment not running
          content:
            application/json:
              schema: &ref_0
                $ref: '#/components/schemas/Error'
          headers: {}
          x-apidog-name: Bad Request
        '404':
          description: Environment not found
          content:
            application/json:
              schema: *ref_0
          headers: {}
          x-apidog-name: Not Found
        '424':
          description: Failed dependency - Claude Code UI API key not configured
          content:
            application/json:
              schema: *ref_0
          headers: {}
          x-apidog-name: Failed Dependency
      security:
        - ApiKeyAuth: []
          x-apidog:
            schemeGroups:
              - id: nyTYV523pyZpXNGC1U365
                schemeIds:
                  - ApiKeyAuth
            required: true
            use:
              id: nyTYV523pyZpXNGC1U365
            scopes:
              nyTYV523pyZpXNGC1U365:
                ApiKeyAuth: []
      x-apidog-folder: Agents
      x-apidog-status: released
      x-run-in-apidog: https://app.eu.apidog.com/web/project/359666/apis/api-3998774-run
components:
  schemas:
    AgentExecuteRequest:
      type: object
      required:
        - environmentId
        - projectName
        - message
        - effort
      properties:
        environmentId:
          type: string
          format: uuid
          description: ID of the running environment
          examples:
            - 123e4567-e89b-12d3-a456-426614174000
        projectName:
          type: string
          description: |
            Name of the project inside /workspace/ directory.
            Just the folder name, not the full path.
          examples:
            - backend
        message:
          type: string
          description: Task description for the AI agent
          examples:
            - Add user authentication with JWT
        provider:
          type: string
          description: AI provider to use
          enum:
            - claude
            - cursor
            - codex
            - opencode
          default: claude
          x-apidog-enum:
            - value: claude
              name: ''
              description: ''
            - value: cursor
              name: ''
              description: ''
            - value: codex
              name: ''
              description: ''
            - value: opencode
              name: ''
              description: ''
        model:
          type: string
          description: >-
            Model of the provider to use. See /agent/models on which models each
            provider supports
        createBranch:
          type: boolean
          default: false
          description: Create a git branch for the changes
        createPR:
          type: boolean
          default: false
          description: Create a pull request after completion
        githubToken:
          type: string
          description: GitHub token for private repos or PR creation
          nullable: true
        effort:
          type: string
          description: Effort and reasoning effort for Claude Code and Codex
          enum:
            - low
            - medium
            - high
            - xhigh
            - max
          x-apidog-enum:
            - value: low
              name: ''
              description: ''
            - value: medium
              name: ''
              description: ''
            - value: high
              name: ''
              description: ''
            - value: xhigh
              name: ''
              description: ''
            - value: max
              name: ''
              description: ''
          nullable: true
      x-apidog-orders:
        - environmentId
        - projectName
        - message
        - provider
        - model
        - createBranch
        - createPR
        - githubToken
        - effort
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
    Error:
      type: object
      properties:
        error:
          type: string
          examples:
            - Invalid or missing API key
      x-apidog-orders:
        - error
      x-apidog-ignore-properties: []
      x-apidog-folder: ''
  securitySchemes:
    ApiKeyAuth:
      type: apikey
      in: header
      name: X-API-KEY
      description: API key obtained from the CloudCLI dashboard
servers:
  - url: https://cloudcli.ai/api/v1
    description: Production API
security:
  - ApiKeyAuth: []
    x-apidog:
      schemeGroups:
        - id: nyTYV523pyZpXNGC1U365
          schemeIds:
            - ApiKeyAuth
      required: true
      use:
        id: nyTYV523pyZpXNGC1U365
      scopes:
        nyTYV523pyZpXNGC1U365:
          ApiKeyAuth: []

```