Cloud Agents API v1: POST /v1/agents returns VALIDATION_ERROR for documented request

Support Bug Reports
,
1

Where does the bug appear (feature/product)?

Cloud Agent (GitHub, Slack, Web, Linear)

Describe the Bug

The Cloud Agents API v1 POST /v1/agents endpoint returns HTTP 400 with VALIDATION_ERROR for a minimal request using documented fields.

The request contains:

  • a client-supplied agentId in the documented bc-{UUID} format,
  • prompt.text,
  • one GitHub repository,
  • an exact 40-character Git commit SHA as repos[0].startingRef,
  • autoCreatePR: false.

The request does not include envVars, model, mode, branchName, workOnCurrentBranch, prUrl, mcpServers, or subagents.

The API returns VALIDATION_ERROR but does not provide enough field-level information to determine which documented field or combination is being rejected.

No Cloud Agent is created.

Steps to Reproduce

  1. Use a valid Cloud Agents API v1 API key and a repository accessible to Cursor.

  2. Choose an existing Git commit SHA in that repository.

  3. Generate a client-supplied agent ID in the documented format:
    bc-{UUID}

  4. Send POST /v1/agents with a request equivalent to:

{
“agentId”: “bc-{SERVER-GENERATED-UUID}”,
“prompt”: {
“text”: “NON-SECRET-PROMPT-TEXT”
},
“repos”: [
{
“url”: “https://github.com/ORG/REPOSITORY”,
“startingRef”: “40-CHARACTER-GIT-COMMIT-SHA”
}
],
“autoCreatePR”: false
}

  1. Observe that the API responds with HTTP 400 and VALIDATION_ERROR.

  2. Check the same intended agent ID using GET only. In our case, two independent 404 responses separated by more than 60 seconds confirmed that the agent had not been created.

We did not retry the POST, to avoid accidentally creating a duplicate paid agent.

Expected Behavior

The API should either:

  1. accept the documented request and return the created agent and its initial run,

or

  1. return a validation error that clearly identifies the rejected field, field combination, or constraint.

If there is an undocumented restriction involving client-supplied agentId, an exact commit SHA in startingRef, or their combination, it should be documented or exposed clearly in the validation response.

Operating System

Windows 10/11

Version Information

Cloud Agents API v1

For AI issues: which model did you use?

Not applicable — no model was specified in the API request. The request fails during agent creation before an agent is created.

Additional Information

This appears to be isolated to the Cloud Agents API v1 agent-creation request.

Other Cloud Agent workflows continue to work. The issue appears specific to this agent-creation request.

We intentionally did not modify the request shape or repeatedly retry the POST after receiving the validation error.

Could you please confirm:

  1. Is the minimal request shown above valid for POST /v1/agents?

  2. If not, which field or field combination is rejected?

  3. Is there an undocumented constraint involving a client-supplied agentId together with an exact Git commit SHA in repos[0].startingRef?

  4. Could the validation response consistently expose the rejected field or constraint?

envVars were intentionally omitted because the request uses a client-supplied agentId.

Does this stop you from using Cursor

Sometimes - I can sometimes use Cursor

7

Hey there! Thanks for the clear write-up.

Your request shape is fine. The reject is the SHA in repos[0].startingRef, not agentId or any field combo.

A full commit SHA only works if that commit is on the default branch, or on a same-repo PR. A tip of an unmerged branch with no PR open gets a 400. That rule isn’t in the docs today - we’ve let the team know.

The response body is also fully generic (validation_error / [invalid_argument] Error), so there’s nothing more to pull from it on your side. We’ve let the team know that should name the field and reason.

To unblock right now:

  1. Pass a branch name as startingRef (e.g. your feature branch)
  2. Pass a SHA already on the default branch
  3. Open a PR for the commit, then pass that SHA or prUrl

Caveat on (1): a branch name resolves to HEAD at start time, so it isn’t a pin the way a SHA is. If pinning matters, use (3).

Cloud Agents API - Endpoints