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

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>"
}
'

import requests

url = "https://api.codegen.com/v1/organizations/{org_id}/agent/run"

payload = {
    "prompt": "<string>",
    "images": ["<string>"],
    "metadata": {},
    "repo_id": 123,
    "model": "<string>"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    prompt: '<string>',
    images: ['<string>'],
    metadata: {},
    repo_id: 123,
    model: '<string>'
  })
};

fetch('https://api.codegen.com/v1/organizations/{org_id}/agent/run', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.codegen.com/v1/organizations/{org_id}/agent/run",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'prompt' => '<string>',
    'images' => [
        '<string>'
    ],
    'metadata' => [
        
    ],
    'repo_id' => 123,
    'model' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.codegen.com/v1/organizations/{org_id}/agent/run"

	payload := strings.NewReader("{\n  \"prompt\": \"<string>\",\n  \"images\": [\n    \"<string>\"\n  ],\n  \"metadata\": {},\n  \"repo_id\": 123,\n  \"model\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.codegen.com/v1/organizations/{org_id}/agent/run")
  .header("Content-Type", "application/json")
  .body("{\n  \"prompt\": \"<string>\",\n  \"images\": [\n    \"<string>\"\n  ],\n  \"metadata\": {},\n  \"repo_id\": 123,\n  \"model\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.codegen.com/v1/organizations/{org_id}/agent/run")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"prompt\": \"<string>\",\n  \"images\": [\n    \"<string>\"\n  ],\n  \"metadata\": {},\n  \"repo_id\": 123,\n  \"model\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

200

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

{
  "message": "Alloted agent runs for the current billing plan have been reached. Please upgrade your plan to continue.",
  "status_code": 402
}

{
  "message": "You do not have access to this organization.",
  "status_code": 403
}

{
  "message": "No repos found in the organization. Please add some repos and try again.",
  "status_code": 404
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

{
  "message": "Rate limit exceeded. Please try again later.",
  "status_code": 429
}

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 | null

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

metadata · Metadata · object | null