Cursor v1 cloud apis [branchName is giving validation error]

Support Bug Reports
,
1

Where does the bug appear (feature/product)?

Cursor Cloud agent apis

Describe the Bug

In the latest v1 Cursor API for launching an agent, there is a parameter named branchName. However, when it is included in the request, it throws a validation error.

URL:

https://api.cursor.com/v1/agents

Request Body:

{
  "prompt": {
    "text": "some dummy prompt"
  },
  "repos": [
    {
      "url": "https://github.com/some-org/genai-foundation-service.git",
      "startingRef": "master-ci"
    }
  ],
  "branchName": "codingagent/agent-test154-caa7a723",
  "autoCreatePR": true
}

Error:

{
  "error": {
    "code": "validation_error",
    "message": "Unrecognized key(s) in object: 'branchName'"
  }
}

Steps to Reproduce

Call the v1/agents endpoint with the branchName field included in the request body.

Expected Behavior

The API should accept the request and create the agent successfully.

Operating System

Windows 10/11

Version Information

cursor-cloud-agents

Does this stop you from using Cursor?

Yes — Cursor is unusable.

6

You’re right, and this is on us. The v1 API contract was updated recently to remove the branchName field, but the docs and OpenAPI spec weren’t updated to match. We have a fix for the docs in progress.

Workaround: Drop branchName from the request body. The agent will auto-generate a branch name (typically cursor/<task-summary>). To find the branch it created, poll GET /v1/agents/{id}/runs/{runId} after creation. Once the agent pushes, the response includes run.git.branches[0].branch with the actual branch name.

If you need to work on an existing PR’s branch, pass repos[0].prUrl and set workOnCurrentBranch: true. The agent will commit to that PR’s head branch instead of creating a new one.

The v1 API doesn’t currently support specifying a custom branch name.

7

ok got it, but is there a way to use custom branch name or let the cursor agent create custom branch name and use it to create pr and stuff

what I have tried so far
in the prompt only I mention some branch name so it did created the branch however
after code changes when it tried to create a pr, it ran into issues:

it can create pr only for branches cursor/some-branch but not anything else meaning custom branch
for custom branch it says

  • gh pr create failed with Resource not accessible by integration (createPullRequest) — the token behind gh in this environment cannot create PRs on that repo.

but if we try to create Pr with cursor/some-branch then it works meaning the tool call for creating the pr is getting success

The solution:-
in the tool call for creating the PR which cursor uses we can pass the curent branch we have created by cursor