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.

POST /v1/organizations/{org_id}/agent/run

Try it

Create Agent Run

cURL

curl --request POST \
  --url https://api.codegen.com/v1/organizations/{org_id}/agent/run \
  --header 'Content-Type: application/json' \
  --data '
{
  "prompt": "<string>",
  "images": [
    "<string>"
  ],
  "metadata": {},
  "repo_id": 123,
  "model": "<string>",
  "agent_type": "codegen"
}
'

200

{
  "id": 123,
  "organization_id": 123,
  "status": "<string>",
  "created_at": "<string>",
  "web_url": "<string>",
  "result": "<string>",
  "summary": "<string>",
  "source_type": "LOCAL",
  "github_pull_requests": [
    {
      "id": 123,
      "created_at": "<string>",
      "title": "<string>",
      "url": "<string>",
      "head_branch_name": "<string>"
    }
  ],
  "metadata": {}
}

Headers

Path Parameters

org_id · integer · required

Body

application/json

prompt · string · required

images · string[] | null

List of base64 encoded data URIs representing images to be processed by the agent

metadata · Metadata · object

Arbitrary JSON metadata to be stored with the agent run

repo_id · integer | null

ID of the repository to use for the agent run

model · string | null

Model to use for this agent run (optional, uses org default if not specified)

agent_type · enum<string> | null

Type of agent to use for this agent run (optional, uses org default if not specified)

Available options: codegen, claude_code

Response

200

application/json

Successful Response

Represents an agent run in API responses

id · integer · required

organization_id · integer · required

status · string | null

created_at · string | null

web_url · string | null

result · string | null

summary · string | null

source_type · enum<string> | null

Available options: LOCAL, SLACK, GITHUB, GITHUB_CHECK_SUITE, GITHUB_PR_REVIEW, LINEAR, API, CHAT, JIRA, CLICKUP, MONDAY, SETUP_COMMANDS

github_pull_requests · GithubPullRequestResponse · object[] | null

Show child attributes

github_pull_requests. id · integer · required

github_pull_requests. created_at · string · required

github_pull_requests. title · string | null

github_pull_requests. url · string | null

github_pull_requests. head_branch_name · string | null

metadata · Metadata · object