Sample - GitHub REST API
POST/agents/repos/{owner}/{repo}/tasks

Start a task

[!NOTE] This endpoint is in public preview and is subject to change.

Starts a new Copilot cloud agent task for a repository.

This endpoint is only available to users with a Copilot Business or Copilot Enterprise subscription.

Fine-grained access tokens for "Start a task"

This endpoint works with the following fine-grained token types:

The fine-grained token must have the following permission set:

  • "Agent tasks" repository permissions (read and write)

GitHub App installation access tokens are not supported for this endpoint.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.

2 parameters · 6 body fields
ownerstringrequired
The account owner of the repository. The name is not case sensitive.
repostringrequired
The name of the repository. The name is not case sensitive.

The task creation parameters, including the user's prompt and optional agent settings.

promptstringrequired
The user's prompt for the agent
modelstringoptional
The model to use for this task. The allowed models may change over time and depend on the user's GitHub Copilot plan and organization policies. Currently supported 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`
custom_agentstringoptional
Optional identifier for a custom agent to use for this task. Use the custom agent's filename without the extension - for example, for a `.github/agents/performance-optimizer.agent.md` custom agent, use `performance-optimizer`.
create_pull_requestbooleanoptional
Whether to create a PR.
Default:false
base_refstringoptional
Base ref for new branch/PR
head_refstringoptional
Head ref for existing branch/PR. If provided with `base_ref`, the agent looks up open PR context for `head_ref` targeting `base_ref` and commits to `head_ref` instead of creating a new branch.

5 status codes
201Task created successfully
idstringrequired
Unique task identifier
urlstringoptional
API URL for this task
html_urlstringoptional
Web URL for this task
namestringoptional
Human-readable name derived from the task prompt
creatorobjectoptional
The entity who created this task
creator_typestringoptional
Type of the task creator
Allowed:userorganization
user_collaboratorsarray<object>deprecatedoptional
User objects of collaborators on this task
ownerobjectoptional
The owner of the repository
repositoryobjectoptional
The repository this task belongs to
statestringrequired
Current state of the task, derived from its most recent session
Allowed:queuedin_progresscompletedfailedidlewaiting_for_usertimed_outcancelled
session_countintegeroptional
Number of sessions in this task
artifactsarray<object>optional
Resources created by this task (PRs, branches, etc.)
archived_atstringoptional
Timestamp when the task was archived, null if not archived
updated_atstringoptional
Timestamp of the most recent update
created_atstringrequired
Timestamp when the task was created
custom_agentobjectoptional
Custom agent metadata associated with this task
400Problems parsing JSON
messagestringrequired
Summary message (e.g. "Validation Failed", "Not Found")
errorsarray<object>optional
List of validation errors (present only for 422 responses)
documentation_urlstringrequired
URL to relevant API documentation
401Authentication required
messagestringrequired
Summary message (e.g. "Validation Failed", "Not Found")
errorsarray<object>optional
List of validation errors (present only for 422 responses)
documentation_urlstringrequired
URL to relevant API documentation
403Insufficient permissions
messagestringrequired
Summary message (e.g. "Validation Failed", "Not Found")
errorsarray<object>optional
List of validation errors (present only for 422 responses)
documentation_urlstringrequired
URL to relevant API documentation
422Validation Failed
messagestringrequired
Summary message (e.g. "Validation Failed", "Not Found")
errorsarray<object>optional
List of validation errors (present only for 422 responses)
documentation_urlstringrequired
URL to relevant API documentation

Error handling

A 400 is returned: Problems parsing JSON. A 401 is returned: Authentication required. A 403 is returned: Insufficient permissions. A 422 is returned: Validation Failed.