Start a task

POST

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

[!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:

• GitHub App user access tokens
• Fine-grained personal access tokens

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.

API method documentation

Parameters

Path Parameters

owner

required

string

The account owner of the repository. The name is not case sensitive.

repo

required

string

The name of the repository. The name is not case sensitive.

Request Body ^required

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

Media type application/json

object

prompt

required

The user’s prompt for the agent

string

model

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

string

custom_agent

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.

string

create_pull_request

Whether to create a PR.

boolean

base_ref

Base ref for new branch/PR

string

head_ref

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.

string

Examples

{
  "prompt": "Fix the login button on the homepage",
  "base_ref": "main"
}

Task with a custom agent

{
  "prompt": "Fix the login button on the homepage",
  "base_ref": "main",
  "custom_agent": "my-custom-agent"
}

Responses

201

Task created successfully

Media type application/json

object

id

required

Unique task identifier

string

url

API URL for this task

string

html_url

Web URL for this task

string

name

Human-readable name derived from the task prompt

string

creator

One of:

object

A GitHub user

object

id

The unique identifier of the user

integer format: int64

creator_type

Type of the task creator

string

Allowed values: user organization

user_collaborators

User objects of collaborators on this task

Array<object>

A GitHub user

object

id

The unique identifier of the user

integer format: int64

owner

The owner of the repository

object

id

The unique identifier of the user

integer format: int64

repository

The repository this task belongs to

object

id

The unique identifier of the repository

integer format: int64

state

required

Current state of the task, derived from its most recent session

string

Allowed values: queued in_progress completed failed idle waiting_for_user timed_out cancelled

session_count

Number of sessions in this task

integer format: int32

artifacts

Resources created by this task (PRs, branches, etc.)

Array<object>

A resource generated by the task

object

provider

required

Provider namespace

string

Allowed values: github

type

required

Type of artifact. Available Values: pull, branch.

string

Allowed values: pull branch

data

required

One of:

object

A GitHub resource (pull request, issue, etc.)

object

id

required

GitHub resource ID

integer format: int64

global_id

GraphQL global ID

string

object

A Git branch reference

object

head_ref

required

Head branch name

string

base_ref

required

Base branch name

string

archived_at

Timestamp when the task was archived, null if not archived

string format: date-time

nullable

updated_at

Timestamp of the most recent update

string format: date-time

created_at

required

Timestamp when the task was created

string format: date-time

custom_agent

Custom agent metadata associated with this task

object

id

The custom agent’s filename without the extension - for example, performance-optimizer for a .github/agents/performance-optimizer.agent.md custom agent.

string

Examples

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Fix the login button on the homepage",
  "creator": {
    "id": 1
  },
  "creator_type": "user",
  "owner": {
    "id": 1
  },
  "repository": {
    "id": 1296269
  },
  "state": "queued",
  "session_count": 1,
  "artifacts": [],
  "archived_at": null,
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-01T00:00:00Z"
}

Task created with a custom agent

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "url": "https://api.github.com/agents/repos/octocat/hello-world/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "html_url": "https://github.com/octocat/hello-world/copilot/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Fix the login button on the homepage",
  "creator": {
    "id": 1
  },
  "creator_type": "user",
  "owner": {
    "id": 1
  },
  "repository": {
    "id": 1296269
  },
  "state": "queued",
  "session_count": 1,
  "custom_agent": {
    "id": "my-custom-agent"
  },
  "artifacts": [],
  "archived_at": null,
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-01T00:00:00Z"
}

400

Problems parsing JSON

Media type application/json

Structured error response following GitHub REST API conventions. For 422 Unprocessable Entity the errors array contains validation details; for other error status codes only message and documentation_url are returned.

object

message

required

Summary message (e.g. “Validation Failed”, “Not Found”)

string

errors

List of validation errors (present only for 422 responses)

Array<object>

A single validation error

object

code

required

Machine-readable error code

string

Allowed values: missing missing_field invalid already_exists unprocessable custom

message

Human-readable message (populated when code is “custom”)

string

documentation_url

required

URL to relevant API documentation

string

Example

{
  "errors": [
    {
      "code": "missing"
    }
  ]
}

401

Authentication required

Media type application/json

Structured error response following GitHub REST API conventions. For 422 Unprocessable Entity the errors array contains validation details; for other error status codes only message and documentation_url are returned.

object

message

required

Summary message (e.g. “Validation Failed”, “Not Found”)

string

errors

List of validation errors (present only for 422 responses)

Array<object>

A single validation error

object

code

required

Machine-readable error code

string

Allowed values: missing missing_field invalid already_exists unprocessable custom

message

Human-readable message (populated when code is “custom”)

string

documentation_url

required

URL to relevant API documentation

string

Example

{
  "errors": [
    {
      "code": "missing"
    }
  ]
}

403

Insufficient permissions

Media type application/json

Structured error response following GitHub REST API conventions. For 422 Unprocessable Entity the errors array contains validation details; for other error status codes only message and documentation_url are returned.

object

message

required

Summary message (e.g. “Validation Failed”, “Not Found”)

string

errors

List of validation errors (present only for 422 responses)

Array<object>

A single validation error

object

code

required

Machine-readable error code

string

Allowed values: missing missing_field invalid already_exists unprocessable custom

message

Human-readable message (populated when code is “custom”)

string

documentation_url

required

URL to relevant API documentation

string

Example

{
  "errors": [
    {
      "code": "missing"
    }
  ]
}

422

Validation Failed

Media type application/json

Structured error response following GitHub REST API conventions. For 422 Unprocessable Entity the errors array contains validation details; for other error status codes only message and documentation_url are returned.

object

message

required

Summary message (e.g. “Validation Failed”, “Not Found”)

string

errors

List of validation errors (present only for 422 responses)

Array<object>

A single validation error

object

code

required

Machine-readable error code

string

Allowed values: missing missing_field invalid already_exists unprocessable custom

message

Human-readable message (populated when code is “custom”)

string

documentation_url

required

URL to relevant API documentation

string

Example

{
  "errors": [
    {
      "code": "missing"
    }
  ]
}