---
title: "Launch an agent"
method: POST
path: "/v0/agents"
---

# Launch an agent

`POST /v0/agents`

## Request

- Base URL: `https://api.cursor.com`
- URL: `https://api.cursor.com/v0/agents`
- Auth: HTTP bearer

Start a new cloud agent to work on your repository

## Request body

- CreateAgentRequest
  - `prompt` object, required
    - `text` string, required: The task or instructions for the agent to execute
    - `images` Image[]: Optional array of base64 encoded images (max 5)
      - `data` string, required: Base64 encoded image data
      - `dimension` ImageDimension
        - `width` integer, required: Width must be a positive integer
        - `height` integer, required: Height must be a positive integer
  - `model` string: Set to an explicit model ID for launch requests, or use "default" to use the configured default model. When omitted, Cursor resolves your user default model, then your team default model, then a system default.
  - `source` object, required
    - `repository` string: The GitHub repository URL. Required unless prUrl is provided.
    - `ref` string: Git ref (branch or commit SHA) to use as the base branch
    - `prUrl` string, uri: GitHub pull request URL. When provided, the agent works on this PR's repository and branches. Mutually exclusive with repository/ref.
  - `target` object
    - `autoCreatePr` boolean: Whether to automatically create a pull request when the agent completes
    - `openAsCursorGithubApp` boolean: Whether to open the pull request as the Cursor GitHub App instead of as the user. Only applies if autoCreatePr is true.
    - `skipReviewerRequest` boolean: Whether to skip adding the user as a reviewer to the pull request. Only applies if autoCreatePr is true and the PR is opened as the Cursor GitHub App.
    - `branchName` string: Custom branch name for the agent to create
    - `autoBranch` boolean: Whether to create a new branch (true) or use the PR's existing head branch (false). Only applies when source.prUrl is provided.
  - `webhook` object
    - `url` string, uri, required: URL to receive webhook notifications about agent status changes
    - `secret` string: Secret key for webhook payload verification

## Response `201`

Agent created successfully

- object
  - `id` string, required: Unique identifier for the cloud agent
  - `name` string, required: Name for the agent
  - `status` 'CREATING', required: Initial status of the newly created agent
  - `source` object, required
    - `repository` string, required: The GitHub repository URL
    - `ref` string: Git ref (branch or commit SHA) used as the base branch
  - `target` object, required
    - `branchName` string: The Git branch name where the agent is working
    - `url` string, required: URL to view the agent in Cursor Web
    - `prUrl` string: URL of the pull request, if agent was created from a PR
    - `autoCreatePr` boolean: Whether a pull request will be automatically created
    - `openAsCursorGithubApp` boolean: Whether the pull request will be opened as the Cursor GitHub App
    - `skipReviewerRequest` boolean: Whether to skip adding the user as a reviewer to the pull request
  - `createdAt` string, date-time, required: When the agent was created

## Other responses

- `400`: Invalid request
- `401`: Unauthorized - invalid or missing API key
- `403`: Forbidden - insufficient permissions, plan limits exceeded, or storage full
- `429`: Rate limit exceeded
- `500`: Internal server error

---

[API](https://skmtc.dev/cursor/apis/cursor-cloud-agents-api.md) - [All operations](https://skmtc.dev/cursor/apis/cursor-cloud-agents-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cursor/apis/cursor-cloud-agents-api/revisions/62c9131c7ea0?raw)