API reference

Import everything from the public package:

from cursor_agent import (
    SyncClient,
    AsyncClient,
    Agent,
    AsyncAgent,
    CursorAPIError,
    CursorClient,
    DEFAULT_BASE_URL,
)

CursorClient is an alias for cursor_agent.SyncClient.

class cursor_agent.Agent(client: SyncClient, *, repo: str | None = None, ref: str | None = None, pr_url: str | None = None)

Bases: object

One Agent instance maps to one Cursor cloud agent (one id from the API).

Use with SyncClient. Call create() once (POST /v0/agents), then follow_up() for further prompts. Or attach() and follow_up() only.

property id: str | None

create(prompt: str, *, model: str | None = None, target: dict[str, Any] | None = None, webhook: dict[str, Any] | None = None, images: list[dict[str, Any]] | None = None) → dict[str, Any]

Create the cloud agent (POST /v0/agents).

Requires repo / pr_url from SyncClient.new_agent(). Call at most once per Agent instance; for more prompts use follow_up().

follow_up(prompt: str, *, images: list[dict[str, Any]] | None = None) → dict[str, Any]

POST /v0/agents/{id}/followup — send another prompt to the same cloud agent.

refresh() → dict[str, Any]

GET /v0/agents/{id} — latest status (requires create() or attach()).

conversation() → dict[str, Any]

GET /v0/agents/{id}/conversation.

stop() → dict[str, Any]

POST /v0/agents/{id}/stop.

delete() → dict[str, Any]

DELETE /v0/agents/{id}.

attach(agent_id: str) → None

Use an existing agent id (e.g. from a previous session) for follow-ups and status.

class cursor_agent.AsyncAgent(client: AsyncClient, *, repo: str | None = None, ref: str | None = None, pr_url: str | None = None)

Bases: object

Async counterpart to Agent for use with AsyncClient.

Methods mirror Agent but are async.

property id: str | None

async create(prompt: str, *, model: str | None = None, target: dict[str, Any] | None = None, webhook: dict[str, Any] | None = None, images: list[dict[str, Any]] | None = None) → dict[str, Any]

async follow_up(prompt: str, *, images: list[dict[str, Any]] | None = None) → dict[str, Any]

async refresh() → dict[str, Any]

async conversation() → dict[str, Any]

async stop() → dict[str, Any]

async delete() → dict[str, Any]

attach(agent_id: str) → None

class cursor_agent.AsyncClient(api_key: str, *, base_url: str = 'https://api.cursor.com', timeout: float = 120.0)

Bases: object

Async client for the Cursor Cloud Agents API (httpx.AsyncClient).

Use async with AsyncClient(...) or call aclose() when done.

classmethod from_httpx_client(client: AsyncClient) → AsyncClient

Wrap an existing httpx.AsyncClient (you manage base URL and auth).

async aclose() → None

new_agent(repo: str | None = None, *, ref: str | None = None, pr_url: str | None = None) → AsyncAgent

async me() → dict[str, Any]

async list_models() → dict[str, Any]

async list_repositories() → dict[str, Any]

async list_agents() → dict[str, Any]

async get_agent(agent_id: str) → dict[str, Any]

async get_conversation(agent_id: str) → dict[str, Any]

async launch_agent(*, prompt: str, repository: str | None = None, ref: str | None = None, pr_url: str | None = None, model: str | None = None, target: dict[str, Any] | None = None, webhook: dict[str, Any] | None = None, images: list[dict[str, Any]] | None = None) → dict[str, Any]

async followup(agent_id: str, *, prompt: str, images: list[dict[str, Any]] | None = None) → dict[str, Any]

async stop_agent(agent_id: str) → dict[str, Any]

async delete_agent(agent_id: str) → dict[str, Any]

exception cursor_agent.CursorAPIError(message: str, *, status_code: int | None = None, response: Response | None = None)

Bases: Exception

Raised when the API returns an error response.

cursor_agent.CursorClient

alias of SyncClient

class cursor_agent.SyncClient(api_key: str, *, base_url: str = 'https://api.cursor.com', timeout: float = 120.0)

Bases: object

Synchronous client for the Cursor Cloud Agents API.

See https://cursor.com/docs/cloud-agent/api/endpoints

Authentication uses HTTP Basic auth: API key as username, empty password (equivalent to curl -u YOUR_API_KEY: ...).

classmethod from_httpx_client(client: Client) → SyncClient

Wrap an existing httpx.Client (you manage base URL and auth).

close() → None

new_agent(repo: str | None = None, *, ref: str | None = None, pr_url: str | None = None) → Agent

Create an Agent bound to a GitHub repo or PR.

Pass repo (repository URL) or pr_url — same rules as POST /v0/agents source. Use Agent.create() for the first prompt, then Agent.follow_up() for more.

me() → dict[str, Any]

GET /v0/me — API key metadata.

list_models() → dict[str, Any]

GET /v0/models — models available for agents.

list_repositories() → dict[str, Any]

GET /v0/repositories — GitHub repositories accessible to the key.

list_agents() → dict[str, Any]

GET /v0/agents — list cloud agents.

get_agent(agent_id: str) → dict[str, Any]

GET /v0/agents/{id} — agent status and details.

get_conversation(agent_id: str) → dict[str, Any]

GET /v0/agents/{id}/conversation.

launch_agent(*, prompt: str, repository: str | None = None, ref: str | None = None, pr_url: str | None = None, model: str | None = None, target: dict[str, Any] | None = None, webhook: dict[str, Any] | None = None, images: list[dict[str, Any]] | None = None) → dict[str, Any]

POST /v0/agents — start a new agent.

Provide either repository (and optionally ref) or pr_url for the source.

followup(agent_id: str, *, prompt: str, images: list[dict[str, Any]] | None = None) → dict[str, Any]

POST /v0/agents/{id}/followup.

stop_agent(agent_id: str) → dict[str, Any]

POST /v0/agents/{id}/stop.

delete_agent(agent_id: str) → dict[str, Any]

DELETE /v0/agents/{id}.