Start a new Copilot cloud-agent task on a repository.

POST /agents/repos/{owner}/{repo}/tasks

Args: owner: Repo owner (user or org login). repo: Repo name. prompt: Natural-language instruction for the agent. base_ref: Branch the agent should base work on (defaults to repo default). head_ref: Branch the agent should push work to (optional). model: Optional model override. Known values: claude-sonnet-4.6, claude-opus-4.6, gpt-5.2-codex, gpt-5.3-codex, gpt-5.4, claude-sonnet-4.5, claude-opus-4.5. Omit for auto-selection. create_pull_request: If true, the agent opens a PR when done.

Returns: Task object including id, state, html_url, artifacts.

List Copilot cloud-agent tasks.

If both owner and repo are provided, scopes to that repo: GET /agents/repos/{owner}/{repo}/tasks Otherwise lists tasks visible to the caller across all repos: GET /agents/tasks

Args: owner: Optional repo owner. repo: Optional repo name. state: Filter by states (any of queued, in_progress, completed, failed, idle, waiting_for_user, timed_out, cancelled). is_archived: Include archived tasks. since: ISO 8601 timestamp; only tasks updated after this. sort: updated_at or created_at. direction: asc or desc. per_page: 1–100, default 30. page: page number, default 1. creator_id: Repo-scoped only — filter by creator user IDs.

Get a single task (with its sessions) by ID.

Prefers the repo-scoped endpoint when owner+repo are provided: GET /agents/repos/{owner}/{repo}/tasks/{task_id} Otherwise: GET /agents/tasks/{task_id}

The response includes a sessions array — each session has its own state, model, prompt, head_ref/base_ref, and any error.message.

Poll a task until it reaches a terminal state, or timeout.

Terminal states: completed, failed, timed_out, cancelled. Non-terminal (will keep polling): queued, in_progress, idle, waiting_for_user.

Args: task_id: Task ID returned by create_task. owner: Optional repo owner (preferred — faster path). repo: Optional repo name. timeout_seconds: Hard ceiling on total wait. Default 30 min. poll_interval_seconds: Sleep between polls. Default 15s.

Returns: Final task object plus _meta.elapsed_seconds and _meta.polls.

Get an org's Copilot coding-agent repo-access setting.

GET /orgs/{org}/copilot/coding-agent/permissions Returns: {enabled_repositories: all|selected|none, selected_repositories_url} Requires admin:org scope.

Set whether all, selected, or no repos in an org can use the cloud agent.

PUT /orgs/{org}/copilot/coding-agent/permissions Requires admin:org scope.

List repos in an org that have cloud-agent access enabled.

GET /orgs/{org}/copilot/coding-agent/permissions/repositories Requires admin:org scope.

Replace the org's selected-repos list for cloud-agent access.

PUT /orgs/{org}/copilot/coding-agent/permissions/repositories Only meaningful when enabled_repositories=selected. Requires admin:org scope.

Add one repo to the org's selected cloud-agent list.

PUT /orgs/{org}/copilot/coding-agent/permissions/repositories/{repository_id} Requires admin:org scope.

Remove one repo from the org's selected cloud-agent list.

DELETE /orgs/{org}/copilot/coding-agent/permissions/repositories/{repository_id} Requires admin:org scope.

Return the model strings accepted by create_task as of API v2026-03-10.

Omit model from create_task to let GitHub pick the default.