{"meta":{"title":"Using Copilot cloud agent via the API","intro":"You can start and manage Copilot cloud agent tasks programmatically using the REST API.","product":"GitHub Copilot","breadcrumbs":[{"href":"/en/copilot","title":"GitHub Copilot"},{"href":"/en/copilot/how-tos","title":"How-tos"},{"href":"/en/copilot/how-tos/use-copilot-agents","title":"Use Copilot agents"},{"href":"/en/copilot/how-tos/use-copilot-agents/cloud-agent","title":"Cloud agent"},{"href":"/en/copilot/how-tos/use-copilot-agents/cloud-agent/use-cloud-agent-via-the-api","title":"Use cloud agent via the API"}],"documentType":"article"},"body":"# Using Copilot cloud agent via the API\n\nYou can start and manage Copilot cloud agent tasks programmatically using the REST API.\n\nYou 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.\n\nIn addition, you can use the REST and GraphQL APIs for issues to assign issues to Copilot.\n\n## Using the agent tasks API\n\n> \\[!NOTE]\n> The agent tasks API is in public preview and subject to change.\n\n### Authentication\n\nThe 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.\n\nServer-to-server tokens, such as GitHub App installation access tokens, are not supported.\n\n### Starting a task via the API\n\nTo 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.\n\n```shell copy\ncurl -X POST \\\n  -H \"Accept: application/vnd.github+json\" \\\n  -H \"X-GitHub-Api-Version: 2022-11-28\" \\\n  -H \"Authorization: Bearer YOUR-TOKEN\" \\\n  https://api.github.com/agents/repos/OWNER/REPO/tasks \\\n  -d '{\n    \"prompt\": \"Fix the login button on the homepage\",\n    \"base_ref\": \"main\"\n  }'\n```\n\nReplace the following placeholder values:\n\n* `YOUR-TOKEN`: A personal access token or GitHub App user-to-server token.\n* `OWNER`: The account owner of the repository.\n* `REPO`: The name of the repository.\n\nYou can also include the following optional parameters in the request body:\n\n* `base_ref`: The base branch for the new branch and pull request.\n* `model`: The AI model to use for the task. If omitted, auto model selection is used. For more information about supported models, see [REST API endpoints for agent tasks](/en/rest/agent-tasks/agent-tasks).\n* `create_pull_request`: A boolean that determines whether to create a pull request for the task.\n\n### Listing tasks\n\nYou can list tasks for a specific repository or across all repositories you have access to.\n\nTo list tasks for a specific repository:\n\n```shell copy\ncurl -H \"Accept: application/vnd.github+json\" \\\n  -H \"X-GitHub-Api-Version: 2022-11-28\" \\\n  -H \"Authorization: Bearer YOUR-TOKEN\" \\\n  https://api.github.com/agents/repos/OWNER/REPO/tasks\n```\n\nTo list your tasks across all repositories:\n\n```shell copy\ncurl -H \"Accept: application/vnd.github+json\" \\\n  -H \"X-GitHub-Api-Version: 2022-11-28\" \\\n  -H \"Authorization: Bearer YOUR-TOKEN\" \\\n  https://api.github.com/agents/tasks\n```\n\n### Checking the status of a task\n\nTo check the status of a specific task, send a `GET` request with the task ID:\n\n```shell copy\ncurl -H \"Accept: application/vnd.github+json\" \\\n  -H \"X-GitHub-Api-Version: 2022-11-28\" \\\n  -H \"Authorization: Bearer YOUR-TOKEN\" \\\n  https://api.github.com/agents/repos/OWNER/REPO/tasks/TASK-ID\n```\n\nReplace `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`.\n\n## Using the issues API\n\n> \\[!NOTE]\n> This feature is in public preview and subject to change.\n\nYou 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:\n\n| GraphQL parameter    | REST parameter        | Description                              |\n| -------------------- | --------------------- | ---------------------------------------- |\n| `targetRepositoryId` | `target_repo`         | The repository where Copilot will work   |\n| `baseRef`            | `base_branch`         | The branch that Copilot will branch from |\n| `customInstructions` | `custom_instructions` | Additional instructions for Copilot      |\n| `customAgent`        | `custom_agent`        | A custom agent to use for the task       |\n| `model`              | `model`               | The model for Copilot to use             |\n\n### Using the GraphQL API\n\n> \\[!NOTE]\n> You must include the `GraphQL-Features` header with the values `issues_copilot_assignment_api_support` and `coding_agent_model_selection`.\n\nYou can use the following GraphQL mutations to assign issues to Copilot:\n\n* [`updateIssue`](/en/graphql/reference/issues#mutation-updateissue)\n* [`createIssue`](/en/graphql/reference/issues#mutation-createissue)\n* [`addAssigneesToAssignable`](/en/graphql/reference/issues#mutation-addassigneestoassignable)\n* [`replaceActorsForAssignable`](/en/graphql/reference/issues#mutation-replaceactorsforassignable)\n\n#### Creating and assigning a new issue\n\n1. 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.\n\n   > \\[!NOTE]\n   > If using a fine-grained personal access token, it needs the following permissions to assign Copilot to an issue:\n   >\n   > * Read access to metadata\n   > * Read and write access to actions, contents, issues and pull requests\n   >\n   > If using a personal access token (classic), it needs the `repo` scope to assign Copilot to an issue.\n\n2. 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.\n\n   ```graphql copy\n   query {\n     repository(owner: \"octo-org\", name: \"octo-repo\") {\n       suggestedActors(capabilities: [CAN_BE_ASSIGNED], first: 100) {\n         nodes {\n           login\n           __typename\n\n           ... on Bot {\n             id\n           }\n\n           ... on User {\n             id\n           }\n         }\n       }\n     }\n   }\n   ```\n\n   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`.\n\n3. Make a note of the `id` value of this login.\n\n4. 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.\n\n   ```graphql copy\n   query {\n     repository(owner: \"octo-org\", name: \"octo-repo\") {\n       id\n     }\n   }\n   ```\n\n5. 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.\n\n   ```shell copy\n   gh api graphql -f query='mutation {\n     createIssue(input: {\n       repositoryId: \"REPOSITORY_ID\",\n       title: \"Implement comprehensive unit tests\",\n       body: \"DETAILS\",\n       assigneeIds: [\"BOT_ID\"],\n       agentAssignment: {\n         targetRepositoryId: \"REPOSITORY_ID\",\n         baseRef: \"main\",\n         customInstructions: \"Add comprehensive test coverage\",\n         customAgent: \"\",\n         model: \"\"\n       }\n     }) {\n       issue {\n         id\n         title\n         assignees(first: 10) {\n           nodes {\n             login\n           }\n         }\n       }\n     }\n   }' -H 'GraphQL-Features: issues_copilot_assignment_api_support,coding_agent_model_selection'\n   ```\n\n#### Assigning an existing issue\n\n1. 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.\n\n2. 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.\n\n   ```graphql copy\n   query {\n     repository(owner: \"monalisa\", name: \"octocat\") {\n       suggestedActors(capabilities: [CAN_BE_ASSIGNED], first: 100) {\n         nodes {\n           login\n           __typename\n\n           ... on Bot {\n             id\n           }\n\n           ... on User {\n             id\n           }\n         }\n       }\n     }\n   }\n   ```\n\n   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`.\n\n3. 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.\n\n   ```graphql copy\n   query {\n     repository(owner: \"monalisa\", name: \"octocat\") {\n       issue(number: 9000) {\n         id\n         title\n       }\n     }\n   }\n   ```\n\n4. 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.\n\n   ```shell copy\n   gh api graphql -f query='mutation {\n     replaceActorsForAssignable(input: {\n       assignableId: \"ISSUE_ID\",\n       actorIds: [\"BOT_ID\"],\n       agentAssignment: {\n         targetRepositoryId: \"REPOSITORY_ID\",\n         baseRef: \"main\",\n         customInstructions: \"Fix the reported bug\",\n         customAgent: \"\",\n         model: \"\"\n       }\n     }) {\n       assignable {\n         ... on Issue {\n           id\n           title\n           assignees(first: 10) {\n             nodes {\n               login\n             }\n           }\n         }\n       }\n     }\n   }' -H 'GraphQL-Features: issues_copilot_assignment_api_support,coding_agent_model_selection'\n   ```\n\n5. 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.\n\n   ```shell copy\n   gh api graphql -f query='mutation {\n     updateIssue(input: {\n       id: \"ISSUE_ID\",\n       assigneeIds: [\"BOT_ID\"],\n       agentAssignment: {\n         targetRepositoryId: \"REPOSITORY_ID\",\n         baseRef: \"main\",\n         customInstructions: \"Update feature implementation\",\n         customAgent: \"\",\n         model: \"\"\n       }\n     }) {\n       issue {\n         id\n         title\n         assignees(first: 10) {\n           nodes {\n             login\n           }\n         }\n       }\n     }\n   }' -H 'GraphQL-Features: issues_copilot_assignment_api_support,coding_agent_model_selection'\n   ```\n\n6. 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.\n\n   ```shell copy\n   gh api graphql -f query='mutation {\n     addAssigneesToAssignable(input: {\n       assignableId: \"ISSUE_ID\",\n       assigneeIds: [\"BOT_ID\"],\n       agentAssignment: {\n         targetRepositoryId: \"REPOSITORY_ID\",\n         baseRef: \"main\",\n         customInstructions: \"Collaborate on this task\",\n         customAgent: \"\",\n         model: \"\"\n       }\n     }) {\n       assignable {\n         ... on Issue {\n           id\n           title\n           assignees(first: 10) {\n             nodes {\n               login\n             }\n           }\n         }\n       }\n     }\n   }' -H 'GraphQL-Features: issues_copilot_assignment_api_support,coding_agent_model_selection'\n   ```\n\n### Using the REST API\n\nYou can use the following REST API endpoints to assign issues to Copilot:\n\n* [Add assignees to an issue](/en/rest/issues/assignees#add-assignees-to-an-issue)\n* [Create an issue](/en/rest/issues/issues#create-an-issue)\n* [Update an issue](/en/rest/issues/issues#update-an-issue)\n\n#### Adding assignees to an existing issue\n\n```shell copy\ngh api \\\n  --method POST \\\n  -H \"Accept: application/vnd.github+json\" \\\n  -H \"X-GitHub-Api-Version: 2022-11-28\" \\\n  /repos/OWNER/REPO/issues/ISSUE_NUMBER/assignees \\\n  --input - <<< '{\n  \"assignees\": [\"copilot-swe-agent[bot]\"],\n  \"agent_assignment\": {\n    \"target_repo\": \"OWNER/REPO\",\n    \"base_branch\": \"main\",\n    \"custom_instructions\": \"\",\n    \"custom_agent\": \"\",\n    \"model\": \"\"\n  }\n}'\n```\n\n#### Creating a new issue\n\n```shell copy\ngh api \\\n  --method POST \\\n  -H \"Accept: application/vnd.github+json\" \\\n  -H \"X-GitHub-Api-Version: 2022-11-28\" \\\n  /repos/OWNER/REPO/issues \\\n  --input - <<< '{\n  \"title\": \"Issue title\",\n  \"body\": \"Issue description.\",\n  \"assignees\": [\"copilot-swe-agent[bot]\"],\n  \"agent_assignment\": {\n    \"target_repo\": \"OWNER/REPO\",\n    \"base_branch\": \"main\",\n    \"custom_instructions\": \"\",\n    \"custom_agent\": \"\",\n    \"model\": \"\"\n  }\n}'\n```\n\n#### Updating an existing issue\n\n```shell copy\ngh api \\\n  --method PATCH \\\n  -H \"Accept: application/vnd.github+json\" \\\n  -H \"X-GitHub-Api-Version: 2022-11-28\" \\\n  /repos/OWNER/REPO/issues/ISSUE_NUMBER \\\n  --input - <<< '{\n  \"assignees\": [\"copilot-swe-agent[bot]\"],\n  \"agent_assignment\": {\n    \"target_repo\": \"OWNER/REPO\",\n    \"base_branch\": \"main\",\n    \"custom_instructions\": \"\",\n    \"custom_agent\": \"\",\n    \"model\": \"\"\n  }\n}'\n```\n\n## Further reading\n\n* [REST API endpoints for agent tasks](/en/rest/agent-tasks/agent-tasks)\n* [About GitHub Copilot cloud agent](/en/copilot/concepts/agents/cloud-agent/about-cloud-agent)\n* [Starting GitHub Copilot sessions](/en/copilot/how-tos/use-copilot-agents/cloud-agent/start-copilot-sessions)"}