{"openapi":"3.1.0","info":{"title":"Cursor Cloud Agents (BYOK) API","version":"0.1.0","description":"Cursor Cloud Agents (BYOK) lets an AI assistant read your own Cursor Cloud Agents data through the Cursor Cloud Agents API with a key you supply (Cursor API key). Read-only: 8 tools (get_api_key_info, list_models, list_agents, get_agent, list_agent_runs, get_run, get_agent_usage, list_environments). The BYOK key travels with each request, is used for that one call only and is never stored, logged...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-cursor-cloud-agents.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-cursor-cloud-agents/docs"},"termsOfService":"https://connectorbay.com/byok-cursor-cloud-agents/terms"},"servers":[{"url":"https://byok-cursor-cloud-agents.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-cursor-cloud-agents/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_api_key_info":{"post":{"operationId":"get_api_key_info","summary":"Show the name and creation time of the API key in use. The owner's name and email are not returned. Reads status only: i","description":"Show the name and creation time of the API key in use. The owner's name and email are not returned. Reads status only: it starts, changes or stops no agent run. Use for \"Which Cursor API key am I using and when was it created\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_api_key_infoArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_models":{"post":{"operationId":"list_models","summary":"List the recommended models that can be chosen for a cloud agent, with display name, aliases, tunable parameters and var","description":"List the recommended models that can be chosen for a cloud agent, with display name, aliases, tunable parameters and variants. Reads status only: it starts, changes or stops no agent run. Use for \"Which models can I use for Cursor cloud agents\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_modelsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_agents":{"post":{"operationId":"list_agents","summary":"List your Cursor cloud agents, newest first, with name, lifecycle status (ACTIVE, IDLE, ARCHIVED), environment type, lin","description":"List your Cursor cloud agents, newest first, with name, lifecycle status (ACTIVE, IDLE, ARCHIVED), environment type, link and latest run id. Filter by pull request URL. Reads status only: it starts, changes or stops no agent run. Use for \"Which Cursor cloud agents are active right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items to return (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor for the next page: the nextCursor of the previous answer (absent on the last page).","title":"Cursor"},"pr_url":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"Only agents tied to this pull request URL.","title":"Pr Url"},"include_archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"False to hide archived agents (they are included by default).","title":"Include Archived"}},"title":"list_agentsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_agent":{"post":{"operationId":"get_agent","summary":"Get one cloud agent's record: name, lifecycle status, environment, repositories, whether it opens pull requests, link an","description":"Get one cloud agent's record: name, lifecycle status, environment, repositories, whether it opens pull requests, link and latest run id. Reads status only: it starts, changes or stops no agent run. Use for \"Show details of Cursor agent bc-00000000-0000-0000-0000-000000000001\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Agent id, for example 'bc-00000000-0000-0000-0000-000000000001', as returned by list_agents.","maxLength":80,"title":"Id","type":"string"}},"required":["id"],"title":"get_agentArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_agent_runs":{"post":{"operationId":"list_agent_runs","summary":"List the runs of one cloud agent, newest first, with status, timestamps and pushed branches. Reads status only: it start","description":"List the runs of one cloud agent, newest first, with status, timestamps and pushed branches. Reads status only: it starts, changes or stops no agent run. Use for \"What runs has Cursor agent bc-00000000-0000-0000-0000-000000000001 had\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Agent id, for example 'bc-00000000-0000-0000-0000-000000000001', as returned by list_agents.","maxLength":80,"title":"Id","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items to return (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor for the next page: the nextCursor of the previous answer (absent on the last page).","title":"Cursor"}},"required":["id"],"title":"list_agent_runsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_run":{"post":{"operationId":"get_run","summary":"Get one run's status and timestamps and, once it has ended, its duration, the agent's final reply text and pushed branch","description":"Get one run's status and timestamps and, once it has ended, its duration, the agent's final reply text and pushed branches or pull requests. Reads status only: it starts, changes or stops no agent run. Use for \"Did Cursor run run-00000000-0000-0000-0000-000000000001 finish\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Agent id, for example 'bc-00000000-0000-0000-0000-000000000001', as returned by list_agents.","maxLength":80,"title":"Id","type":"string"},"run_id":{"description":"Run id, for example 'run-00000000-0000-0000-0000-000000000001', as returned by list_agent_runs.","maxLength":80,"title":"Run Id","type":"string"}},"required":["id","run_id"],"title":"get_runArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_agent_usage":{"post":{"operationId":"get_agent_usage","summary":"Get token usage of one cloud agent: total and per run (input, output, cache write, cache read and total tokens). Optiona","description":"Get token usage of one cloud agent: total and per run (input, output, cache write, cache read and total tokens). Optionally for a single run. Reads status only: it starts, changes or stops no agent run. Use for \"How many tokens did Cursor agent bc-00000000-0000-0000-0000-000000000001 use\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Agent id, for example 'bc-00000000-0000-0000-0000-000000000001', as returned by list_agents.","maxLength":80,"title":"Id","type":"string"},"run_id":{"anyOf":[{"maxLength":80,"type":"string"},{"type":"null"}],"default":null,"description":"Only this run's usage.","title":"Run Id"}},"required":["id"],"title":"get_agent_usageArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_environments":{"post":{"operationId":"list_environments","summary":"List the saved cloud agent environments you can access (personal and team), most recently updated first, with name, owne","description":"List the saved cloud agent environments you can access (personal and team), most recently updated first, with name, owner type and repositories. Reads status only: it starts, changes or stops no agent run. Use for \"Which saved Cursor agent environments exist\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items to return (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor for the next page: the nextCursor of the previous answer (absent on the last page).","title":"Cursor"}},"title":"list_environmentsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}