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

# Create Agent Run

> Create a new agent run.

Creates and initiates a long-running agent process based on the provided prompt.
The process will complete asynchronously, and the response contains the agent run ID
which can be used to check the status later. The requesting user must be a member
of the specified organization.

This endpoint accepts both a text prompt and an optional image file upload.

Rate limit: 10 requests per minute.



## OpenAPI

````yaml api-reference/openapi3.json post /v1/organizations/{org_id}/agent/run
openapi: 3.1.0
info:
  title: Developer API
  description: API for application developers
  version: 1.0.0
servers:
  - url: https://api.codegen.com
    description: Codegen API
security: []
paths:
  /v1/organizations/{org_id}/agent/run:
    post:
      tags:
        - agents
        - agents
        - agents
      summary: Create Agent Run
      description: >-
        Create a new agent run.


        Creates and initiates a long-running agent process based on the provided
        prompt.

        The process will complete asynchronously, and the response contains the
        agent run ID

        which can be used to check the status later. The requesting user must be
        a member

        of the specified organization.


        This endpoint accepts both a text prompt and an optional image file
        upload.


        Rate limit: 10 requests per minute.
      operationId: create_agent_run_v1_organizations__org_id__agent_run_post
      parameters:
        - name: org_id
          in: path
          required: true
          schema:
            type: integer
            title: Org Id
        - name: authorization
          in: header
          required: false
          schema:
            title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentRunInput'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRunResponse'
        '402':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentRunLimitReachedErrorResponse'
          description: Payment Required
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PermissionsErrorResponse'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NoReposFoundInOrgErrorResponse'
          description: Not Found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIRateLimitErrorResponse'
          description: Too Many Requests
components:
  schemas:
    CreateAgentRunInput:
      properties:
        prompt:
          type: string
          title: Prompt
        images:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Images
          description: >-
            List of base64 encoded data URIs representing images to be processed
            by the agent
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
          description: Arbitrary JSON metadata to be stored with the agent run
        repo_id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Repo Id
          description: ID of the repository to use for the agent run
        model:
          anyOf:
            - type: string
            - type: 'null'
          title: Model
          description: >-
            Model to use for this agent run (optional, uses org default if not
            specified)
        agent_type:
          anyOf:
            - type: string
              enum:
                - codegen
                - claude_code
            - type: 'null'
          title: Agent Type
          description: >-
            Type of agent to use for this agent run (optional, uses org default
            if not specified)
      type: object
      required:
        - prompt
      title: CreateAgentRunInput
    AgentRunResponse:
      properties:
        id:
          type: integer
          title: Id
        organization_id:
          type: integer
          title: Organization Id
        status:
          anyOf:
            - type: string
            - type: 'null'
          title: Status
        created_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Created At
        web_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Web Url
        result:
          anyOf:
            - type: string
            - type: 'null'
          title: Result
        summary:
          anyOf:
            - type: string
            - type: 'null'
          title: Summary
        source_type:
          anyOf:
            - $ref: '#/components/schemas/ApiAgentRunSourceType'
            - type: 'null'
        github_pull_requests:
          anyOf:
            - items:
                $ref: '#/components/schemas/GithubPullRequestResponse'
              type: array
            - type: 'null'
          title: Github Pull Requests
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Metadata
      type: object
      required:
        - id
        - organization_id
      title: AgentRunResponse
      description: Represents an agent run in API responses
    AgentRunLimitReachedErrorResponse:
      properties:
        message:
          type: string
          title: Message
          default: >-
            Alloted agent runs for the current billing plan have been reached.
            Please upgrade your plan to continue.
        status_code:
          type: integer
          title: Status Code
          default: 402
      type: object
      title: AgentRunLimitReachedErrorResponse
    PermissionsErrorResponse:
      properties:
        message:
          type: string
          title: Message
          default: You do not have access to this organization.
        status_code:
          type: integer
          title: Status Code
          default: 403
      type: object
      title: PermissionsErrorResponse
    NoReposFoundInOrgErrorResponse:
      properties:
        message:
          type: string
          title: Message
          default: >-
            No repos found in the organization. Please add some repos and try
            again.
        status_code:
          type: integer
          title: Status Code
          default: 404
      type: object
      title: NoReposFoundInOrgErrorResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    APIRateLimitErrorResponse:
      properties:
        message:
          type: string
          title: Message
          default: Rate limit exceeded. Please try again later.
        status_code:
          type: integer
          title: Status Code
          default: 429
      type: object
      title: APIRateLimitErrorResponse
    ApiAgentRunSourceType:
      type: string
      enum:
        - LOCAL
        - SLACK
        - GITHUB
        - GITHUB_CHECK_SUITE
        - GITHUB_PR_REVIEW
        - LINEAR
        - API
        - CHAT
        - JIRA
        - CLICKUP
        - MONDAY
        - SETUP_COMMANDS
      title: ApiAgentRunSourceType
    GithubPullRequestResponse:
      properties:
        id:
          type: integer
          title: Id
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
        created_at:
          type: string
          title: Created At
        head_branch_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Head Branch Name
      type: object
      required:
        - id
        - created_at
      title: GithubPullRequestResponse
    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

````