---
title: "Create Agent Run"
method: POST
path: "/v1/organizations/{org_id}/agent/run"
tags: ["agents", "agents", "agents"]
---

# Create Agent Run

`POST /v1/organizations/{org_id}/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.

## Path parameters

- `org_id` integer, required

## Headers

- `authorization` unknown

## Request body

- CreateAgentRunInput
  - `prompt` string, required
  - `images` string[], nullable — List of base64 encoded data URIs representing images to be processed by the agent
  - `metadata` object, nullable — Arbitrary JSON metadata to be stored with the agent run
  - `repo_id` integer, nullable — ID of the repository to use for the agent run
  - `model` string, nullable — Model to use for this agent run (optional, uses org default if not specified)
  - `agent_type` 'codegen' | 'claude_code', nullable — Type of agent to use for this agent run (optional, uses org default if not specified)

## Response `200`

Successful Response

- AgentRunResponse — Represents an agent run in API responses
  - `id` integer, required
  - `organization_id` integer, required
  - `status` string, nullable
  - `created_at` string, nullable
  - `web_url` string, nullable
  - `result` string, nullable
  - `summary` string, nullable
  - `source_type` 'LOCAL' | 'SLACK' | 'GITHUB' | 'GITHUB_CHECK_SUITE' | 'GITHUB_PR_REVIEW' | 'LINEAR' | 'API' | 'CHAT' | 'JIRA' | 'CLICKUP' | 'MONDAY' | 'SETUP_COMMANDS'
  - `github_pull_requests` GithubPullRequestResponse[], nullable
    - `id` integer, required
    - `title` string, nullable
    - `url` string, nullable
    - `created_at` string, required
    - `head_branch_name` string, nullable
  - `metadata` object, nullable

## Other responses

- `402` — Payment Required
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `429` — Too Many Requests

## Changes

- **2025-09-22** `2acd27225236` — 1 info
  - added the new optional request property `agent_type`
- **2025-08-21** `a0215d4f2c07` — 1 warning
  - added the new `SETUP_COMMANDS` enum value to the `source_type/anyOf[subschema #1: ApiAgentRunSourceType]/` response property for the response status `200`
- **2025-08-15** `69bfde65bf75` — 4 breaking, 3 warning, 4 info
  - the response property `github_pull_requests/anyOf[subschema #1]/items/title` became optional for the status `200`
  - the response property `github_pull_requests/anyOf[subschema #1]/items/url` became optional for the status `200`
  - response property `github_pull_requests/anyOf[subschema #1]/items/title` list-of-types was widened by adding types `null` to media type `application/json` of response `200`
  - response property `github_pull_requests/anyOf[subschema #1]/items/url` list-of-types was widened by adding types `null` to media type `application/json` of response `200`
  - …7 more
- **2025-06-26** `4b2b8862eea6` — 3 info
  - added the new optional request property `metadata`
  - added the optional property `github_pull_requests` to the response with the `200` status
  - added the optional property `metadata` to the response with the `200` status
- **2025-06-13** `70e15e0c5ef2` — 1 info
  - added the optional property `source_type` to the response with the `200` status

[Full history](https://skmtc.dev/codegen-sh/apis/developer-api/changes/v1/organizations/:org_id/agent/run/post.md)

---

[API](https://skmtc.dev/codegen-sh/apis/developer-api.md) · [All operations](https://skmtc.dev/codegen-sh/apis/developer-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/codegen-sh/developer-api/revisions/e68a3133f727/schema)