Using Copilot cloud agent via the API

You can start and manage Copilot cloud agent tasks programmatically using the REST API.

You can use the agent tasks API to integrate cloud agent into your own tools and workflows. For example, you can start a new task, list existing tasks, or check the status of a task.

In addition, you can use the REST and GraphQL APIs for issues to assign issues to Copilot.

Using the agent tasks API

The agent tasks API is in public preview and subject to change.

Authentication

The agent tasks API only supports user-to-server tokens. You can authenticate using a personal access token, a OAuth app token or a GitHub App user-to-server token.

Server-to-server tokens, such as GitHub App installation access tokens, are not supported.

Starting a task via the API

To start a new cloud agent task, send a POST request to /agents/repos/{owner}/{repo}/tasks. The only required parameter is prompt, which is the prompt for the agent.

curl -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: " \
  -H "Authorization: Bearer YOUR-TOKEN" \
  https://api.github.com/agents/repos/OWNER/REPO/tasks \
  -d '{
    "prompt": "Fix the login button on the homepage",
    "base_ref": "main"
  }'

Replace the following placeholder values:

YOUR-TOKEN: A personal access token or GitHub App user-to-server token.
OWNER: The account owner of the repository.
REPO: The name of the repository.

You can also include the following optional parameters in the request body:

base_ref: The base branch for the new branch and pull request.
model: The AI model to use for the task. If omitted, auto model selection is used. For more information about supported models, see AUTOTITLE.
create_pull_request: A boolean that determines whether to create a pull request for the task.

Listing tasks

You can list tasks for a specific repository or across all repositories you have access to.

To list tasks for a specific repository:

curl -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: " \
  -H "Authorization: Bearer YOUR-TOKEN" \
  https://api.github.com/agents/repos/OWNER/REPO/tasks

To list your tasks across all repositories:

curl -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: " \
  -H "Authorization: Bearer YOUR-TOKEN" \
  https://api.github.com/agents/tasks

Checking the status of a task

To check the status of a specific task, send a GET request with the task ID:

curl -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: " \
  -H "Authorization: Bearer YOUR-TOKEN" \
  https://api.github.com/agents/repos/OWNER/REPO/tasks/TASK-ID

Replace TASK-ID with the ID of the task you want to check. You can get this ID from the response when you create a task or list tasks. The response includes the task's current state, which can be one of: queued, in_progress, completed, failed, idle, waiting_for_user, timed_out, or cancelled.

Using the issues API

This feature is in public preview and subject to change.

You can assign issues to Copilot using either the GraphQL API or the REST API. Both APIs support an optional Agent Assignment input to customize the task:

GraphQL parameter	REST parameter	Description
`targetRepositoryId`	`target_repo`	The repository where Copilot will work
`baseRef`	`base_branch`	The branch that Copilot will branch from
`customInstructions`	`custom_instructions`	Additional instructions for Copilot
`customAgent`	`custom_agent`	A custom agent to use for the task
`model`	`model`	The model for Copilot to use

Using the GraphQL API

You must include the GraphQL-Features header with the values issues_copilot_assignment_api_support and coding_agent_model_selection.

You can use the following GraphQL mutations to assign issues to Copilot:

Creating and assigning a new issue

Make sure you're authenticating with the API using a user token, for example a personal access token or a GitHub App user-to-server token.

If using a fine-grained personal access token, it needs the following permissions to assign Copilot to an issue:

Read access to metadata
Read and write access to actions, contents, issues and pull requests

If using a personal access token (classic), it needs the repo scope to assign Copilot to an issue.

Verify that Copilot cloud agent is enabled in the repository by checking if the repository's suggestedActors in the GraphQL API includes Copilot. Replace octo-org with the repository owner, and octo-repo with the repository name.

query {
  repository(owner: "octo-org", name: "octo-repo") {
    suggestedActors(capabilities: [CAN_BE_ASSIGNED], first: 100) {
      nodes {
        login
        __typename

        ... on Bot {
          id
        }

        ... on User {
          id
        }
      }
    }
  }
}

If Copilot cloud agent is enabled for the user and in the repository, the first node returned from the query will have the login value copilot-swe-agent.

Make a note of the id value of this login.
Fetch the GraphQL global ID of the repository you want to create the issue in, replacing octo-org with the repository owner, and octo-repo with the repository name.
```
query {
  repository(owner: "octo-org", name: "octo-repo") {
    id
  }
}
```

Create the issue with the createIssue mutation. Replace REPOSITORY_ID with the ID returned from the previous step, and BOT_ID with the ID returned from the step before that. You can optionally include the agentAssignment input to customize the task.

gh api graphql -f query='mutation {
  createIssue(input: {
    repositoryId: "REPOSITORY_ID",
    title: "Implement comprehensive unit tests",
    body: "DETAILS",
    assigneeIds: ["BOT_ID"],
    agentAssignment: {
      targetRepositoryId: "REPOSITORY_ID",
      baseRef: "main",
      customInstructions: "Add comprehensive test coverage",
      customAgent: "",
      model: ""
    }
  }) {
    issue {
      id
      title
      assignees(first: 10) {
        nodes {
          login
        }
      }
    }
  }
}' -H 'GraphQL-Features: issues_copilot_assignment_api_support,coding_agent_model_selection'

Assigning an existing issue

Make sure you're authenticating with the API using a user token, for example a personal access token or a GitHub App user-to-server token.

query {
  repository(owner: "monalisa", name: "octocat") {
    suggestedActors(capabilities: [CAN_BE_ASSIGNED], first: 100) {
      nodes {
        login
        __typename

        ... on Bot {
          id
        }

        ... on User {
          id
        }
      }
    }
  }
}

If Copilot cloud agent is enabled for the user and in the repository, the first node returned from the query will have the login value copilot-swe-agent.

Fetch the GraphQL global ID of the issue you want to assign to Copilot, replacing monalisa with the repository owner, octocat with the name and 9000 with the issue number.
```
query {
  repository(owner: "monalisa", name: "octocat") {
    issue(number: 9000) {
      id
      title
    }
  }
}
```

Assign the existing issue to Copilot using the replaceActorsForAssignable mutation. Replace ISSUE_ID with the ID returned from the previous step, BOT_ID with the ID returned from the step before that, and REPOSITORY_ID with the repository ID. You can optionally include the agentAssignment input to customize the task.

gh api graphql -f query='mutation {
  replaceActorsForAssignable(input: {
    assignableId: "ISSUE_ID",
    actorIds: ["BOT_ID"],
    agentAssignment: {
      targetRepositoryId: "REPOSITORY_ID",
      baseRef: "main",
      customInstructions: "Fix the reported bug",
      customAgent: "",
      model: ""
    }
  }) {
    assignable {
      ... on Issue {
        id
        title
        assignees(first: 10) {
          nodes {
            login
          }
        }
      }
    }
  }
}' -H 'GraphQL-Features: issues_copilot_assignment_api_support,coding_agent_model_selection'

Alternatively, you can use the updateIssue mutation to update an existing issue and assign it to Copilot. Replace ISSUE_ID with the issue ID and BOT_ID with the bot ID.

gh api graphql -f query='mutation {
  updateIssue(input: {
    id: "ISSUE_ID",
    assigneeIds: ["BOT_ID"],
    agentAssignment: {
      targetRepositoryId: "REPOSITORY_ID",
      baseRef: "main",
      customInstructions: "Update feature implementation",
      customAgent: "",
      model: ""
    }
  }) {
    issue {
      id
      title
      assignees(first: 10) {
        nodes {
          login
        }
      }
    }
  }
}' -H 'GraphQL-Features: issues_copilot_assignment_api_support,coding_agent_model_selection'

You can also use the addAssigneesToAssignable mutation to add Copilot to an existing issue while keeping other assignees. Replace ISSUE_ID with the issue ID and BOT_ID with the bot ID.

gh api graphql -f query='mutation {
  addAssigneesToAssignable(input: {
    assignableId: "ISSUE_ID",
    assigneeIds: ["BOT_ID"],
    agentAssignment: {
      targetRepositoryId: "REPOSITORY_ID",
      baseRef: "main",
      customInstructions: "Collaborate on this task",
      customAgent: "",
      model: ""
    }
  }) {
    assignable {
      ... on Issue {
        id
        title
        assignees(first: 10) {
          nodes {
            login
          }
        }
      }
    }
  }
}' -H 'GraphQL-Features: issues_copilot_assignment_api_support,coding_agent_model_selection'

Using the REST API

You can use the following REST API endpoints to assign issues to Copilot:

Adding assignees to an existing issue

gh api \
  --method POST \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  /repos/OWNER/REPO/issues/ISSUE_NUMBER/assignees \
  --input - <<< '{
  "assignees": ["copilot-swe-agent[bot]"],
  "agent_assignment": {
    "target_repo": "OWNER/REPO",
    "base_branch": "main",
    "custom_instructions": "",
    "custom_agent": "",
    "model": ""
  }
}'

Creating a new issue

gh api \
  --method POST \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  /repos/OWNER/REPO/issues \
  --input - <<< '{
  "title": "Issue title",
  "body": "Issue description.",
  "assignees": ["copilot-swe-agent[bot]"],
  "agent_assignment": {
    "target_repo": "OWNER/REPO",
    "base_branch": "main",
    "custom_instructions": "",
    "custom_agent": "",
    "model": ""
  }
}'

Updating an existing issue

gh api \
  --method PATCH \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  /repos/OWNER/REPO/issues/ISSUE_NUMBER \
  --input - <<< '{
  "assignees": ["copilot-swe-agent[bot]"],
  "agent_assignment": {
    "target_repo": "OWNER/REPO",
    "base_branch": "main",
    "custom_instructions": "",
    "custom_agent": "",
    "model": ""
  }
}'

Using Copilot cloud agent via the API

Using the agent tasks API

Authentication

Starting a task via the API

Listing tasks

Checking the status of a task

Using the issues API

Using the GraphQL API

Creating and assigning a new issue

Assigning an existing issue

Using the REST API

Adding assignees to an existing issue

Creating a new issue

Updating an existing issue

Further reading