diff --git a/descriptions-next/api.github.com/api.github.com.2022-11-28.json b/descriptions-next/api.github.com/api.github.com.2022-11-28.json index b0692b120..f5cf01ea5 100644 --- a/descriptions-next/api.github.com/api.github.com.2022-11-28.json +++ b/descriptions-next/api.github.com/api.github.com.2022-11-28.json @@ -530,6 +530,3174 @@ } } }, + "/agents/repos/{owner}/{repo}/tasks": { + "get": { + "summary": "List tasks for repository", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for a specific repository\n\n**Fine-grained access tokens for \"List tasks for repository\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks-for-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks-for-repository" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "Comma-separated list of task states to filter by. Can be any combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, `waiting_for_user`, `timed_out`, `cancelled`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + }, + { + "name": "creator_id", + "in": "query", + "schema": { + "type": "integer" + }, + "description": "Filter tasks by creator user ID" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"prev\" (when current page > 1),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "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": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + }, + "post": { + "summary": "Start a task", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nStarts a new Copilot cloud agent task for a repository.\n\nThis endpoint is only available to users with a Copilot Business or Copilot Enterprise subscription.\n\n**Fine-grained access tokens for \"Start a task\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read and write)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/create-task-in-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#start-a-task" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + } + ], + "requestBody": { + "required": true, + "description": "The task creation parameters, including the user's prompt and optional agent settings.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "prompt" + ], + "properties": { + "prompt": { + "type": "string", + "description": "The user's prompt for the agent" + }, + "model": { + "type": "string", + "description": "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`" + }, + "create_pull_request": { + "type": "boolean", + "description": "Whether to create a PR.", + "default": false + }, + "base_ref": { + "type": "string", + "description": "Base ref for new branch/PR" + } + } + }, + "examples": { + "default": { + "value": { + "prompt": "Fix the login button on the homepage", + "base_ref": "main" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Task created successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "examples": { + "default": { + "value": { + "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" + } + } + } + } + } + }, + "400": { + "description": "Problems parsing JSON", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/repos/{owner}/{repo}/tasks/{task_id}": { + "get": { + "summary": "Get a task by repo", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID scoped to an owner/repo path\n\n**Fine-grained access tokens for \"Get a task by repo\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-repo-and-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-repo" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "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": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks": { + "get": { + "summary": "List tasks", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for the authenticated user\n\n**Fine-grained access tokens for \"List tasks\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "Comma-separated list of task states to filter by. Can be any combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, `waiting_for_user`, `timed_out`, `cancelled`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "id": "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": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks/{task_id}": { + "get": { + "summary": "Get a task by ID", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID with its associated sessions\n\n**Fine-grained access tokens for \"Get a task by ID\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-id" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "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": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Problems parsing request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, "/app": { "get": { "summary": "Get the authenticated app", @@ -35242,6 +38410,139 @@ } } }, + "/repos/{owner}/{repo}/actions/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a repository", + "description": "Lists the active concurrency groups for a repository.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository" + }, + "parameters": [ + { + "$ref": "#/components/parameters/owner" + }, + { + "$ref": "#/components/parameters/repo" + }, + { + "$ref": "#/components/parameters/per-page" + }, + { + "$ref": "#/components/parameters/pagination-after" + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/concurrency-group-list" + }, + "examples": { + "default": { + "$ref": "#/components/examples/concurrency-group-list" + } + } + } + }, + "headers": { + "Link": { + "$ref": "#/components/headers/link" + } + } + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": { + "get": { + "summary": "Get a concurrency group for a repository", + "description": "Gets a specific concurrency group for a repository, including all instances in the group's queue.\nReturns 404 if the group is inactive or does not exist.\n\nOptionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items\nahead of the specified workflow run or job in the queue, plus the specified item itself\n(returned as the last element). This is useful for determining what is blocking a particular\nrun or job. Returns 422 if the specified run or job is not in this concurrency group.\n\nWhen using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow\nleases held on behalf of that run. Job-level leases within the run are not considered to\nblock the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow\nleases on the job's ancestor paths.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/get-concurrency-group-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository" + }, + "parameters": [ + { + "$ref": "#/components/parameters/owner" + }, + { + "$ref": "#/components/parameters/repo" + }, + { + "$ref": "#/components/parameters/concurrency-group-name" + }, + { + "name": "ahead_of_run", + "description": "Filter to items ahead of this workflow run ID in the queue, plus the run itself.\nMatches workflow-level concurrency and reusable-workflow leases held on behalf of\nthe run. Mutually exclusive with `ahead_of_job`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + }, + { + "name": "ahead_of_job", + "description": "Filter to items ahead of this job ID in the queue, plus the job itself.\nMatches job-level concurrency and reusable-workflow leases on the job's\nancestor paths. Mutually exclusive with `ahead_of_run`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/concurrency-group" + }, + "examples": { + "default": { + "$ref": "#/components/examples/concurrency-group" + } + } + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/jobs/{job_id}": { "get": { "summary": "Get a job for a workflow run", @@ -37655,6 +40956,74 @@ } } }, + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a workflow run", + "description": "Lists all concurrency groups associated with a workflow run or its jobs.\n\nThe set of groups is derived from the run's configuration, so a group is\nincluded even when the run no longer has any items currently holding or\nwaiting in it. In that case the `group_members` array will be empty.\n`total_count` reflects the number of groups the run participates in by\nconfiguration, not the number with active items.\n\nThis differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`,\nwhich returns 404 when a group has no active items. That endpoint reports\nthe live state of a group repo-wide, while this endpoint reports the\ngroups associated with a specific run by configuration.\n\nResults are sorted by group name and support cursor-based pagination via\n`before` and `after`. The `after` cursor paginates forward only and does\nnot emit a `rel=\"prev\"` Link; use `before` to page backward from a\nforward page's `next` cursor.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-workflow-run", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run" + }, + "parameters": [ + { + "$ref": "#/components/parameters/owner" + }, + { + "$ref": "#/components/parameters/repo" + }, + { + "$ref": "#/components/parameters/run-id" + }, + { + "$ref": "#/components/parameters/per-page" + }, + { + "$ref": "#/components/parameters/pagination-before" + }, + { + "$ref": "#/components/parameters/pagination-after" + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/concurrency-group-run-list" + }, + "examples": { + "default": { + "$ref": "#/components/examples/concurrency-group-run-list" + } + } + } + }, + "headers": { + "Link": { + "$ref": "#/components/headers/link" + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": { "post": { "summary": "Review custom deployment protection rules for a workflow run", @@ -130867,6 +134236,144 @@ "actions_caches" ] }, + "concurrency-group-list": { + "title": "Concurrency Group List", + "description": "A list of active concurrency groups for a repository.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer" + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "last_acquired_at" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "last_acquired_at": { + "type": [ + "string", + "null" + ], + "format": "date-time" + } + } + } + } + } + }, + "concurrency-group": { + "title": "Concurrency Group", + "description": "A concurrency group with the workflow runs and jobs that are either currently holding\nor waiting for the concurrency group lease.", + "type": "object", + "required": [ + "group_name", + "group_url", + "total_count", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "total_count": { + "type": "integer" + }, + "group_members": { + "type": "array", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "API URL for the workflow run." + }, + "run_html_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "Web URL for the workflow run." + }, + "job_id": { + "type": "integer", + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_name": { + "type": "string", + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "API URL for the job." + }, + "job_html_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "Web URL for the job." + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + }, "job": { "title": "Job", "description": "Information of a job execution in a workflow run", @@ -131798,6 +135305,131 @@ "comment" ] }, + "concurrency-group-run-list": { + "title": "Concurrency Group Run List", + "description": "A list of concurrency groups associated with a workflow run.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer", + "description": "The total number of concurrency groups this workflow run participates in,\nderived from the run's configuration. This count is not filtered by\nwhether the run currently holds or is waiting in each group, so it can\ninclude groups whose `group_members` array is empty (for example, when\nthe run has already released its lease in that group)." + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group. May return 404 if the group\nhas no active items at the time it is requested, since the\nget-by-name endpoint reports the live repo-wide state of a group\nwhile this endpoint lists groups associated with a run by\nconfiguration." + }, + "group_members": { + "type": "array", + "description": "Items belonging to this workflow run that are either currently holding or\nwaiting for the concurrency group lease. May be empty if the run no\nlonger has any active or queued items in this group.", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status", + "position", + "position_url" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "API URL for the workflow run." + }, + "run_html_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "Web URL for the workflow run." + }, + "position": { + "type": "integer", + "description": "Queue position. 0 means the item holds the concurrency lease (in_progress), 1 or higher means queued (pending)." + }, + "position_url": { + "type": "string", + "format": "uri", + "description": "API URL to get items ahead of this item in the concurrency group." + }, + "job_id": { + "type": [ + "integer", + "null" + ], + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_name": { + "type": [ + "string", + "null" + ], + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "API URL for the job." + }, + "job_html_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "Web URL for the job." + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + } + } + } + }, "review-custom-gates-comment-required": { "type": "object", "properties": { @@ -312472,6 +316104,57 @@ ] } }, + "concurrency-group-list": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "last_acquired_at": "2026-01-15T16:14:23Z" + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "last_acquired_at": "2026-01-15T16:13:55Z" + } + ] + } + }, + "concurrency-group": { + "value": { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "total_count": 3, + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress" + }, + { + "run_id": 30433643, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433643", + "status": "pending" + }, + { + "run_id": 30433644, + "run_name": "Deploy hotfix", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644", + "job_id": 798245260, + "job_name": "deploy", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260", + "status": "pending" + } + ] + } + }, "job": { "value": { "id": 399444496, @@ -313260,6 +316943,47 @@ ] } }, + "concurrency-group-run-list": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress", + "position": 0, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642" + } + ] + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "pending", + "position": 2, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260", + "job_id": 798245260, + "job_name": "build", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260" + } + ] + } + ] + } + }, "pending-deployment-items": { "value": [ { @@ -333406,6 +337130,15 @@ "type": "integer" } }, + "concurrency-group-name": { + "name": "concurrency_group_name", + "description": "The name of the concurrency group.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, "job-id": { "name": "job_id", "description": "The unique identifier of the job.", diff --git a/descriptions-next/api.github.com/api.github.com.2022-11-28.yaml b/descriptions-next/api.github.com/api.github.com.2022-11-28.yaml index 3901c917c..3a0dac4bf 100644 --- a/descriptions-next/api.github.com/api.github.com.2022-11-28.yaml +++ b/descriptions-next/api.github.com/api.github.com.2022-11-28.yaml @@ -343,6 +343,2530 @@ paths: enabledForGitHubApps: true category: security-advisories subcategory: global-advisories + "/agents/repos/{owner}/{repo}/tasks": + get: + summary: List tasks for repository + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a list of tasks for a specific repository + + **Fine-grained access tokens for "List tasks for repository"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + The fine-grained token must have the following permission set: + + * "Agent tasks" repository permissions (read) + + GitHub App installation access tokens are not supported for this endpoint. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks-for-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks-for-repository + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: 'Comma-separated list of task states to filter by. Can be any + combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, + `waiting_for_user`, `timed_out`, `cancelled`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + - name: creator_id + in: query + schema: + type: integer + description: Filter tasks by creator user ID + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="prev" (when current page > 1), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; + rel="next", ; + rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - 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: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + post: + summary: Start a task + description: | + > [!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](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/create-task-in-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#start-a-task + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + requestBody: + required: true + description: The task creation parameters, including the user's prompt and + optional agent settings. + content: + application/json: + schema: + type: object + required: + - prompt + properties: + prompt: + type: string + description: The user's prompt for the agent + model: + type: string + description: '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`' + create_pull_request: + type: boolean + description: Whether to create a PR. + default: false + base_ref: + type: string + description: Base ref for new branch/PR + examples: + default: + value: + prompt: Fix the login button on the homepage + base_ref: main + responses: + '201': + description: Task created successfully + content: + application/json: + schema: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + examples: + default: + value: + 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: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T00:00:00Z' + '400': + description: Problems parsing JSON + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/repos/{owner}/{repo}/tasks/{task_id}": + get: + summary: Get a task by repo + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a task by ID scoped to an owner/repo path + + **Fine-grained access tokens for "Get a task by repo"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + The fine-grained token must have the following permission set: + + * "Agent tasks" repository permissions (read) + + GitHub App installation access tokens are not supported for this endpoint. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-repo-and-id + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-repo + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + 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: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks": + get: + summary: List tasks + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a list of tasks for the authenticated user + + **Fine-grained access tokens for "List tasks"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + The fine-grained token must have the following permission set: + + * "Agent tasks" repository permissions (read) + + GitHub App installation access tokens are not supported for this endpoint. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: 'Comma-separated list of task states to filter by. Can be any + combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, + `waiting_for_user`, `timed_out`, `cancelled`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; rel="next", + ; rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - id: 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: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks/{task_id}": + get: + summary: Get a task by ID + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a task by ID with its associated sessions + + **Fine-grained access tokens for "Get a task by ID"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + The fine-grained token must have the following permission set: + + * "Agent tasks" repository permissions (read) + + GitHub App installation access tokens are not supported for this endpoint. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-id + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-id + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + 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: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Problems parsing request + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation "/app": get: summary: Get the authenticated app @@ -25733,6 +28257,111 @@ paths: enabledForGitHubApps: true category: actions subcategory: cache + "/repos/{owner}/{repo}/actions/concurrency_groups": + get: + summary: List concurrency groups for a repository + description: |- + Lists the active concurrency groups for a repository. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository + parameters: + - "$ref": "#/components/parameters/owner" + - "$ref": "#/components/parameters/repo" + - "$ref": "#/components/parameters/per-page" + - "$ref": "#/components/parameters/pagination-after" + responses: + '200': + description: Response + content: + application/json: + schema: + "$ref": "#/components/schemas/concurrency-group-list" + examples: + default: + "$ref": "#/components/examples/concurrency-group-list" + headers: + Link: + "$ref": "#/components/headers/link" + '422': + "$ref": "#/components/responses/validation_failed" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": + get: + summary: Get a concurrency group for a repository + description: |- + Gets a specific concurrency group for a repository, including all instances in the group's queue. + Returns 404 if the group is inactive or does not exist. + + Optionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items + ahead of the specified workflow run or job in the queue, plus the specified item itself + (returned as the last element). This is useful for determining what is blocking a particular + run or job. Returns 422 if the specified run or job is not in this concurrency group. + + When using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow + leases held on behalf of that run. Job-level leases within the run are not considered to + block the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow + leases on the job's ancestor paths. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/get-concurrency-group-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository + parameters: + - "$ref": "#/components/parameters/owner" + - "$ref": "#/components/parameters/repo" + - "$ref": "#/components/parameters/concurrency-group-name" + - name: ahead_of_run + description: |- + Filter to items ahead of this workflow run ID in the queue, plus the run itself. + Matches workflow-level concurrency and reusable-workflow leases held on behalf of + the run. Mutually exclusive with `ahead_of_job`. + in: query + required: false + schema: + type: integer + minimum: 1 + - name: ahead_of_job + description: |- + Filter to items ahead of this job ID in the queue, plus the job itself. + Matches job-level concurrency and reusable-workflow leases on the job's + ancestor paths. Mutually exclusive with `ahead_of_run`. + in: query + required: false + schema: + type: integer + minimum: 1 + responses: + '200': + description: Response + content: + application/json: + schema: + "$ref": "#/components/schemas/concurrency-group" + examples: + default: + "$ref": "#/components/examples/concurrency-group" + '404': + "$ref": "#/components/responses/not_found" + '422': + "$ref": "#/components/responses/validation_failed" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/jobs/{job_id}": get: summary: Get a job for a workflow run @@ -27435,6 +30064,64 @@ paths: enabledForGitHubApps: true category: actions subcategory: workflow-runs + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": + get: + summary: List concurrency groups for a workflow run + description: |- + Lists all concurrency groups associated with a workflow run or its jobs. + + The set of groups is derived from the run's configuration, so a group is + included even when the run no longer has any items currently holding or + waiting in it. In that case the `group_members` array will be empty. + `total_count` reflects the number of groups the run participates in by + configuration, not the number with active items. + + This differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`, + which returns 404 when a group has no active items. That endpoint reports + the live state of a group repo-wide, while this endpoint reports the + groups associated with a specific run by configuration. + + Results are sorted by group name and support cursor-based pagination via + `before` and `after`. The `after` cursor paginates forward only and does + not emit a `rel="prev"` Link; use `before` to page backward from a + forward page's `next` cursor. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-workflow-run + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run + parameters: + - "$ref": "#/components/parameters/owner" + - "$ref": "#/components/parameters/repo" + - "$ref": "#/components/parameters/run-id" + - "$ref": "#/components/parameters/per-page" + - "$ref": "#/components/parameters/pagination-before" + - "$ref": "#/components/parameters/pagination-after" + responses: + '200': + description: Response + content: + application/json: + schema: + "$ref": "#/components/schemas/concurrency-group-run-list" + examples: + default: + "$ref": "#/components/examples/concurrency-group-run-list" + headers: + Link: + "$ref": "#/components/headers/link" + '404': + "$ref": "#/components/responses/not_found" + '422': + "$ref": "#/components/responses/validation_failed" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": post: summary: Review custom deployment protection rules for a workflow run @@ -95139,6 +97826,112 @@ components: required: - total_count - actions_caches + concurrency-group-list: + title: Concurrency Group List + description: A list of active concurrency groups for a repository. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - last_acquired_at + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + last_acquired_at: + type: + - string + - 'null' + format: date-time + concurrency-group: + title: Concurrency Group + description: |- + A concurrency group with the workflow runs and jobs that are either currently holding + or waiting for the concurrency group lease. + type: object + required: + - group_name + - group_url + - total_count + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + total_count: + type: integer + group_members: + type: array + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: + - string + - 'null' + format: uri + description: API URL for the workflow run. + run_html_url: + type: + - string + - 'null' + format: uri + description: Web URL for the workflow run. + job_id: + type: integer + description: The ID of the job, when the item represents a job-level + or reusable-workflow-level lease. + job_name: + type: string + description: The display name of the job, when the item represents + a job-level or reusable-workflow-level lease. + job_url: + type: + - string + - 'null' + format: uri + description: API URL for the job. + job_html_url: + type: + - string + - 'null' + format: uri + description: Web URL for the job. + status: + type: string + enum: + - in_progress + - pending job: title: Job description: Information of a job execution in a workflow run @@ -95842,6 +98635,116 @@ components: - state - user - comment + concurrency-group-run-list: + title: Concurrency Group Run List + description: A list of concurrency groups associated with a workflow run. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + description: |- + The total number of concurrency groups this workflow run participates in, + derived from the run's configuration. This count is not filtered by + whether the run currently holds or is waiting in each group, so it can + include groups whose `group_members` array is empty (for example, when + the run has already released its lease in that group). + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: |- + API URL for this concurrency group. May return 404 if the group + has no active items at the time it is requested, since the + get-by-name endpoint reports the live repo-wide state of a group + while this endpoint lists groups associated with a run by + configuration. + group_members: + type: array + description: |- + Items belonging to this workflow run that are either currently holding or + waiting for the concurrency group lease. May be empty if the run no + longer has any active or queued items in this group. + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + - position + - position_url + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: + - string + - 'null' + format: uri + description: API URL for the workflow run. + run_html_url: + type: + - string + - 'null' + format: uri + description: Web URL for the workflow run. + position: + type: integer + description: Queue position. 0 means the item holds the concurrency + lease (in_progress), 1 or higher means queued (pending). + position_url: + type: string + format: uri + description: API URL to get items ahead of this item in the + concurrency group. + job_id: + type: + - integer + - 'null' + description: The ID of the job, when the item represents a job-level + or reusable-workflow-level lease. + job_name: + type: + - string + - 'null' + description: The display name of the job, when the item represents + a job-level or reusable-workflow-level lease. + job_url: + type: + - string + - 'null' + format: uri + description: API URL for the job. + job_html_url: + type: + - string + - 'null' + format: uri + description: Web URL for the job. + status: + type: string + enum: + - in_progress + - pending review-custom-gates-comment-required: type: object properties: @@ -231365,6 +234268,41 @@ components: last_accessed_at: '2019-01-24T22:45:36.000Z' created_at: '2019-01-24T22:45:36.000Z' size_in_bytes: 1024 + concurrency-group-list: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + last_acquired_at: '2026-01-15T16:14:23Z' + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + last_acquired_at: '2026-01-15T16:13:55Z' + concurrency-group: + value: + group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + total_count: 3 + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + - run_id: 30433643 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433643 + status: pending + - run_id: 30433644 + run_name: Deploy hotfix + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644 + job_id: 798245260 + job_name: deploy + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260 + status: pending job: value: id: 399444496 @@ -232041,6 +234979,34 @@ components: runner_group_name: my runner group workflow_name: CI head_branch: main + concurrency-group-run-list: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + position: 0 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642 + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: pending + position: 2 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260 + job_id: 798245260 + job_name: build + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260 pending-deployment-items: value: - environment: @@ -249466,6 +252432,13 @@ components: required: true schema: type: integer + concurrency-group-name: + name: concurrency_group_name + description: The name of the concurrency group. + in: path + required: true + schema: + type: string job-id: name: job_id description: The unique identifier of the job. diff --git a/descriptions-next/api.github.com/api.github.com.2026-03-10.json b/descriptions-next/api.github.com/api.github.com.2026-03-10.json index 30dfb1c04..15372d089 100644 --- a/descriptions-next/api.github.com/api.github.com.2026-03-10.json +++ b/descriptions-next/api.github.com/api.github.com.2026-03-10.json @@ -530,6 +530,3174 @@ } } }, + "/agents/repos/{owner}/{repo}/tasks": { + "get": { + "summary": "List tasks for repository", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for a specific repository\n\n**Fine-grained access tokens for \"List tasks for repository\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks-for-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks-for-repository" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "Comma-separated list of task states to filter by. Can be any combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, `waiting_for_user`, `timed_out`, `cancelled`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + }, + { + "name": "creator_id", + "in": "query", + "schema": { + "type": "integer" + }, + "description": "Filter tasks by creator user ID" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"prev\" (when current page > 1),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "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": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + }, + "post": { + "summary": "Start a task", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nStarts a new Copilot cloud agent task for a repository.\n\nThis endpoint is only available to users with a Copilot Business or Copilot Enterprise subscription.\n\n**Fine-grained access tokens for \"Start a task\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read and write)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/create-task-in-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#start-a-task" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + } + ], + "requestBody": { + "required": true, + "description": "The task creation parameters, including the user's prompt and optional agent settings.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "prompt" + ], + "properties": { + "prompt": { + "type": "string", + "description": "The user's prompt for the agent" + }, + "model": { + "type": "string", + "description": "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`" + }, + "create_pull_request": { + "type": "boolean", + "description": "Whether to create a PR.", + "default": false + }, + "base_ref": { + "type": "string", + "description": "Base ref for new branch/PR" + } + } + }, + "examples": { + "default": { + "value": { + "prompt": "Fix the login button on the homepage", + "base_ref": "main" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Task created successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "examples": { + "default": { + "value": { + "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" + } + } + } + } + } + }, + "400": { + "description": "Problems parsing JSON", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/repos/{owner}/{repo}/tasks/{task_id}": { + "get": { + "summary": "Get a task by repo", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID scoped to an owner/repo path\n\n**Fine-grained access tokens for \"Get a task by repo\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-repo-and-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-repo" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "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": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks": { + "get": { + "summary": "List tasks", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for the authenticated user\n\n**Fine-grained access tokens for \"List tasks\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "Comma-separated list of task states to filter by. Can be any combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, `waiting_for_user`, `timed_out`, `cancelled`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "id": "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": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks/{task_id}": { + "get": { + "summary": "Get a task by ID", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID with its associated sessions\n\n**Fine-grained access tokens for \"Get a task by ID\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-id" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "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": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Problems parsing request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, "/app": { "get": { "summary": "Get the authenticated app", @@ -35193,6 +38361,139 @@ } } }, + "/repos/{owner}/{repo}/actions/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a repository", + "description": "Lists the active concurrency groups for a repository.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository" + }, + "parameters": [ + { + "$ref": "#/components/parameters/owner" + }, + { + "$ref": "#/components/parameters/repo" + }, + { + "$ref": "#/components/parameters/per-page" + }, + { + "$ref": "#/components/parameters/pagination-after" + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/concurrency-group-list" + }, + "examples": { + "default": { + "$ref": "#/components/examples/concurrency-group-list" + } + } + } + }, + "headers": { + "Link": { + "$ref": "#/components/headers/link" + } + } + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": { + "get": { + "summary": "Get a concurrency group for a repository", + "description": "Gets a specific concurrency group for a repository, including all instances in the group's queue.\nReturns 404 if the group is inactive or does not exist.\n\nOptionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items\nahead of the specified workflow run or job in the queue, plus the specified item itself\n(returned as the last element). This is useful for determining what is blocking a particular\nrun or job. Returns 422 if the specified run or job is not in this concurrency group.\n\nWhen using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow\nleases held on behalf of that run. Job-level leases within the run are not considered to\nblock the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow\nleases on the job's ancestor paths.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/get-concurrency-group-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository" + }, + "parameters": [ + { + "$ref": "#/components/parameters/owner" + }, + { + "$ref": "#/components/parameters/repo" + }, + { + "$ref": "#/components/parameters/concurrency-group-name" + }, + { + "name": "ahead_of_run", + "description": "Filter to items ahead of this workflow run ID in the queue, plus the run itself.\nMatches workflow-level concurrency and reusable-workflow leases held on behalf of\nthe run. Mutually exclusive with `ahead_of_job`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + }, + { + "name": "ahead_of_job", + "description": "Filter to items ahead of this job ID in the queue, plus the job itself.\nMatches job-level concurrency and reusable-workflow leases on the job's\nancestor paths. Mutually exclusive with `ahead_of_run`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/concurrency-group" + }, + "examples": { + "default": { + "$ref": "#/components/examples/concurrency-group" + } + } + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/jobs/{job_id}": { "get": { "summary": "Get a job for a workflow run", @@ -37606,6 +40907,74 @@ } } }, + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a workflow run", + "description": "Lists all concurrency groups associated with a workflow run or its jobs.\n\nThe set of groups is derived from the run's configuration, so a group is\nincluded even when the run no longer has any items currently holding or\nwaiting in it. In that case the `group_members` array will be empty.\n`total_count` reflects the number of groups the run participates in by\nconfiguration, not the number with active items.\n\nThis differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`,\nwhich returns 404 when a group has no active items. That endpoint reports\nthe live state of a group repo-wide, while this endpoint reports the\ngroups associated with a specific run by configuration.\n\nResults are sorted by group name and support cursor-based pagination via\n`before` and `after`. The `after` cursor paginates forward only and does\nnot emit a `rel=\"prev\"` Link; use `before` to page backward from a\nforward page's `next` cursor.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-workflow-run", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run" + }, + "parameters": [ + { + "$ref": "#/components/parameters/owner" + }, + { + "$ref": "#/components/parameters/repo" + }, + { + "$ref": "#/components/parameters/run-id" + }, + { + "$ref": "#/components/parameters/per-page" + }, + { + "$ref": "#/components/parameters/pagination-before" + }, + { + "$ref": "#/components/parameters/pagination-after" + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/concurrency-group-run-list" + }, + "examples": { + "default": { + "$ref": "#/components/examples/concurrency-group-run-list" + } + } + } + }, + "headers": { + "Link": { + "$ref": "#/components/headers/link" + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": { "post": { "summary": "Review custom deployment protection rules for a workflow run", @@ -130227,6 +133596,144 @@ "actions_caches" ] }, + "concurrency-group-list": { + "title": "Concurrency Group List", + "description": "A list of active concurrency groups for a repository.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer" + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "last_acquired_at" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "last_acquired_at": { + "type": [ + "string", + "null" + ], + "format": "date-time" + } + } + } + } + } + }, + "concurrency-group": { + "title": "Concurrency Group", + "description": "A concurrency group with the workflow runs and jobs that are either currently holding\nor waiting for the concurrency group lease.", + "type": "object", + "required": [ + "group_name", + "group_url", + "total_count", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "total_count": { + "type": "integer" + }, + "group_members": { + "type": "array", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "API URL for the workflow run." + }, + "run_html_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "Web URL for the workflow run." + }, + "job_id": { + "type": "integer", + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_name": { + "type": "string", + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "API URL for the job." + }, + "job_html_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "Web URL for the job." + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + }, "job": { "title": "Job", "description": "Information of a job execution in a workflow run", @@ -131158,6 +134665,131 @@ "comment" ] }, + "concurrency-group-run-list": { + "title": "Concurrency Group Run List", + "description": "A list of concurrency groups associated with a workflow run.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer", + "description": "The total number of concurrency groups this workflow run participates in,\nderived from the run's configuration. This count is not filtered by\nwhether the run currently holds or is waiting in each group, so it can\ninclude groups whose `group_members` array is empty (for example, when\nthe run has already released its lease in that group)." + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group. May return 404 if the group\nhas no active items at the time it is requested, since the\nget-by-name endpoint reports the live repo-wide state of a group\nwhile this endpoint lists groups associated with a run by\nconfiguration." + }, + "group_members": { + "type": "array", + "description": "Items belonging to this workflow run that are either currently holding or\nwaiting for the concurrency group lease. May be empty if the run no\nlonger has any active or queued items in this group.", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status", + "position", + "position_url" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "API URL for the workflow run." + }, + "run_html_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "Web URL for the workflow run." + }, + "position": { + "type": "integer", + "description": "Queue position. 0 means the item holds the concurrency lease (in_progress), 1 or higher means queued (pending)." + }, + "position_url": { + "type": "string", + "format": "uri", + "description": "API URL to get items ahead of this item in the concurrency group." + }, + "job_id": { + "type": [ + "integer", + "null" + ], + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_name": { + "type": [ + "string", + "null" + ], + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "API URL for the job." + }, + "job_html_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "Web URL for the job." + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + } + } + } + }, "review-custom-gates-comment-required": { "type": "object", "properties": { @@ -311622,6 +315254,57 @@ ] } }, + "concurrency-group-list": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "last_acquired_at": "2026-01-15T16:14:23Z" + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "last_acquired_at": "2026-01-15T16:13:55Z" + } + ] + } + }, + "concurrency-group": { + "value": { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "total_count": 3, + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress" + }, + { + "run_id": 30433643, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433643", + "status": "pending" + }, + { + "run_id": 30433644, + "run_name": "Deploy hotfix", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644", + "job_id": 798245260, + "job_name": "deploy", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260", + "status": "pending" + } + ] + } + }, "job": { "value": { "id": 399444496, @@ -312410,6 +316093,47 @@ ] } }, + "concurrency-group-run-list": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress", + "position": 0, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642" + } + ] + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "pending", + "position": 2, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260", + "job_id": 798245260, + "job_name": "build", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260" + } + ] + } + ] + } + }, "pending-deployment-items": { "value": [ { @@ -332466,6 +336190,15 @@ "type": "integer" } }, + "concurrency-group-name": { + "name": "concurrency_group_name", + "description": "The name of the concurrency group.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, "job-id": { "name": "job_id", "description": "The unique identifier of the job.", diff --git a/descriptions-next/api.github.com/api.github.com.2026-03-10.yaml b/descriptions-next/api.github.com/api.github.com.2026-03-10.yaml index 6819017a1..9a3887ece 100644 --- a/descriptions-next/api.github.com/api.github.com.2026-03-10.yaml +++ b/descriptions-next/api.github.com/api.github.com.2026-03-10.yaml @@ -343,6 +343,2530 @@ paths: enabledForGitHubApps: true category: security-advisories subcategory: global-advisories + "/agents/repos/{owner}/{repo}/tasks": + get: + summary: List tasks for repository + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a list of tasks for a specific repository + + **Fine-grained access tokens for "List tasks for repository"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + The fine-grained token must have the following permission set: + + * "Agent tasks" repository permissions (read) + + GitHub App installation access tokens are not supported for this endpoint. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks-for-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks-for-repository + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: 'Comma-separated list of task states to filter by. Can be any + combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, + `waiting_for_user`, `timed_out`, `cancelled`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + - name: creator_id + in: query + schema: + type: integer + description: Filter tasks by creator user ID + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="prev" (when current page > 1), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; + rel="next", ; + rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - 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: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + post: + summary: Start a task + description: | + > [!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](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/create-task-in-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#start-a-task + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + requestBody: + required: true + description: The task creation parameters, including the user's prompt and + optional agent settings. + content: + application/json: + schema: + type: object + required: + - prompt + properties: + prompt: + type: string + description: The user's prompt for the agent + model: + type: string + description: '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`' + create_pull_request: + type: boolean + description: Whether to create a PR. + default: false + base_ref: + type: string + description: Base ref for new branch/PR + examples: + default: + value: + prompt: Fix the login button on the homepage + base_ref: main + responses: + '201': + description: Task created successfully + content: + application/json: + schema: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + examples: + default: + value: + 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: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T00:00:00Z' + '400': + description: Problems parsing JSON + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/repos/{owner}/{repo}/tasks/{task_id}": + get: + summary: Get a task by repo + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a task by ID scoped to an owner/repo path + + **Fine-grained access tokens for "Get a task by repo"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + The fine-grained token must have the following permission set: + + * "Agent tasks" repository permissions (read) + + GitHub App installation access tokens are not supported for this endpoint. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-repo-and-id + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-repo + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + 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: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks": + get: + summary: List tasks + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a list of tasks for the authenticated user + + **Fine-grained access tokens for "List tasks"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + The fine-grained token must have the following permission set: + + * "Agent tasks" repository permissions (read) + + GitHub App installation access tokens are not supported for this endpoint. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: 'Comma-separated list of task states to filter by. Can be any + combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, + `waiting_for_user`, `timed_out`, `cancelled`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; rel="next", + ; rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - id: 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: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks/{task_id}": + get: + summary: Get a task by ID + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a task by ID with its associated sessions + + **Fine-grained access tokens for "Get a task by ID"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + The fine-grained token must have the following permission set: + + * "Agent tasks" repository permissions (read) + + GitHub App installation access tokens are not supported for this endpoint. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-id + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-id + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + 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: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Problems parsing request + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation "/app": get: summary: Get the authenticated app @@ -25695,6 +28219,111 @@ paths: enabledForGitHubApps: true category: actions subcategory: cache + "/repos/{owner}/{repo}/actions/concurrency_groups": + get: + summary: List concurrency groups for a repository + description: |- + Lists the active concurrency groups for a repository. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository + parameters: + - "$ref": "#/components/parameters/owner" + - "$ref": "#/components/parameters/repo" + - "$ref": "#/components/parameters/per-page" + - "$ref": "#/components/parameters/pagination-after" + responses: + '200': + description: Response + content: + application/json: + schema: + "$ref": "#/components/schemas/concurrency-group-list" + examples: + default: + "$ref": "#/components/examples/concurrency-group-list" + headers: + Link: + "$ref": "#/components/headers/link" + '422': + "$ref": "#/components/responses/validation_failed" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": + get: + summary: Get a concurrency group for a repository + description: |- + Gets a specific concurrency group for a repository, including all instances in the group's queue. + Returns 404 if the group is inactive or does not exist. + + Optionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items + ahead of the specified workflow run or job in the queue, plus the specified item itself + (returned as the last element). This is useful for determining what is blocking a particular + run or job. Returns 422 if the specified run or job is not in this concurrency group. + + When using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow + leases held on behalf of that run. Job-level leases within the run are not considered to + block the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow + leases on the job's ancestor paths. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/get-concurrency-group-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository + parameters: + - "$ref": "#/components/parameters/owner" + - "$ref": "#/components/parameters/repo" + - "$ref": "#/components/parameters/concurrency-group-name" + - name: ahead_of_run + description: |- + Filter to items ahead of this workflow run ID in the queue, plus the run itself. + Matches workflow-level concurrency and reusable-workflow leases held on behalf of + the run. Mutually exclusive with `ahead_of_job`. + in: query + required: false + schema: + type: integer + minimum: 1 + - name: ahead_of_job + description: |- + Filter to items ahead of this job ID in the queue, plus the job itself. + Matches job-level concurrency and reusable-workflow leases on the job's + ancestor paths. Mutually exclusive with `ahead_of_run`. + in: query + required: false + schema: + type: integer + minimum: 1 + responses: + '200': + description: Response + content: + application/json: + schema: + "$ref": "#/components/schemas/concurrency-group" + examples: + default: + "$ref": "#/components/examples/concurrency-group" + '404': + "$ref": "#/components/responses/not_found" + '422': + "$ref": "#/components/responses/validation_failed" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/jobs/{job_id}": get: summary: Get a job for a workflow run @@ -27397,6 +30026,64 @@ paths: enabledForGitHubApps: true category: actions subcategory: workflow-runs + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": + get: + summary: List concurrency groups for a workflow run + description: |- + Lists all concurrency groups associated with a workflow run or its jobs. + + The set of groups is derived from the run's configuration, so a group is + included even when the run no longer has any items currently holding or + waiting in it. In that case the `group_members` array will be empty. + `total_count` reflects the number of groups the run participates in by + configuration, not the number with active items. + + This differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`, + which returns 404 when a group has no active items. That endpoint reports + the live state of a group repo-wide, while this endpoint reports the + groups associated with a specific run by configuration. + + Results are sorted by group name and support cursor-based pagination via + `before` and `after`. The `after` cursor paginates forward only and does + not emit a `rel="prev"` Link; use `before` to page backward from a + forward page's `next` cursor. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-workflow-run + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run + parameters: + - "$ref": "#/components/parameters/owner" + - "$ref": "#/components/parameters/repo" + - "$ref": "#/components/parameters/run-id" + - "$ref": "#/components/parameters/per-page" + - "$ref": "#/components/parameters/pagination-before" + - "$ref": "#/components/parameters/pagination-after" + responses: + '200': + description: Response + content: + application/json: + schema: + "$ref": "#/components/schemas/concurrency-group-run-list" + examples: + default: + "$ref": "#/components/examples/concurrency-group-run-list" + headers: + Link: + "$ref": "#/components/headers/link" + '404': + "$ref": "#/components/responses/not_found" + '422': + "$ref": "#/components/responses/validation_failed" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": post: summary: Review custom deployment protection rules for a workflow run @@ -94668,6 +97355,112 @@ components: required: - total_count - actions_caches + concurrency-group-list: + title: Concurrency Group List + description: A list of active concurrency groups for a repository. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - last_acquired_at + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + last_acquired_at: + type: + - string + - 'null' + format: date-time + concurrency-group: + title: Concurrency Group + description: |- + A concurrency group with the workflow runs and jobs that are either currently holding + or waiting for the concurrency group lease. + type: object + required: + - group_name + - group_url + - total_count + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + total_count: + type: integer + group_members: + type: array + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: + - string + - 'null' + format: uri + description: API URL for the workflow run. + run_html_url: + type: + - string + - 'null' + format: uri + description: Web URL for the workflow run. + job_id: + type: integer + description: The ID of the job, when the item represents a job-level + or reusable-workflow-level lease. + job_name: + type: string + description: The display name of the job, when the item represents + a job-level or reusable-workflow-level lease. + job_url: + type: + - string + - 'null' + format: uri + description: API URL for the job. + job_html_url: + type: + - string + - 'null' + format: uri + description: Web URL for the job. + status: + type: string + enum: + - in_progress + - pending job: title: Job description: Information of a job execution in a workflow run @@ -95371,6 +98164,116 @@ components: - state - user - comment + concurrency-group-run-list: + title: Concurrency Group Run List + description: A list of concurrency groups associated with a workflow run. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + description: |- + The total number of concurrency groups this workflow run participates in, + derived from the run's configuration. This count is not filtered by + whether the run currently holds or is waiting in each group, so it can + include groups whose `group_members` array is empty (for example, when + the run has already released its lease in that group). + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: |- + API URL for this concurrency group. May return 404 if the group + has no active items at the time it is requested, since the + get-by-name endpoint reports the live repo-wide state of a group + while this endpoint lists groups associated with a run by + configuration. + group_members: + type: array + description: |- + Items belonging to this workflow run that are either currently holding or + waiting for the concurrency group lease. May be empty if the run no + longer has any active or queued items in this group. + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + - position + - position_url + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: + - string + - 'null' + format: uri + description: API URL for the workflow run. + run_html_url: + type: + - string + - 'null' + format: uri + description: Web URL for the workflow run. + position: + type: integer + description: Queue position. 0 means the item holds the concurrency + lease (in_progress), 1 or higher means queued (pending). + position_url: + type: string + format: uri + description: API URL to get items ahead of this item in the + concurrency group. + job_id: + type: + - integer + - 'null' + description: The ID of the job, when the item represents a job-level + or reusable-workflow-level lease. + job_name: + type: + - string + - 'null' + description: The display name of the job, when the item represents + a job-level or reusable-workflow-level lease. + job_url: + type: + - string + - 'null' + format: uri + description: API URL for the job. + job_html_url: + type: + - string + - 'null' + format: uri + description: Web URL for the job. + status: + type: string + enum: + - in_progress + - pending review-custom-gates-comment-required: type: object properties: @@ -230662,6 +233565,41 @@ components: last_accessed_at: '2019-01-24T22:45:36.000Z' created_at: '2019-01-24T22:45:36.000Z' size_in_bytes: 1024 + concurrency-group-list: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + last_acquired_at: '2026-01-15T16:14:23Z' + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + last_acquired_at: '2026-01-15T16:13:55Z' + concurrency-group: + value: + group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + total_count: 3 + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + - run_id: 30433643 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433643 + status: pending + - run_id: 30433644 + run_name: Deploy hotfix + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644 + job_id: 798245260 + job_name: deploy + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260 + status: pending job: value: id: 399444496 @@ -231338,6 +234276,34 @@ components: runner_group_name: my runner group workflow_name: CI head_branch: main + concurrency-group-run-list: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + position: 0 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642 + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: pending + position: 2 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260 + job_id: 798245260 + job_name: build + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260 pending-deployment-items: value: - environment: @@ -248678,6 +251644,13 @@ components: required: true schema: type: integer + concurrency-group-name: + name: concurrency_group_name + description: The name of the concurrency group. + in: path + required: true + schema: + type: string job-id: name: job_id description: The unique identifier of the job. diff --git a/descriptions-next/api.github.com/api.github.com.json b/descriptions-next/api.github.com/api.github.com.json index 5c94afb10..206dc6e92 100644 --- a/descriptions-next/api.github.com/api.github.com.json +++ b/descriptions-next/api.github.com/api.github.com.json @@ -530,6 +530,3174 @@ } } }, + "/agents/repos/{owner}/{repo}/tasks": { + "get": { + "summary": "List tasks for repository", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for a specific repository\n\n**Fine-grained access tokens for \"List tasks for repository\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks-for-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks-for-repository" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "Comma-separated list of task states to filter by. Can be any combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, `waiting_for_user`, `timed_out`, `cancelled`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + }, + { + "name": "creator_id", + "in": "query", + "schema": { + "type": "integer" + }, + "description": "Filter tasks by creator user ID" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"prev\" (when current page > 1),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "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": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + }, + "post": { + "summary": "Start a task", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nStarts a new Copilot cloud agent task for a repository.\n\nThis endpoint is only available to users with a Copilot Business or Copilot Enterprise subscription.\n\n**Fine-grained access tokens for \"Start a task\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read and write)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/create-task-in-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#start-a-task" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + } + ], + "requestBody": { + "required": true, + "description": "The task creation parameters, including the user's prompt and optional agent settings.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "prompt" + ], + "properties": { + "prompt": { + "type": "string", + "description": "The user's prompt for the agent" + }, + "model": { + "type": "string", + "description": "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`" + }, + "create_pull_request": { + "type": "boolean", + "description": "Whether to create a PR.", + "default": false + }, + "base_ref": { + "type": "string", + "description": "Base ref for new branch/PR" + } + } + }, + "examples": { + "default": { + "value": { + "prompt": "Fix the login button on the homepage", + "base_ref": "main" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Task created successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "examples": { + "default": { + "value": { + "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" + } + } + } + } + } + }, + "400": { + "description": "Problems parsing JSON", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/repos/{owner}/{repo}/tasks/{task_id}": { + "get": { + "summary": "Get a task by repo", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID scoped to an owner/repo path\n\n**Fine-grained access tokens for \"Get a task by repo\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-repo-and-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-repo" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "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": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks": { + "get": { + "summary": "List tasks", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for the authenticated user\n\n**Fine-grained access tokens for \"List tasks\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "Comma-separated list of task states to filter by. Can be any combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, `waiting_for_user`, `timed_out`, `cancelled`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "id": "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": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks/{task_id}": { + "get": { + "summary": "Get a task by ID", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID with its associated sessions\n\n**Fine-grained access tokens for \"Get a task by ID\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-id" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "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": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Problems parsing request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, "/app": { "get": { "summary": "Get the authenticated app", @@ -35454,6 +38622,139 @@ } } }, + "/repos/{owner}/{repo}/actions/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a repository", + "description": "Lists the active concurrency groups for a repository.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository" + }, + "parameters": [ + { + "$ref": "#/components/parameters/owner" + }, + { + "$ref": "#/components/parameters/repo" + }, + { + "$ref": "#/components/parameters/per-page" + }, + { + "$ref": "#/components/parameters/pagination-after" + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/concurrency-group-list" + }, + "examples": { + "default": { + "$ref": "#/components/examples/concurrency-group-list" + } + } + } + }, + "headers": { + "Link": { + "$ref": "#/components/headers/link" + } + } + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": { + "get": { + "summary": "Get a concurrency group for a repository", + "description": "Gets a specific concurrency group for a repository, including all instances in the group's queue.\nReturns 404 if the group is inactive or does not exist.\n\nOptionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items\nahead of the specified workflow run or job in the queue, plus the specified item itself\n(returned as the last element). This is useful for determining what is blocking a particular\nrun or job. Returns 422 if the specified run or job is not in this concurrency group.\n\nWhen using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow\nleases held on behalf of that run. Job-level leases within the run are not considered to\nblock the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow\nleases on the job's ancestor paths.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/get-concurrency-group-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository" + }, + "parameters": [ + { + "$ref": "#/components/parameters/owner" + }, + { + "$ref": "#/components/parameters/repo" + }, + { + "$ref": "#/components/parameters/concurrency-group-name" + }, + { + "name": "ahead_of_run", + "description": "Filter to items ahead of this workflow run ID in the queue, plus the run itself.\nMatches workflow-level concurrency and reusable-workflow leases held on behalf of\nthe run. Mutually exclusive with `ahead_of_job`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + }, + { + "name": "ahead_of_job", + "description": "Filter to items ahead of this job ID in the queue, plus the job itself.\nMatches job-level concurrency and reusable-workflow leases on the job's\nancestor paths. Mutually exclusive with `ahead_of_run`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/concurrency-group" + }, + "examples": { + "default": { + "$ref": "#/components/examples/concurrency-group" + } + } + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/jobs/{job_id}": { "get": { "summary": "Get a job for a workflow run", @@ -37867,6 +41168,74 @@ } } }, + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a workflow run", + "description": "Lists all concurrency groups associated with a workflow run or its jobs.\n\nThe set of groups is derived from the run's configuration, so a group is\nincluded even when the run no longer has any items currently holding or\nwaiting in it. In that case the `group_members` array will be empty.\n`total_count` reflects the number of groups the run participates in by\nconfiguration, not the number with active items.\n\nThis differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`,\nwhich returns 404 when a group has no active items. That endpoint reports\nthe live state of a group repo-wide, while this endpoint reports the\ngroups associated with a specific run by configuration.\n\nResults are sorted by group name and support cursor-based pagination via\n`before` and `after`. The `after` cursor paginates forward only and does\nnot emit a `rel=\"prev\"` Link; use `before` to page backward from a\nforward page's `next` cursor.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-workflow-run", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run" + }, + "parameters": [ + { + "$ref": "#/components/parameters/owner" + }, + { + "$ref": "#/components/parameters/repo" + }, + { + "$ref": "#/components/parameters/run-id" + }, + { + "$ref": "#/components/parameters/per-page" + }, + { + "$ref": "#/components/parameters/pagination-before" + }, + { + "$ref": "#/components/parameters/pagination-after" + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/concurrency-group-run-list" + }, + "examples": { + "default": { + "$ref": "#/components/examples/concurrency-group-run-list" + } + } + } + }, + "headers": { + "Link": { + "$ref": "#/components/headers/link" + } + } + }, + "404": { + "$ref": "#/components/responses/not_found" + }, + "422": { + "$ref": "#/components/responses/validation_failed" + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": { "post": { "summary": "Review custom deployment protection rules for a workflow run", @@ -131878,6 +135247,144 @@ "actions_caches" ] }, + "concurrency-group-list": { + "title": "Concurrency Group List", + "description": "A list of active concurrency groups for a repository.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer" + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "last_acquired_at" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "last_acquired_at": { + "type": [ + "string", + "null" + ], + "format": "date-time" + } + } + } + } + } + }, + "concurrency-group": { + "title": "Concurrency Group", + "description": "A concurrency group with the workflow runs and jobs that are either currently holding\nor waiting for the concurrency group lease.", + "type": "object", + "required": [ + "group_name", + "group_url", + "total_count", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "total_count": { + "type": "integer" + }, + "group_members": { + "type": "array", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "API URL for the workflow run." + }, + "run_html_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "Web URL for the workflow run." + }, + "job_id": { + "type": "integer", + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_name": { + "type": "string", + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "API URL for the job." + }, + "job_html_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "Web URL for the job." + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + }, "job": { "title": "Job", "description": "Information of a job execution in a workflow run", @@ -132809,6 +136316,131 @@ "comment" ] }, + "concurrency-group-run-list": { + "title": "Concurrency Group Run List", + "description": "A list of concurrency groups associated with a workflow run.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer", + "description": "The total number of concurrency groups this workflow run participates in,\nderived from the run's configuration. This count is not filtered by\nwhether the run currently holds or is waiting in each group, so it can\ninclude groups whose `group_members` array is empty (for example, when\nthe run has already released its lease in that group)." + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group. May return 404 if the group\nhas no active items at the time it is requested, since the\nget-by-name endpoint reports the live repo-wide state of a group\nwhile this endpoint lists groups associated with a run by\nconfiguration." + }, + "group_members": { + "type": "array", + "description": "Items belonging to this workflow run that are either currently holding or\nwaiting for the concurrency group lease. May be empty if the run no\nlonger has any active or queued items in this group.", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status", + "position", + "position_url" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "API URL for the workflow run." + }, + "run_html_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "Web URL for the workflow run." + }, + "position": { + "type": "integer", + "description": "Queue position. 0 means the item holds the concurrency lease (in_progress), 1 or higher means queued (pending)." + }, + "position_url": { + "type": "string", + "format": "uri", + "description": "API URL to get items ahead of this item in the concurrency group." + }, + "job_id": { + "type": [ + "integer", + "null" + ], + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_name": { + "type": [ + "string", + "null" + ], + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "API URL for the job." + }, + "job_html_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "Web URL for the job." + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + } + } + } + }, "review-custom-gates-comment-required": { "type": "object", "properties": { @@ -314456,6 +318088,57 @@ ] } }, + "concurrency-group-list": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "last_acquired_at": "2026-01-15T16:14:23Z" + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "last_acquired_at": "2026-01-15T16:13:55Z" + } + ] + } + }, + "concurrency-group": { + "value": { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "total_count": 3, + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress" + }, + { + "run_id": 30433643, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433643", + "status": "pending" + }, + { + "run_id": 30433644, + "run_name": "Deploy hotfix", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644", + "job_id": 798245260, + "job_name": "deploy", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260", + "status": "pending" + } + ] + } + }, "job": { "value": { "id": 399444496, @@ -315244,6 +318927,47 @@ ] } }, + "concurrency-group-run-list": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress", + "position": 0, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642" + } + ] + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "pending", + "position": 2, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260", + "job_id": 798245260, + "job_name": "build", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260" + } + ] + } + ] + } + }, "pending-deployment-items": { "value": [ { @@ -335518,6 +339242,15 @@ "type": "integer" } }, + "concurrency-group-name": { + "name": "concurrency_group_name", + "description": "The name of the concurrency group.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, "job-id": { "name": "job_id", "description": "The unique identifier of the job.", diff --git a/descriptions-next/api.github.com/api.github.com.yaml b/descriptions-next/api.github.com/api.github.com.yaml index bee45867e..49e3cd499 100644 --- a/descriptions-next/api.github.com/api.github.com.yaml +++ b/descriptions-next/api.github.com/api.github.com.yaml @@ -343,6 +343,2530 @@ paths: enabledForGitHubApps: true category: security-advisories subcategory: global-advisories + "/agents/repos/{owner}/{repo}/tasks": + get: + summary: List tasks for repository + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a list of tasks for a specific repository + + **Fine-grained access tokens for "List tasks for repository"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + The fine-grained token must have the following permission set: + + * "Agent tasks" repository permissions (read) + + GitHub App installation access tokens are not supported for this endpoint. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks-for-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks-for-repository + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: 'Comma-separated list of task states to filter by. Can be any + combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, + `waiting_for_user`, `timed_out`, `cancelled`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + - name: creator_id + in: query + schema: + type: integer + description: Filter tasks by creator user ID + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="prev" (when current page > 1), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; + rel="next", ; + rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - 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: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + post: + summary: Start a task + description: | + > [!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](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/create-task-in-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#start-a-task + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + requestBody: + required: true + description: The task creation parameters, including the user's prompt and + optional agent settings. + content: + application/json: + schema: + type: object + required: + - prompt + properties: + prompt: + type: string + description: The user's prompt for the agent + model: + type: string + description: '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`' + create_pull_request: + type: boolean + description: Whether to create a PR. + default: false + base_ref: + type: string + description: Base ref for new branch/PR + examples: + default: + value: + prompt: Fix the login button on the homepage + base_ref: main + responses: + '201': + description: Task created successfully + content: + application/json: + schema: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + examples: + default: + value: + 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: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T00:00:00Z' + '400': + description: Problems parsing JSON + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/repos/{owner}/{repo}/tasks/{task_id}": + get: + summary: Get a task by repo + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a task by ID scoped to an owner/repo path + + **Fine-grained access tokens for "Get a task by repo"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + The fine-grained token must have the following permission set: + + * "Agent tasks" repository permissions (read) + + GitHub App installation access tokens are not supported for this endpoint. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-repo-and-id + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-repo + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + 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: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks": + get: + summary: List tasks + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a list of tasks for the authenticated user + + **Fine-grained access tokens for "List tasks"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + The fine-grained token must have the following permission set: + + * "Agent tasks" repository permissions (read) + + GitHub App installation access tokens are not supported for this endpoint. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: 'Comma-separated list of task states to filter by. Can be any + combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, + `waiting_for_user`, `timed_out`, `cancelled`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; rel="next", + ; rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - id: 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: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks/{task_id}": + get: + summary: Get a task by ID + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a task by ID with its associated sessions + + **Fine-grained access tokens for "Get a task by ID"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + The fine-grained token must have the following permission set: + + * "Agent tasks" repository permissions (read) + + GitHub App installation access tokens are not supported for this endpoint. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-id + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-id + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + 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: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Problems parsing request + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation "/app": get: summary: Get the authenticated app @@ -25846,6 +28370,111 @@ paths: enabledForGitHubApps: true category: actions subcategory: cache + "/repos/{owner}/{repo}/actions/concurrency_groups": + get: + summary: List concurrency groups for a repository + description: |- + Lists the active concurrency groups for a repository. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository + parameters: + - "$ref": "#/components/parameters/owner" + - "$ref": "#/components/parameters/repo" + - "$ref": "#/components/parameters/per-page" + - "$ref": "#/components/parameters/pagination-after" + responses: + '200': + description: Response + content: + application/json: + schema: + "$ref": "#/components/schemas/concurrency-group-list" + examples: + default: + "$ref": "#/components/examples/concurrency-group-list" + headers: + Link: + "$ref": "#/components/headers/link" + '422': + "$ref": "#/components/responses/validation_failed" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": + get: + summary: Get a concurrency group for a repository + description: |- + Gets a specific concurrency group for a repository, including all instances in the group's queue. + Returns 404 if the group is inactive or does not exist. + + Optionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items + ahead of the specified workflow run or job in the queue, plus the specified item itself + (returned as the last element). This is useful for determining what is blocking a particular + run or job. Returns 422 if the specified run or job is not in this concurrency group. + + When using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow + leases held on behalf of that run. Job-level leases within the run are not considered to + block the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow + leases on the job's ancestor paths. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/get-concurrency-group-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository + parameters: + - "$ref": "#/components/parameters/owner" + - "$ref": "#/components/parameters/repo" + - "$ref": "#/components/parameters/concurrency-group-name" + - name: ahead_of_run + description: |- + Filter to items ahead of this workflow run ID in the queue, plus the run itself. + Matches workflow-level concurrency and reusable-workflow leases held on behalf of + the run. Mutually exclusive with `ahead_of_job`. + in: query + required: false + schema: + type: integer + minimum: 1 + - name: ahead_of_job + description: |- + Filter to items ahead of this job ID in the queue, plus the job itself. + Matches job-level concurrency and reusable-workflow leases on the job's + ancestor paths. Mutually exclusive with `ahead_of_run`. + in: query + required: false + schema: + type: integer + minimum: 1 + responses: + '200': + description: Response + content: + application/json: + schema: + "$ref": "#/components/schemas/concurrency-group" + examples: + default: + "$ref": "#/components/examples/concurrency-group" + '404': + "$ref": "#/components/responses/not_found" + '422': + "$ref": "#/components/responses/validation_failed" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/jobs/{job_id}": get: summary: Get a job for a workflow run @@ -27548,6 +30177,64 @@ paths: enabledForGitHubApps: true category: actions subcategory: workflow-runs + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": + get: + summary: List concurrency groups for a workflow run + description: |- + Lists all concurrency groups associated with a workflow run or its jobs. + + The set of groups is derived from the run's configuration, so a group is + included even when the run no longer has any items currently holding or + waiting in it. In that case the `group_members` array will be empty. + `total_count` reflects the number of groups the run participates in by + configuration, not the number with active items. + + This differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`, + which returns 404 when a group has no active items. That endpoint reports + the live state of a group repo-wide, while this endpoint reports the + groups associated with a specific run by configuration. + + Results are sorted by group name and support cursor-based pagination via + `before` and `after`. The `after` cursor paginates forward only and does + not emit a `rel="prev"` Link; use `before` to page backward from a + forward page's `next` cursor. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-workflow-run + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run + parameters: + - "$ref": "#/components/parameters/owner" + - "$ref": "#/components/parameters/repo" + - "$ref": "#/components/parameters/run-id" + - "$ref": "#/components/parameters/per-page" + - "$ref": "#/components/parameters/pagination-before" + - "$ref": "#/components/parameters/pagination-after" + responses: + '200': + description: Response + content: + application/json: + schema: + "$ref": "#/components/schemas/concurrency-group-run-list" + examples: + default: + "$ref": "#/components/examples/concurrency-group-run-list" + headers: + Link: + "$ref": "#/components/headers/link" + '404': + "$ref": "#/components/responses/not_found" + '422': + "$ref": "#/components/responses/validation_failed" + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": post: summary: Review custom deployment protection rules for a workflow run @@ -95843,6 +98530,112 @@ components: required: - total_count - actions_caches + concurrency-group-list: + title: Concurrency Group List + description: A list of active concurrency groups for a repository. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - last_acquired_at + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + last_acquired_at: + type: + - string + - 'null' + format: date-time + concurrency-group: + title: Concurrency Group + description: |- + A concurrency group with the workflow runs and jobs that are either currently holding + or waiting for the concurrency group lease. + type: object + required: + - group_name + - group_url + - total_count + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + total_count: + type: integer + group_members: + type: array + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: + - string + - 'null' + format: uri + description: API URL for the workflow run. + run_html_url: + type: + - string + - 'null' + format: uri + description: Web URL for the workflow run. + job_id: + type: integer + description: The ID of the job, when the item represents a job-level + or reusable-workflow-level lease. + job_name: + type: string + description: The display name of the job, when the item represents + a job-level or reusable-workflow-level lease. + job_url: + type: + - string + - 'null' + format: uri + description: API URL for the job. + job_html_url: + type: + - string + - 'null' + format: uri + description: Web URL for the job. + status: + type: string + enum: + - in_progress + - pending job: title: Job description: Information of a job execution in a workflow run @@ -96546,6 +99339,116 @@ components: - state - user - comment + concurrency-group-run-list: + title: Concurrency Group Run List + description: A list of concurrency groups associated with a workflow run. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + description: |- + The total number of concurrency groups this workflow run participates in, + derived from the run's configuration. This count is not filtered by + whether the run currently holds or is waiting in each group, so it can + include groups whose `group_members` array is empty (for example, when + the run has already released its lease in that group). + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: |- + API URL for this concurrency group. May return 404 if the group + has no active items at the time it is requested, since the + get-by-name endpoint reports the live repo-wide state of a group + while this endpoint lists groups associated with a run by + configuration. + group_members: + type: array + description: |- + Items belonging to this workflow run that are either currently holding or + waiting for the concurrency group lease. May be empty if the run no + longer has any active or queued items in this group. + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + - position + - position_url + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: + - string + - 'null' + format: uri + description: API URL for the workflow run. + run_html_url: + type: + - string + - 'null' + format: uri + description: Web URL for the workflow run. + position: + type: integer + description: Queue position. 0 means the item holds the concurrency + lease (in_progress), 1 or higher means queued (pending). + position_url: + type: string + format: uri + description: API URL to get items ahead of this item in the + concurrency group. + job_id: + type: + - integer + - 'null' + description: The ID of the job, when the item represents a job-level + or reusable-workflow-level lease. + job_name: + type: + - string + - 'null' + description: The display name of the job, when the item represents + a job-level or reusable-workflow-level lease. + job_url: + type: + - string + - 'null' + format: uri + description: API URL for the job. + job_html_url: + type: + - string + - 'null' + format: uri + description: Web URL for the job. + status: + type: string + enum: + - in_progress + - pending review-custom-gates-comment-required: type: object properties: @@ -232639,6 +235542,41 @@ components: last_accessed_at: '2019-01-24T22:45:36.000Z' created_at: '2019-01-24T22:45:36.000Z' size_in_bytes: 1024 + concurrency-group-list: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + last_acquired_at: '2026-01-15T16:14:23Z' + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + last_acquired_at: '2026-01-15T16:13:55Z' + concurrency-group: + value: + group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + total_count: 3 + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + - run_id: 30433643 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433643 + status: pending + - run_id: 30433644 + run_name: Deploy hotfix + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644 + job_id: 798245260 + job_name: deploy + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260 + status: pending job: value: id: 399444496 @@ -233315,6 +236253,34 @@ components: runner_group_name: my runner group workflow_name: CI head_branch: main + concurrency-group-run-list: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + position: 0 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642 + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: pending + position: 2 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260 + job_id: 798245260 + job_name: build + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260 pending-deployment-items: value: - environment: @@ -250804,6 +253770,13 @@ components: required: true schema: type: integer + concurrency-group-name: + name: concurrency_group_name + description: The name of the concurrency group. + in: path + required: true + schema: + type: string job-id: name: job_id description: The unique identifier of the job. diff --git a/descriptions-next/api.github.com/dereferenced/api.github.com.2022-11-28.deref.json b/descriptions-next/api.github.com/dereferenced/api.github.com.2022-11-28.deref.json index bc80497d4..ba60ebc23 100644 --- a/descriptions-next/api.github.com/dereferenced/api.github.com.2022-11-28.deref.json +++ b/descriptions-next/api.github.com/dereferenced/api.github.com.2022-11-28.deref.json @@ -2228,6 +2228,3174 @@ } } }, + "/agents/repos/{owner}/{repo}/tasks": { + "get": { + "summary": "List tasks for repository", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for a specific repository\n\n**Fine-grained access tokens for \"List tasks for repository\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks-for-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks-for-repository" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "Comma-separated list of task states to filter by. Can be any combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, `waiting_for_user`, `timed_out`, `cancelled`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + }, + { + "name": "creator_id", + "in": "query", + "schema": { + "type": "integer" + }, + "description": "Filter tasks by creator user ID" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"prev\" (when current page > 1),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "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": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + }, + "post": { + "summary": "Start a task", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nStarts a new Copilot cloud agent task for a repository.\n\nThis endpoint is only available to users with a Copilot Business or Copilot Enterprise subscription.\n\n**Fine-grained access tokens for \"Start a task\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read and write)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/create-task-in-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#start-a-task" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + } + ], + "requestBody": { + "required": true, + "description": "The task creation parameters, including the user's prompt and optional agent settings.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "prompt" + ], + "properties": { + "prompt": { + "type": "string", + "description": "The user's prompt for the agent" + }, + "model": { + "type": "string", + "description": "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`" + }, + "create_pull_request": { + "type": "boolean", + "description": "Whether to create a PR.", + "default": false + }, + "base_ref": { + "type": "string", + "description": "Base ref for new branch/PR" + } + } + }, + "examples": { + "default": { + "value": { + "prompt": "Fix the login button on the homepage", + "base_ref": "main" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Task created successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "examples": { + "default": { + "value": { + "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" + } + } + } + } + } + }, + "400": { + "description": "Problems parsing JSON", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/repos/{owner}/{repo}/tasks/{task_id}": { + "get": { + "summary": "Get a task by repo", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID scoped to an owner/repo path\n\n**Fine-grained access tokens for \"Get a task by repo\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-repo-and-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-repo" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "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": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks": { + "get": { + "summary": "List tasks", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for the authenticated user\n\n**Fine-grained access tokens for \"List tasks\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "Comma-separated list of task states to filter by. Can be any combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, `waiting_for_user`, `timed_out`, `cancelled`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "id": "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": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks/{task_id}": { + "get": { + "summary": "Get a task by ID", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID with its associated sessions\n\n**Fine-grained access tokens for \"Get a task by ID\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-id" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "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": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Problems parsing request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, "/app": { "get": { "summary": "Get the authenticated app", @@ -274734,6 +277902,528 @@ } } }, + "/repos/{owner}/{repo}/actions/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a repository", + "description": "Lists the active concurrency groups for a repository.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "per_page", + "description": "The number of results per page (max 100). For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "schema": { + "type": "integer", + "default": 30 + } + }, + { + "name": "after", + "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results after this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group List", + "description": "A list of active concurrency groups for a repository.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer" + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "last_acquired_at" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "last_acquired_at": { + "type": [ + "string", + "null" + ], + "format": "date-time" + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "last_acquired_at": "2026-01-15T16:14:23Z" + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "last_acquired_at": "2026-01-15T16:13:55Z" + } + ] + } + } + } + } + }, + "headers": { + "Link": { + "example": "; rel=\"next\", ; rel=\"last\"", + "schema": { + "type": "string" + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": [ + "string", + "null" + ] + }, + { + "type": [ + "integer", + "null" + ] + }, + { + "type": [ + "array", + "null" + ], + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": { + "get": { + "summary": "Get a concurrency group for a repository", + "description": "Gets a specific concurrency group for a repository, including all instances in the group's queue.\nReturns 404 if the group is inactive or does not exist.\n\nOptionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items\nahead of the specified workflow run or job in the queue, plus the specified item itself\n(returned as the last element). This is useful for determining what is blocking a particular\nrun or job. Returns 422 if the specified run or job is not in this concurrency group.\n\nWhen using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow\nleases held on behalf of that run. Job-level leases within the run are not considered to\nblock the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow\nleases on the job's ancestor paths.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/get-concurrency-group-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "concurrency_group_name", + "description": "The name of the concurrency group.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "ahead_of_run", + "description": "Filter to items ahead of this workflow run ID in the queue, plus the run itself.\nMatches workflow-level concurrency and reusable-workflow leases held on behalf of\nthe run. Mutually exclusive with `ahead_of_job`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + }, + { + "name": "ahead_of_job", + "description": "Filter to items ahead of this job ID in the queue, plus the job itself.\nMatches job-level concurrency and reusable-workflow leases on the job's\nancestor paths. Mutually exclusive with `ahead_of_run`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group", + "description": "A concurrency group with the workflow runs and jobs that are either currently holding\nor waiting for the concurrency group lease.", + "type": "object", + "required": [ + "group_name", + "group_url", + "total_count", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "total_count": { + "type": "integer" + }, + "group_members": { + "type": "array", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "API URL for the workflow run." + }, + "run_html_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "Web URL for the workflow run." + }, + "job_id": { + "type": "integer", + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_name": { + "type": "string", + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "API URL for the job." + }, + "job_html_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "Web URL for the job." + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "total_count": 3, + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress" + }, + { + "run_id": 30433643, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433643", + "status": "pending" + }, + { + "run_id": 30433644, + "run_name": "Deploy hotfix", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644", + "job_id": 798245260, + "job_name": "deploy", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260", + "status": "pending" + } + ] + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": [ + "string", + "null" + ] + }, + { + "type": [ + "integer", + "null" + ] + }, + { + "type": [ + "array", + "null" + ], + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/jobs/{job_id}": { "get": { "summary": "Get a job for a workflow run", @@ -292222,6 +295912,368 @@ } } }, + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a workflow run", + "description": "Lists all concurrency groups associated with a workflow run or its jobs.\n\nThe set of groups is derived from the run's configuration, so a group is\nincluded even when the run no longer has any items currently holding or\nwaiting in it. In that case the `group_members` array will be empty.\n`total_count` reflects the number of groups the run participates in by\nconfiguration, not the number with active items.\n\nThis differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`,\nwhich returns 404 when a group has no active items. That endpoint reports\nthe live state of a group repo-wide, while this endpoint reports the\ngroups associated with a specific run by configuration.\n\nResults are sorted by group name and support cursor-based pagination via\n`before` and `after`. The `after` cursor paginates forward only and does\nnot emit a `rel=\"prev\"` Link; use `before` to page backward from a\nforward page's `next` cursor.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-workflow-run", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "run_id", + "description": "The unique identifier of the workflow run.", + "in": "path", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "per_page", + "description": "The number of results per page (max 100). For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "schema": { + "type": "integer", + "default": 30 + } + }, + { + "name": "before", + "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results before this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "after", + "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results after this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group Run List", + "description": "A list of concurrency groups associated with a workflow run.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer", + "description": "The total number of concurrency groups this workflow run participates in,\nderived from the run's configuration. This count is not filtered by\nwhether the run currently holds or is waiting in each group, so it can\ninclude groups whose `group_members` array is empty (for example, when\nthe run has already released its lease in that group)." + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group. May return 404 if the group\nhas no active items at the time it is requested, since the\nget-by-name endpoint reports the live repo-wide state of a group\nwhile this endpoint lists groups associated with a run by\nconfiguration." + }, + "group_members": { + "type": "array", + "description": "Items belonging to this workflow run that are either currently holding or\nwaiting for the concurrency group lease. May be empty if the run no\nlonger has any active or queued items in this group.", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status", + "position", + "position_url" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "API URL for the workflow run." + }, + "run_html_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "Web URL for the workflow run." + }, + "position": { + "type": "integer", + "description": "Queue position. 0 means the item holds the concurrency lease (in_progress), 1 or higher means queued (pending)." + }, + "position_url": { + "type": "string", + "format": "uri", + "description": "API URL to get items ahead of this item in the concurrency group." + }, + "job_id": { + "type": [ + "integer", + "null" + ], + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_name": { + "type": [ + "string", + "null" + ], + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "API URL for the job." + }, + "job_html_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "Web URL for the job." + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress", + "position": 0, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642" + } + ] + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "pending", + "position": 2, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260", + "job_id": 798245260, + "job_name": "build", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260" + } + ] + } + ] + } + } + } + } + }, + "headers": { + "Link": { + "example": "; rel=\"next\", ; rel=\"last\"", + "schema": { + "type": "string" + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": [ + "string", + "null" + ] + }, + { + "type": [ + "integer", + "null" + ] + }, + { + "type": [ + "array", + "null" + ], + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": { "post": { "summary": "Review custom deployment protection rules for a workflow run", diff --git a/descriptions-next/api.github.com/dereferenced/api.github.com.2022-11-28.deref.yaml b/descriptions-next/api.github.com/dereferenced/api.github.com.2022-11-28.deref.yaml index d8f4e05b8..4f6870043 100644 --- a/descriptions-next/api.github.com/dereferenced/api.github.com.2022-11-28.deref.yaml +++ b/descriptions-next/api.github.com/dereferenced/api.github.com.2022-11-28.deref.yaml @@ -1168,6 +1168,2530 @@ paths: enabledForGitHubApps: true category: security-advisories subcategory: global-advisories + "/agents/repos/{owner}/{repo}/tasks": + get: + summary: List tasks for repository + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a list of tasks for a specific repository + + **Fine-grained access tokens for "List tasks for repository"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + The fine-grained token must have the following permission set: + + * "Agent tasks" repository permissions (read) + + GitHub App installation access tokens are not supported for this endpoint. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks-for-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks-for-repository + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: 'Comma-separated list of task states to filter by. Can be any + combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, + `waiting_for_user`, `timed_out`, `cancelled`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + - name: creator_id + in: query + schema: + type: integer + description: Filter tasks by creator user ID + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="prev" (when current page > 1), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; + rel="next", ; + rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - 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: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + post: + summary: Start a task + description: | + > [!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](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/create-task-in-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#start-a-task + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + requestBody: + required: true + description: The task creation parameters, including the user's prompt and + optional agent settings. + content: + application/json: + schema: + type: object + required: + - prompt + properties: + prompt: + type: string + description: The user's prompt for the agent + model: + type: string + description: '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`' + create_pull_request: + type: boolean + description: Whether to create a PR. + default: false + base_ref: + type: string + description: Base ref for new branch/PR + examples: + default: + value: + prompt: Fix the login button on the homepage + base_ref: main + responses: + '201': + description: Task created successfully + content: + application/json: + schema: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + examples: + default: + value: + 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: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T00:00:00Z' + '400': + description: Problems parsing JSON + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/repos/{owner}/{repo}/tasks/{task_id}": + get: + summary: Get a task by repo + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a task by ID scoped to an owner/repo path + + **Fine-grained access tokens for "Get a task by repo"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + The fine-grained token must have the following permission set: + + * "Agent tasks" repository permissions (read) + + GitHub App installation access tokens are not supported for this endpoint. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-repo-and-id + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-repo + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + 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: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks": + get: + summary: List tasks + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a list of tasks for the authenticated user + + **Fine-grained access tokens for "List tasks"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + The fine-grained token must have the following permission set: + + * "Agent tasks" repository permissions (read) + + GitHub App installation access tokens are not supported for this endpoint. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: 'Comma-separated list of task states to filter by. Can be any + combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, + `waiting_for_user`, `timed_out`, `cancelled`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; rel="next", + ; rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - id: 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: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks/{task_id}": + get: + summary: Get a task by ID + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a task by ID with its associated sessions + + **Fine-grained access tokens for "Get a task by ID"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + The fine-grained token must have the following permission set: + + * "Agent tasks" repository permissions (read) + + GitHub App installation access tokens are not supported for this endpoint. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-id + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-id + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + 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: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Problems parsing request + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation "/app": get: summary: Get the authenticated app @@ -55677,6 +58201,245 @@ paths: enabledForGitHubApps: true category: actions subcategory: cache + "/repos/{owner}/{repo}/actions/concurrency_groups": + get: + summary: List concurrency groups for a repository + description: |- + Lists the active concurrency groups for a repository. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository + parameters: + - *331 + - *332 + - *17 + - *46 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group List + description: A list of active concurrency groups for a repository. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - last_acquired_at + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + last_acquired_at: + type: + - string + - 'null' + format: date-time + examples: + default: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + last_acquired_at: '2026-01-15T16:14:23Z' + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + last_acquired_at: '2026-01-15T16:13:55Z' + headers: + Link: *66 + '422': *15 + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": + get: + summary: Get a concurrency group for a repository + description: |- + Gets a specific concurrency group for a repository, including all instances in the group's queue. + Returns 404 if the group is inactive or does not exist. + + Optionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items + ahead of the specified workflow run or job in the queue, plus the specified item itself + (returned as the last element). This is useful for determining what is blocking a particular + run or job. Returns 422 if the specified run or job is not in this concurrency group. + + When using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow + leases held on behalf of that run. Job-level leases within the run are not considered to + block the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow + leases on the job's ancestor paths. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/get-concurrency-group-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository + parameters: + - *331 + - *332 + - name: concurrency_group_name + description: The name of the concurrency group. + in: path + required: true + schema: + type: string + - name: ahead_of_run + description: |- + Filter to items ahead of this workflow run ID in the queue, plus the run itself. + Matches workflow-level concurrency and reusable-workflow leases held on behalf of + the run. Mutually exclusive with `ahead_of_job`. + in: query + required: false + schema: + type: integer + minimum: 1 + - name: ahead_of_job + description: |- + Filter to items ahead of this job ID in the queue, plus the job itself. + Matches job-level concurrency and reusable-workflow leases on the job's + ancestor paths. Mutually exclusive with `ahead_of_run`. + in: query + required: false + schema: + type: integer + minimum: 1 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group + description: |- + A concurrency group with the workflow runs and jobs that are either currently holding + or waiting for the concurrency group lease. + type: object + required: + - group_name + - group_url + - total_count + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + total_count: + type: integer + group_members: + type: array + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: + - string + - 'null' + format: uri + description: API URL for the workflow run. + run_html_url: + type: + - string + - 'null' + format: uri + description: Web URL for the workflow run. + job_id: + type: integer + description: The ID of the job, when the item represents + a job-level or reusable-workflow-level lease. + job_name: + type: string + description: The display name of the job, when the item + represents a job-level or reusable-workflow-level lease. + job_url: + type: + - string + - 'null' + format: uri + description: API URL for the job. + job_html_url: + type: + - string + - 'null' + format: uri + description: Web URL for the job. + status: + type: string + enum: + - in_progress + - pending + examples: + default: + value: + group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + total_count: 3 + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + - run_id: 30433643 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433643 + status: pending + - run_id: 30433644 + run_name: Deploy hotfix + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644 + job_id: 798245260 + job_name: deploy + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260 + status: pending + '404': *6 + '422': *15 + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/jobs/{job_id}": get: summary: Get a job for a workflow run @@ -58730,6 +61493,198 @@ paths: enabledForGitHubApps: true category: actions subcategory: workflow-runs + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": + get: + summary: List concurrency groups for a workflow run + description: |- + Lists all concurrency groups associated with a workflow run or its jobs. + + The set of groups is derived from the run's configuration, so a group is + included even when the run no longer has any items currently holding or + waiting in it. In that case the `group_members` array will be empty. + `total_count` reflects the number of groups the run participates in by + configuration, not the number with active items. + + This differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`, + which returns 404 when a group has no active items. That endpoint reports + the live state of a group repo-wide, while this endpoint reports the + groups associated with a specific run by configuration. + + Results are sorted by group name and support cursor-based pagination via + `before` and `after`. The `after` cursor paginates forward only and does + not emit a `rel="prev"` Link; use `before` to page backward from a + forward page's `next` cursor. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-workflow-run + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run + parameters: + - *331 + - *332 + - *369 + - *17 + - *45 + - *46 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group Run List + description: A list of concurrency groups associated with a workflow + run. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + description: |- + The total number of concurrency groups this workflow run participates in, + derived from the run's configuration. This count is not filtered by + whether the run currently holds or is waiting in each group, so it can + include groups whose `group_members` array is empty (for example, when + the run has already released its lease in that group). + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: |- + API URL for this concurrency group. May return 404 if the group + has no active items at the time it is requested, since the + get-by-name endpoint reports the live repo-wide state of a group + while this endpoint lists groups associated with a run by + configuration. + group_members: + type: array + description: |- + Items belonging to this workflow run that are either currently holding or + waiting for the concurrency group lease. May be empty if the run no + longer has any active or queued items in this group. + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + - position + - position_url + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: + - string + - 'null' + format: uri + description: API URL for the workflow run. + run_html_url: + type: + - string + - 'null' + format: uri + description: Web URL for the workflow run. + position: + type: integer + description: Queue position. 0 means the item holds + the concurrency lease (in_progress), 1 or higher + means queued (pending). + position_url: + type: string + format: uri + description: API URL to get items ahead of this item + in the concurrency group. + job_id: + type: + - integer + - 'null' + description: The ID of the job, when the item represents + a job-level or reusable-workflow-level lease. + job_name: + type: + - string + - 'null' + description: The display name of the job, when the + item represents a job-level or reusable-workflow-level + lease. + job_url: + type: + - string + - 'null' + format: uri + description: API URL for the job. + job_html_url: + type: + - string + - 'null' + format: uri + description: Web URL for the job. + status: + type: string + enum: + - in_progress + - pending + examples: + default: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + position: 0 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642 + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: pending + position: 2 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260 + job_id: 798245260 + job_name: build + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260 + headers: + Link: *66 + '404': *6 + '422': *15 + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": post: summary: Review custom deployment protection rules for a workflow run diff --git a/descriptions-next/api.github.com/dereferenced/api.github.com.2026-03-10.deref.json b/descriptions-next/api.github.com/dereferenced/api.github.com.2026-03-10.deref.json index 728079642..d5f69c80b 100644 --- a/descriptions-next/api.github.com/dereferenced/api.github.com.2026-03-10.deref.json +++ b/descriptions-next/api.github.com/dereferenced/api.github.com.2026-03-10.deref.json @@ -2152,6 +2152,3174 @@ } } }, + "/agents/repos/{owner}/{repo}/tasks": { + "get": { + "summary": "List tasks for repository", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for a specific repository\n\n**Fine-grained access tokens for \"List tasks for repository\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks-for-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks-for-repository" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "Comma-separated list of task states to filter by. Can be any combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, `waiting_for_user`, `timed_out`, `cancelled`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + }, + { + "name": "creator_id", + "in": "query", + "schema": { + "type": "integer" + }, + "description": "Filter tasks by creator user ID" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"prev\" (when current page > 1),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "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": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + }, + "post": { + "summary": "Start a task", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nStarts a new Copilot cloud agent task for a repository.\n\nThis endpoint is only available to users with a Copilot Business or Copilot Enterprise subscription.\n\n**Fine-grained access tokens for \"Start a task\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read and write)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/create-task-in-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#start-a-task" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + } + ], + "requestBody": { + "required": true, + "description": "The task creation parameters, including the user's prompt and optional agent settings.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "prompt" + ], + "properties": { + "prompt": { + "type": "string", + "description": "The user's prompt for the agent" + }, + "model": { + "type": "string", + "description": "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`" + }, + "create_pull_request": { + "type": "boolean", + "description": "Whether to create a PR.", + "default": false + }, + "base_ref": { + "type": "string", + "description": "Base ref for new branch/PR" + } + } + }, + "examples": { + "default": { + "value": { + "prompt": "Fix the login button on the homepage", + "base_ref": "main" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Task created successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "examples": { + "default": { + "value": { + "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" + } + } + } + } + } + }, + "400": { + "description": "Problems parsing JSON", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/repos/{owner}/{repo}/tasks/{task_id}": { + "get": { + "summary": "Get a task by repo", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID scoped to an owner/repo path\n\n**Fine-grained access tokens for \"Get a task by repo\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-repo-and-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-repo" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "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": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks": { + "get": { + "summary": "List tasks", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for the authenticated user\n\n**Fine-grained access tokens for \"List tasks\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "Comma-separated list of task states to filter by. Can be any combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, `waiting_for_user`, `timed_out`, `cancelled`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "id": "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": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks/{task_id}": { + "get": { + "summary": "Get a task by ID", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID with its associated sessions\n\n**Fine-grained access tokens for \"Get a task by ID\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-id" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "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": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Problems parsing request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, "/app": { "get": { "summary": "Get the authenticated app", @@ -267130,6 +270298,528 @@ } } }, + "/repos/{owner}/{repo}/actions/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a repository", + "description": "Lists the active concurrency groups for a repository.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "per_page", + "description": "The number of results per page (max 100). For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "schema": { + "type": "integer", + "default": 30 + } + }, + { + "name": "after", + "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results after this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group List", + "description": "A list of active concurrency groups for a repository.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer" + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "last_acquired_at" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "last_acquired_at": { + "type": [ + "string", + "null" + ], + "format": "date-time" + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "last_acquired_at": "2026-01-15T16:14:23Z" + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "last_acquired_at": "2026-01-15T16:13:55Z" + } + ] + } + } + } + } + }, + "headers": { + "Link": { + "example": "; rel=\"next\", ; rel=\"last\"", + "schema": { + "type": "string" + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": [ + "string", + "null" + ] + }, + { + "type": [ + "integer", + "null" + ] + }, + { + "type": [ + "array", + "null" + ], + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": { + "get": { + "summary": "Get a concurrency group for a repository", + "description": "Gets a specific concurrency group for a repository, including all instances in the group's queue.\nReturns 404 if the group is inactive or does not exist.\n\nOptionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items\nahead of the specified workflow run or job in the queue, plus the specified item itself\n(returned as the last element). This is useful for determining what is blocking a particular\nrun or job. Returns 422 if the specified run or job is not in this concurrency group.\n\nWhen using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow\nleases held on behalf of that run. Job-level leases within the run are not considered to\nblock the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow\nleases on the job's ancestor paths.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/get-concurrency-group-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "concurrency_group_name", + "description": "The name of the concurrency group.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "ahead_of_run", + "description": "Filter to items ahead of this workflow run ID in the queue, plus the run itself.\nMatches workflow-level concurrency and reusable-workflow leases held on behalf of\nthe run. Mutually exclusive with `ahead_of_job`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + }, + { + "name": "ahead_of_job", + "description": "Filter to items ahead of this job ID in the queue, plus the job itself.\nMatches job-level concurrency and reusable-workflow leases on the job's\nancestor paths. Mutually exclusive with `ahead_of_run`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group", + "description": "A concurrency group with the workflow runs and jobs that are either currently holding\nor waiting for the concurrency group lease.", + "type": "object", + "required": [ + "group_name", + "group_url", + "total_count", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "total_count": { + "type": "integer" + }, + "group_members": { + "type": "array", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "API URL for the workflow run." + }, + "run_html_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "Web URL for the workflow run." + }, + "job_id": { + "type": "integer", + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_name": { + "type": "string", + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "API URL for the job." + }, + "job_html_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "Web URL for the job." + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "total_count": 3, + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress" + }, + { + "run_id": 30433643, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433643", + "status": "pending" + }, + { + "run_id": 30433644, + "run_name": "Deploy hotfix", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644", + "job_id": 798245260, + "job_name": "deploy", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260", + "status": "pending" + } + ] + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": [ + "string", + "null" + ] + }, + { + "type": [ + "integer", + "null" + ] + }, + { + "type": [ + "array", + "null" + ], + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/jobs/{job_id}": { "get": { "summary": "Get a job for a workflow run", @@ -284562,6 +288252,368 @@ } } }, + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a workflow run", + "description": "Lists all concurrency groups associated with a workflow run or its jobs.\n\nThe set of groups is derived from the run's configuration, so a group is\nincluded even when the run no longer has any items currently holding or\nwaiting in it. In that case the `group_members` array will be empty.\n`total_count` reflects the number of groups the run participates in by\nconfiguration, not the number with active items.\n\nThis differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`,\nwhich returns 404 when a group has no active items. That endpoint reports\nthe live state of a group repo-wide, while this endpoint reports the\ngroups associated with a specific run by configuration.\n\nResults are sorted by group name and support cursor-based pagination via\n`before` and `after`. The `after` cursor paginates forward only and does\nnot emit a `rel=\"prev\"` Link; use `before` to page backward from a\nforward page's `next` cursor.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-workflow-run", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "run_id", + "description": "The unique identifier of the workflow run.", + "in": "path", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "per_page", + "description": "The number of results per page (max 100). For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "schema": { + "type": "integer", + "default": 30 + } + }, + { + "name": "before", + "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results before this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "after", + "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results after this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group Run List", + "description": "A list of concurrency groups associated with a workflow run.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer", + "description": "The total number of concurrency groups this workflow run participates in,\nderived from the run's configuration. This count is not filtered by\nwhether the run currently holds or is waiting in each group, so it can\ninclude groups whose `group_members` array is empty (for example, when\nthe run has already released its lease in that group)." + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group. May return 404 if the group\nhas no active items at the time it is requested, since the\nget-by-name endpoint reports the live repo-wide state of a group\nwhile this endpoint lists groups associated with a run by\nconfiguration." + }, + "group_members": { + "type": "array", + "description": "Items belonging to this workflow run that are either currently holding or\nwaiting for the concurrency group lease. May be empty if the run no\nlonger has any active or queued items in this group.", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status", + "position", + "position_url" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "API URL for the workflow run." + }, + "run_html_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "Web URL for the workflow run." + }, + "position": { + "type": "integer", + "description": "Queue position. 0 means the item holds the concurrency lease (in_progress), 1 or higher means queued (pending)." + }, + "position_url": { + "type": "string", + "format": "uri", + "description": "API URL to get items ahead of this item in the concurrency group." + }, + "job_id": { + "type": [ + "integer", + "null" + ], + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_name": { + "type": [ + "string", + "null" + ], + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "API URL for the job." + }, + "job_html_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "Web URL for the job." + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress", + "position": 0, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642" + } + ] + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "pending", + "position": 2, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260", + "job_id": 798245260, + "job_name": "build", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260" + } + ] + } + ] + } + } + } + } + }, + "headers": { + "Link": { + "example": "; rel=\"next\", ; rel=\"last\"", + "schema": { + "type": "string" + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": [ + "string", + "null" + ] + }, + { + "type": [ + "integer", + "null" + ] + }, + { + "type": [ + "array", + "null" + ], + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": { "post": { "summary": "Review custom deployment protection rules for a workflow run", diff --git a/descriptions-next/api.github.com/dereferenced/api.github.com.2026-03-10.deref.yaml b/descriptions-next/api.github.com/dereferenced/api.github.com.2026-03-10.deref.yaml index a8d81b4cc..15914b6e5 100644 --- a/descriptions-next/api.github.com/dereferenced/api.github.com.2026-03-10.deref.yaml +++ b/descriptions-next/api.github.com/dereferenced/api.github.com.2026-03-10.deref.yaml @@ -1133,6 +1133,2530 @@ paths: enabledForGitHubApps: true category: security-advisories subcategory: global-advisories + "/agents/repos/{owner}/{repo}/tasks": + get: + summary: List tasks for repository + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a list of tasks for a specific repository + + **Fine-grained access tokens for "List tasks for repository"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + The fine-grained token must have the following permission set: + + * "Agent tasks" repository permissions (read) + + GitHub App installation access tokens are not supported for this endpoint. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks-for-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks-for-repository + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: 'Comma-separated list of task states to filter by. Can be any + combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, + `waiting_for_user`, `timed_out`, `cancelled`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + - name: creator_id + in: query + schema: + type: integer + description: Filter tasks by creator user ID + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="prev" (when current page > 1), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; + rel="next", ; + rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - 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: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + post: + summary: Start a task + description: | + > [!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](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/create-task-in-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#start-a-task + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + requestBody: + required: true + description: The task creation parameters, including the user's prompt and + optional agent settings. + content: + application/json: + schema: + type: object + required: + - prompt + properties: + prompt: + type: string + description: The user's prompt for the agent + model: + type: string + description: '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`' + create_pull_request: + type: boolean + description: Whether to create a PR. + default: false + base_ref: + type: string + description: Base ref for new branch/PR + examples: + default: + value: + prompt: Fix the login button on the homepage + base_ref: main + responses: + '201': + description: Task created successfully + content: + application/json: + schema: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + examples: + default: + value: + 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: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T00:00:00Z' + '400': + description: Problems parsing JSON + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/repos/{owner}/{repo}/tasks/{task_id}": + get: + summary: Get a task by repo + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a task by ID scoped to an owner/repo path + + **Fine-grained access tokens for "Get a task by repo"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + The fine-grained token must have the following permission set: + + * "Agent tasks" repository permissions (read) + + GitHub App installation access tokens are not supported for this endpoint. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-repo-and-id + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-repo + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + 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: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks": + get: + summary: List tasks + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a list of tasks for the authenticated user + + **Fine-grained access tokens for "List tasks"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + The fine-grained token must have the following permission set: + + * "Agent tasks" repository permissions (read) + + GitHub App installation access tokens are not supported for this endpoint. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: 'Comma-separated list of task states to filter by. Can be any + combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, + `waiting_for_user`, `timed_out`, `cancelled`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; rel="next", + ; rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - id: 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: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks/{task_id}": + get: + summary: Get a task by ID + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a task by ID with its associated sessions + + **Fine-grained access tokens for "Get a task by ID"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + The fine-grained token must have the following permission set: + + * "Agent tasks" repository permissions (read) + + GitHub App installation access tokens are not supported for this endpoint. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-id + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-id + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + 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: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Problems parsing request + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation "/app": get: summary: Get the authenticated app @@ -55253,6 +57777,245 @@ paths: enabledForGitHubApps: true category: actions subcategory: cache + "/repos/{owner}/{repo}/actions/concurrency_groups": + get: + summary: List concurrency groups for a repository + description: |- + Lists the active concurrency groups for a repository. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository + parameters: + - *331 + - *332 + - *17 + - *46 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group List + description: A list of active concurrency groups for a repository. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - last_acquired_at + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + last_acquired_at: + type: + - string + - 'null' + format: date-time + examples: + default: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + last_acquired_at: '2026-01-15T16:14:23Z' + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + last_acquired_at: '2026-01-15T16:13:55Z' + headers: + Link: *66 + '422': *15 + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": + get: + summary: Get a concurrency group for a repository + description: |- + Gets a specific concurrency group for a repository, including all instances in the group's queue. + Returns 404 if the group is inactive or does not exist. + + Optionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items + ahead of the specified workflow run or job in the queue, plus the specified item itself + (returned as the last element). This is useful for determining what is blocking a particular + run or job. Returns 422 if the specified run or job is not in this concurrency group. + + When using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow + leases held on behalf of that run. Job-level leases within the run are not considered to + block the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow + leases on the job's ancestor paths. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/get-concurrency-group-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository + parameters: + - *331 + - *332 + - name: concurrency_group_name + description: The name of the concurrency group. + in: path + required: true + schema: + type: string + - name: ahead_of_run + description: |- + Filter to items ahead of this workflow run ID in the queue, plus the run itself. + Matches workflow-level concurrency and reusable-workflow leases held on behalf of + the run. Mutually exclusive with `ahead_of_job`. + in: query + required: false + schema: + type: integer + minimum: 1 + - name: ahead_of_job + description: |- + Filter to items ahead of this job ID in the queue, plus the job itself. + Matches job-level concurrency and reusable-workflow leases on the job's + ancestor paths. Mutually exclusive with `ahead_of_run`. + in: query + required: false + schema: + type: integer + minimum: 1 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group + description: |- + A concurrency group with the workflow runs and jobs that are either currently holding + or waiting for the concurrency group lease. + type: object + required: + - group_name + - group_url + - total_count + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + total_count: + type: integer + group_members: + type: array + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: + - string + - 'null' + format: uri + description: API URL for the workflow run. + run_html_url: + type: + - string + - 'null' + format: uri + description: Web URL for the workflow run. + job_id: + type: integer + description: The ID of the job, when the item represents + a job-level or reusable-workflow-level lease. + job_name: + type: string + description: The display name of the job, when the item + represents a job-level or reusable-workflow-level lease. + job_url: + type: + - string + - 'null' + format: uri + description: API URL for the job. + job_html_url: + type: + - string + - 'null' + format: uri + description: Web URL for the job. + status: + type: string + enum: + - in_progress + - pending + examples: + default: + value: + group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + total_count: 3 + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + - run_id: 30433643 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433643 + status: pending + - run_id: 30433644 + run_name: Deploy hotfix + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644 + job_id: 798245260 + job_name: deploy + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260 + status: pending + '404': *6 + '422': *15 + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/jobs/{job_id}": get: summary: Get a job for a workflow run @@ -58306,6 +61069,198 @@ paths: enabledForGitHubApps: true category: actions subcategory: workflow-runs + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": + get: + summary: List concurrency groups for a workflow run + description: |- + Lists all concurrency groups associated with a workflow run or its jobs. + + The set of groups is derived from the run's configuration, so a group is + included even when the run no longer has any items currently holding or + waiting in it. In that case the `group_members` array will be empty. + `total_count` reflects the number of groups the run participates in by + configuration, not the number with active items. + + This differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`, + which returns 404 when a group has no active items. That endpoint reports + the live state of a group repo-wide, while this endpoint reports the + groups associated with a specific run by configuration. + + Results are sorted by group name and support cursor-based pagination via + `before` and `after`. The `after` cursor paginates forward only and does + not emit a `rel="prev"` Link; use `before` to page backward from a + forward page's `next` cursor. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-workflow-run + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run + parameters: + - *331 + - *332 + - *369 + - *17 + - *45 + - *46 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group Run List + description: A list of concurrency groups associated with a workflow + run. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + description: |- + The total number of concurrency groups this workflow run participates in, + derived from the run's configuration. This count is not filtered by + whether the run currently holds or is waiting in each group, so it can + include groups whose `group_members` array is empty (for example, when + the run has already released its lease in that group). + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: |- + API URL for this concurrency group. May return 404 if the group + has no active items at the time it is requested, since the + get-by-name endpoint reports the live repo-wide state of a group + while this endpoint lists groups associated with a run by + configuration. + group_members: + type: array + description: |- + Items belonging to this workflow run that are either currently holding or + waiting for the concurrency group lease. May be empty if the run no + longer has any active or queued items in this group. + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + - position + - position_url + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: + - string + - 'null' + format: uri + description: API URL for the workflow run. + run_html_url: + type: + - string + - 'null' + format: uri + description: Web URL for the workflow run. + position: + type: integer + description: Queue position. 0 means the item holds + the concurrency lease (in_progress), 1 or higher + means queued (pending). + position_url: + type: string + format: uri + description: API URL to get items ahead of this item + in the concurrency group. + job_id: + type: + - integer + - 'null' + description: The ID of the job, when the item represents + a job-level or reusable-workflow-level lease. + job_name: + type: + - string + - 'null' + description: The display name of the job, when the + item represents a job-level or reusable-workflow-level + lease. + job_url: + type: + - string + - 'null' + format: uri + description: API URL for the job. + job_html_url: + type: + - string + - 'null' + format: uri + description: Web URL for the job. + status: + type: string + enum: + - in_progress + - pending + examples: + default: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + position: 0 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642 + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: pending + position: 2 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260 + job_id: 798245260 + job_name: build + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260 + headers: + Link: *66 + '404': *6 + '422': *15 + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": post: summary: Review custom deployment protection rules for a workflow run diff --git a/descriptions-next/api.github.com/dereferenced/api.github.com.deref.json b/descriptions-next/api.github.com/dereferenced/api.github.com.deref.json index 7541edcc0..250a87434 100644 --- a/descriptions-next/api.github.com/dereferenced/api.github.com.deref.json +++ b/descriptions-next/api.github.com/dereferenced/api.github.com.deref.json @@ -2352,6 +2352,3174 @@ } } }, + "/agents/repos/{owner}/{repo}/tasks": { + "get": { + "summary": "List tasks for repository", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for a specific repository\n\n**Fine-grained access tokens for \"List tasks for repository\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks-for-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks-for-repository" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "Comma-separated list of task states to filter by. Can be any combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, `waiting_for_user`, `timed_out`, `cancelled`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + }, + { + "name": "creator_id", + "in": "query", + "schema": { + "type": "integer" + }, + "description": "Filter tasks by creator user ID" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"prev\" (when current page > 1),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "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": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + }, + "post": { + "summary": "Start a task", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nStarts a new Copilot cloud agent task for a repository.\n\nThis endpoint is only available to users with a Copilot Business or Copilot Enterprise subscription.\n\n**Fine-grained access tokens for \"Start a task\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read and write)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/create-task-in-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#start-a-task" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + } + ], + "requestBody": { + "required": true, + "description": "The task creation parameters, including the user's prompt and optional agent settings.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "prompt" + ], + "properties": { + "prompt": { + "type": "string", + "description": "The user's prompt for the agent" + }, + "model": { + "type": "string", + "description": "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`" + }, + "create_pull_request": { + "type": "boolean", + "description": "Whether to create a PR.", + "default": false + }, + "base_ref": { + "type": "string", + "description": "Base ref for new branch/PR" + } + } + }, + "examples": { + "default": { + "value": { + "prompt": "Fix the login button on the homepage", + "base_ref": "main" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Task created successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "examples": { + "default": { + "value": { + "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" + } + } + } + } + } + }, + "400": { + "description": "Problems parsing JSON", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/repos/{owner}/{repo}/tasks/{task_id}": { + "get": { + "summary": "Get a task by repo", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID scoped to an owner/repo path\n\n**Fine-grained access tokens for \"Get a task by repo\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-repo-and-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-repo" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "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": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks": { + "get": { + "summary": "List tasks", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for the authenticated user\n\n**Fine-grained access tokens for \"List tasks\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "Comma-separated list of task states to filter by. Can be any combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, `waiting_for_user`, `timed_out`, `cancelled`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "id": "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": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks/{task_id}": { + "get": { + "summary": "Get a task by ID", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID with its associated sessions\n\n**Fine-grained access tokens for \"Get a task by ID\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-id" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "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": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Problems parsing request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, "/app": { "get": { "summary": "Get the authenticated app", @@ -282503,6 +285671,528 @@ } } }, + "/repos/{owner}/{repo}/actions/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a repository", + "description": "Lists the active concurrency groups for a repository.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "per_page", + "description": "The number of results per page (max 100). For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "schema": { + "type": "integer", + "default": 30 + } + }, + { + "name": "after", + "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results after this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group List", + "description": "A list of active concurrency groups for a repository.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer" + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "last_acquired_at" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "last_acquired_at": { + "type": [ + "string", + "null" + ], + "format": "date-time" + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "last_acquired_at": "2026-01-15T16:14:23Z" + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "last_acquired_at": "2026-01-15T16:13:55Z" + } + ] + } + } + } + } + }, + "headers": { + "Link": { + "example": "; rel=\"next\", ; rel=\"last\"", + "schema": { + "type": "string" + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": [ + "string", + "null" + ] + }, + { + "type": [ + "integer", + "null" + ] + }, + { + "type": [ + "array", + "null" + ], + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": { + "get": { + "summary": "Get a concurrency group for a repository", + "description": "Gets a specific concurrency group for a repository, including all instances in the group's queue.\nReturns 404 if the group is inactive or does not exist.\n\nOptionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items\nahead of the specified workflow run or job in the queue, plus the specified item itself\n(returned as the last element). This is useful for determining what is blocking a particular\nrun or job. Returns 422 if the specified run or job is not in this concurrency group.\n\nWhen using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow\nleases held on behalf of that run. Job-level leases within the run are not considered to\nblock the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow\nleases on the job's ancestor paths.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/get-concurrency-group-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "concurrency_group_name", + "description": "The name of the concurrency group.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "ahead_of_run", + "description": "Filter to items ahead of this workflow run ID in the queue, plus the run itself.\nMatches workflow-level concurrency and reusable-workflow leases held on behalf of\nthe run. Mutually exclusive with `ahead_of_job`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + }, + { + "name": "ahead_of_job", + "description": "Filter to items ahead of this job ID in the queue, plus the job itself.\nMatches job-level concurrency and reusable-workflow leases on the job's\nancestor paths. Mutually exclusive with `ahead_of_run`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group", + "description": "A concurrency group with the workflow runs and jobs that are either currently holding\nor waiting for the concurrency group lease.", + "type": "object", + "required": [ + "group_name", + "group_url", + "total_count", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "total_count": { + "type": "integer" + }, + "group_members": { + "type": "array", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "API URL for the workflow run." + }, + "run_html_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "Web URL for the workflow run." + }, + "job_id": { + "type": "integer", + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_name": { + "type": "string", + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "API URL for the job." + }, + "job_html_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "Web URL for the job." + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "total_count": 3, + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress" + }, + { + "run_id": 30433643, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433643", + "status": "pending" + }, + { + "run_id": 30433644, + "run_name": "Deploy hotfix", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644", + "job_id": 798245260, + "job_name": "deploy", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260", + "status": "pending" + } + ] + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": [ + "string", + "null" + ] + }, + { + "type": [ + "integer", + "null" + ] + }, + { + "type": [ + "array", + "null" + ], + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/jobs/{job_id}": { "get": { "summary": "Get a job for a workflow run", @@ -300263,6 +303953,368 @@ } } }, + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a workflow run", + "description": "Lists all concurrency groups associated with a workflow run or its jobs.\n\nThe set of groups is derived from the run's configuration, so a group is\nincluded even when the run no longer has any items currently holding or\nwaiting in it. In that case the `group_members` array will be empty.\n`total_count` reflects the number of groups the run participates in by\nconfiguration, not the number with active items.\n\nThis differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`,\nwhich returns 404 when a group has no active items. That endpoint reports\nthe live state of a group repo-wide, while this endpoint reports the\ngroups associated with a specific run by configuration.\n\nResults are sorted by group name and support cursor-based pagination via\n`before` and `after`. The `after` cursor paginates forward only and does\nnot emit a `rel=\"prev\"` Link; use `before` to page backward from a\nforward page's `next` cursor.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-workflow-run", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "run_id", + "description": "The unique identifier of the workflow run.", + "in": "path", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "per_page", + "description": "The number of results per page (max 100). For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "schema": { + "type": "integer", + "default": 30 + } + }, + { + "name": "before", + "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results before this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "after", + "description": "A cursor, as given in the [Link header](https://docs.github.com/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results after this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group Run List", + "description": "A list of concurrency groups associated with a workflow run.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer", + "description": "The total number of concurrency groups this workflow run participates in,\nderived from the run's configuration. This count is not filtered by\nwhether the run currently holds or is waiting in each group, so it can\ninclude groups whose `group_members` array is empty (for example, when\nthe run has already released its lease in that group)." + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group. May return 404 if the group\nhas no active items at the time it is requested, since the\nget-by-name endpoint reports the live repo-wide state of a group\nwhile this endpoint lists groups associated with a run by\nconfiguration." + }, + "group_members": { + "type": "array", + "description": "Items belonging to this workflow run that are either currently holding or\nwaiting for the concurrency group lease. May be empty if the run no\nlonger has any active or queued items in this group.", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status", + "position", + "position_url" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "API URL for the workflow run." + }, + "run_html_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "Web URL for the workflow run." + }, + "position": { + "type": "integer", + "description": "Queue position. 0 means the item holds the concurrency lease (in_progress), 1 or higher means queued (pending)." + }, + "position_url": { + "type": "string", + "format": "uri", + "description": "API URL to get items ahead of this item in the concurrency group." + }, + "job_id": { + "type": [ + "integer", + "null" + ], + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_name": { + "type": [ + "string", + "null" + ], + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "API URL for the job." + }, + "job_html_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "Web URL for the job." + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress", + "position": 0, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642" + } + ] + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "pending", + "position": 2, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260", + "job_id": 798245260, + "job_name": "build", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260" + } + ] + } + ] + } + } + } + } + }, + "headers": { + "Link": { + "example": "; rel=\"next\", ; rel=\"last\"", + "schema": { + "type": "string" + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": [ + "string", + "null" + ] + }, + { + "type": [ + "integer", + "null" + ] + }, + { + "type": [ + "array", + "null" + ], + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": { "post": { "summary": "Review custom deployment protection rules for a workflow run", diff --git a/descriptions-next/api.github.com/dereferenced/api.github.com.deref.yaml b/descriptions-next/api.github.com/dereferenced/api.github.com.deref.yaml index e34dac270..dc09e42a7 100644 --- a/descriptions-next/api.github.com/dereferenced/api.github.com.deref.yaml +++ b/descriptions-next/api.github.com/dereferenced/api.github.com.deref.yaml @@ -1225,6 +1225,2530 @@ paths: enabledForGitHubApps: true category: security-advisories subcategory: global-advisories + "/agents/repos/{owner}/{repo}/tasks": + get: + summary: List tasks for repository + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a list of tasks for a specific repository + + **Fine-grained access tokens for "List tasks for repository"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + The fine-grained token must have the following permission set: + + * "Agent tasks" repository permissions (read) + + GitHub App installation access tokens are not supported for this endpoint. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks-for-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks-for-repository + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: 'Comma-separated list of task states to filter by. Can be any + combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, + `waiting_for_user`, `timed_out`, `cancelled`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + - name: creator_id + in: query + schema: + type: integer + description: Filter tasks by creator user ID + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="prev" (when current page > 1), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; + rel="next", ; + rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - 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: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + post: + summary: Start a task + description: | + > [!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](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/create-task-in-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#start-a-task + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + requestBody: + required: true + description: The task creation parameters, including the user's prompt and + optional agent settings. + content: + application/json: + schema: + type: object + required: + - prompt + properties: + prompt: + type: string + description: The user's prompt for the agent + model: + type: string + description: '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`' + create_pull_request: + type: boolean + description: Whether to create a PR. + default: false + base_ref: + type: string + description: Base ref for new branch/PR + examples: + default: + value: + prompt: Fix the login button on the homepage + base_ref: main + responses: + '201': + description: Task created successfully + content: + application/json: + schema: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + examples: + default: + value: + 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: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T00:00:00Z' + '400': + description: Problems parsing JSON + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/repos/{owner}/{repo}/tasks/{task_id}": + get: + summary: Get a task by repo + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a task by ID scoped to an owner/repo path + + **Fine-grained access tokens for "Get a task by repo"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + The fine-grained token must have the following permission set: + + * "Agent tasks" repository permissions (read) + + GitHub App installation access tokens are not supported for this endpoint. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-repo-and-id + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-repo + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + 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: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks": + get: + summary: List tasks + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a list of tasks for the authenticated user + + **Fine-grained access tokens for "List tasks"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + The fine-grained token must have the following permission set: + + * "Agent tasks" repository permissions (read) + + GitHub App installation access tokens are not supported for this endpoint. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#list-tasks + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: 'Comma-separated list of task states to filter by. Can be any + combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, + `waiting_for_user`, `timed_out`, `cancelled`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; rel="next", + ; rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - id: 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: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks/{task_id}": + get: + summary: Get a task by ID + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a task by ID with its associated sessions + + **Fine-grained access tokens for "Get a task by ID"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + The fine-grained token must have the following permission set: + + * "Agent tasks" repository permissions (read) + + GitHub App installation access tokens are not supported for this endpoint. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-id + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/agent-tasks/agent-tasks#get-a-task-by-id + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + 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: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Problems parsing request + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation "/app": get: summary: Get the authenticated app @@ -56291,6 +58815,245 @@ paths: enabledForGitHubApps: true category: actions subcategory: cache + "/repos/{owner}/{repo}/actions/concurrency_groups": + get: + summary: List concurrency groups for a repository + description: |- + Lists the active concurrency groups for a repository. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository + parameters: + - *331 + - *332 + - *17 + - *46 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group List + description: A list of active concurrency groups for a repository. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - last_acquired_at + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + last_acquired_at: + type: + - string + - 'null' + format: date-time + examples: + default: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + last_acquired_at: '2026-01-15T16:14:23Z' + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + last_acquired_at: '2026-01-15T16:13:55Z' + headers: + Link: *66 + '422': *15 + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": + get: + summary: Get a concurrency group for a repository + description: |- + Gets a specific concurrency group for a repository, including all instances in the group's queue. + Returns 404 if the group is inactive or does not exist. + + Optionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items + ahead of the specified workflow run or job in the queue, plus the specified item itself + (returned as the last element). This is useful for determining what is blocking a particular + run or job. Returns 422 if the specified run or job is not in this concurrency group. + + When using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow + leases held on behalf of that run. Job-level leases within the run are not considered to + block the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow + leases on the job's ancestor paths. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/get-concurrency-group-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository + parameters: + - *331 + - *332 + - name: concurrency_group_name + description: The name of the concurrency group. + in: path + required: true + schema: + type: string + - name: ahead_of_run + description: |- + Filter to items ahead of this workflow run ID in the queue, plus the run itself. + Matches workflow-level concurrency and reusable-workflow leases held on behalf of + the run. Mutually exclusive with `ahead_of_job`. + in: query + required: false + schema: + type: integer + minimum: 1 + - name: ahead_of_job + description: |- + Filter to items ahead of this job ID in the queue, plus the job itself. + Matches job-level concurrency and reusable-workflow leases on the job's + ancestor paths. Mutually exclusive with `ahead_of_run`. + in: query + required: false + schema: + type: integer + minimum: 1 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group + description: |- + A concurrency group with the workflow runs and jobs that are either currently holding + or waiting for the concurrency group lease. + type: object + required: + - group_name + - group_url + - total_count + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + total_count: + type: integer + group_members: + type: array + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: + - string + - 'null' + format: uri + description: API URL for the workflow run. + run_html_url: + type: + - string + - 'null' + format: uri + description: Web URL for the workflow run. + job_id: + type: integer + description: The ID of the job, when the item represents + a job-level or reusable-workflow-level lease. + job_name: + type: string + description: The display name of the job, when the item + represents a job-level or reusable-workflow-level lease. + job_url: + type: + - string + - 'null' + format: uri + description: API URL for the job. + job_html_url: + type: + - string + - 'null' + format: uri + description: Web URL for the job. + status: + type: string + enum: + - in_progress + - pending + examples: + default: + value: + group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + total_count: 3 + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + - run_id: 30433643 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433643 + status: pending + - run_id: 30433644 + run_name: Deploy hotfix + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644 + job_id: 798245260 + job_name: deploy + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260 + status: pending + '404': *6 + '422': *15 + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/jobs/{job_id}": get: summary: Get a job for a workflow run @@ -59344,6 +62107,198 @@ paths: enabledForGitHubApps: true category: actions subcategory: workflow-runs + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": + get: + summary: List concurrency groups for a workflow run + description: |- + Lists all concurrency groups associated with a workflow run or its jobs. + + The set of groups is derived from the run's configuration, so a group is + included even when the run no longer has any items currently holding or + waiting in it. In that case the `group_members` array will be empty. + `total_count` reflects the number of groups the run participates in by + configuration, not the number with active items. + + This differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`, + which returns 404 when a group has no active items. That endpoint reports + the live state of a group repo-wide, while this endpoint reports the + groups associated with a specific run by configuration. + + Results are sorted by group name and support cursor-based pagination via + `before` and `after`. The `after` cursor paginates forward only and does + not emit a `rel="prev"` Link; use `before` to page backward from a + forward page's `next` cursor. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-workflow-run + externalDocs: + description: API method documentation + url: https://docs.github.com/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run + parameters: + - *331 + - *332 + - *369 + - *17 + - *45 + - *46 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group Run List + description: A list of concurrency groups associated with a workflow + run. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + description: |- + The total number of concurrency groups this workflow run participates in, + derived from the run's configuration. This count is not filtered by + whether the run currently holds or is waiting in each group, so it can + include groups whose `group_members` array is empty (for example, when + the run has already released its lease in that group). + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: |- + API URL for this concurrency group. May return 404 if the group + has no active items at the time it is requested, since the + get-by-name endpoint reports the live repo-wide state of a group + while this endpoint lists groups associated with a run by + configuration. + group_members: + type: array + description: |- + Items belonging to this workflow run that are either currently holding or + waiting for the concurrency group lease. May be empty if the run no + longer has any active or queued items in this group. + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + - position + - position_url + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: + - string + - 'null' + format: uri + description: API URL for the workflow run. + run_html_url: + type: + - string + - 'null' + format: uri + description: Web URL for the workflow run. + position: + type: integer + description: Queue position. 0 means the item holds + the concurrency lease (in_progress), 1 or higher + means queued (pending). + position_url: + type: string + format: uri + description: API URL to get items ahead of this item + in the concurrency group. + job_id: + type: + - integer + - 'null' + description: The ID of the job, when the item represents + a job-level or reusable-workflow-level lease. + job_name: + type: + - string + - 'null' + description: The display name of the job, when the + item represents a job-level or reusable-workflow-level + lease. + job_url: + type: + - string + - 'null' + format: uri + description: API URL for the job. + job_html_url: + type: + - string + - 'null' + format: uri + description: Web URL for the job. + status: + type: string + enum: + - in_progress + - pending + examples: + default: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + position: 0 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642 + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: pending + position: 2 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260 + job_id: 798245260 + job_name: build + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260 + headers: + Link: *66 + '404': *6 + '422': *15 + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": post: summary: Review custom deployment protection rules for a workflow run diff --git a/descriptions-next/ghec/dereferenced/ghec.2022-11-28.deref.json b/descriptions-next/ghec/dereferenced/ghec.2022-11-28.deref.json index 540dc227f..0c5c73902 100644 --- a/descriptions-next/ghec/dereferenced/ghec.2022-11-28.deref.json +++ b/descriptions-next/ghec/dereferenced/ghec.2022-11-28.deref.json @@ -2244,6 +2244,3174 @@ } } }, + "/agents/repos/{owner}/{repo}/tasks": { + "get": { + "summary": "List tasks for repository", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for a specific repository\n\n**Fine-grained access tokens for \"List tasks for repository\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks-for-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#list-tasks-for-repository" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "Comma-separated list of task states to filter by. Can be any combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, `waiting_for_user`, `timed_out`, `cancelled`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + }, + { + "name": "creator_id", + "in": "query", + "schema": { + "type": "integer" + }, + "description": "Filter tasks by creator user ID" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"prev\" (when current page > 1),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "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": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + }, + "post": { + "summary": "Start a task", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nStarts a new Copilot cloud agent task for a repository.\n\nThis endpoint is only available to users with a Copilot Business or Copilot Enterprise subscription.\n\n**Fine-grained access tokens for \"Start a task\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read and write)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/create-task-in-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#start-a-task" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + } + ], + "requestBody": { + "required": true, + "description": "The task creation parameters, including the user's prompt and optional agent settings.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "prompt" + ], + "properties": { + "prompt": { + "type": "string", + "description": "The user's prompt for the agent" + }, + "model": { + "type": "string", + "description": "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`" + }, + "create_pull_request": { + "type": "boolean", + "description": "Whether to create a PR.", + "default": false + }, + "base_ref": { + "type": "string", + "description": "Base ref for new branch/PR" + } + } + }, + "examples": { + "default": { + "value": { + "prompt": "Fix the login button on the homepage", + "base_ref": "main" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Task created successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "examples": { + "default": { + "value": { + "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" + } + } + } + } + } + }, + "400": { + "description": "Problems parsing JSON", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/repos/{owner}/{repo}/tasks/{task_id}": { + "get": { + "summary": "Get a task by repo", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID scoped to an owner/repo path\n\n**Fine-grained access tokens for \"Get a task by repo\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-repo-and-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#get-a-task-by-repo" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "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": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks": { + "get": { + "summary": "List tasks", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for the authenticated user\n\n**Fine-grained access tokens for \"List tasks\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#list-tasks" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "Comma-separated list of task states to filter by. Can be any combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, `waiting_for_user`, `timed_out`, `cancelled`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "id": "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": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks/{task_id}": { + "get": { + "summary": "Get a task by ID", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID with its associated sessions\n\n**Fine-grained access tokens for \"Get a task by ID\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#get-a-task-by-id" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "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": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Problems parsing request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, "/app": { "get": { "summary": "Get the authenticated app", @@ -334450,6 +337618,528 @@ } } }, + "/repos/{owner}/{repo}/actions/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a repository", + "description": "Lists the active concurrency groups for a repository.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "per_page", + "description": "The number of results per page (max 100). For more information, see \"[Using pagination in the REST API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "schema": { + "type": "integer", + "default": 30 + } + }, + { + "name": "after", + "description": "A cursor, as given in the [Link header](https://docs.github.com/enterprise-cloud@latest/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results after this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group List", + "description": "A list of active concurrency groups for a repository.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer" + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "last_acquired_at" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "last_acquired_at": { + "type": [ + "string", + "null" + ], + "format": "date-time" + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "last_acquired_at": "2026-01-15T16:14:23Z" + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "last_acquired_at": "2026-01-15T16:13:55Z" + } + ] + } + } + } + } + }, + "headers": { + "Link": { + "example": "; rel=\"next\", ; rel=\"last\"", + "schema": { + "type": "string" + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": [ + "string", + "null" + ] + }, + { + "type": [ + "integer", + "null" + ] + }, + { + "type": [ + "array", + "null" + ], + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": { + "get": { + "summary": "Get a concurrency group for a repository", + "description": "Gets a specific concurrency group for a repository, including all instances in the group's queue.\nReturns 404 if the group is inactive or does not exist.\n\nOptionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items\nahead of the specified workflow run or job in the queue, plus the specified item itself\n(returned as the last element). This is useful for determining what is blocking a particular\nrun or job. Returns 422 if the specified run or job is not in this concurrency group.\n\nWhen using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow\nleases held on behalf of that run. Job-level leases within the run are not considered to\nblock the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow\nleases on the job's ancestor paths.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/get-concurrency-group-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "concurrency_group_name", + "description": "The name of the concurrency group.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "ahead_of_run", + "description": "Filter to items ahead of this workflow run ID in the queue, plus the run itself.\nMatches workflow-level concurrency and reusable-workflow leases held on behalf of\nthe run. Mutually exclusive with `ahead_of_job`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + }, + { + "name": "ahead_of_job", + "description": "Filter to items ahead of this job ID in the queue, plus the job itself.\nMatches job-level concurrency and reusable-workflow leases on the job's\nancestor paths. Mutually exclusive with `ahead_of_run`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group", + "description": "A concurrency group with the workflow runs and jobs that are either currently holding\nor waiting for the concurrency group lease.", + "type": "object", + "required": [ + "group_name", + "group_url", + "total_count", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "total_count": { + "type": "integer" + }, + "group_members": { + "type": "array", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "API URL for the workflow run." + }, + "run_html_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "Web URL for the workflow run." + }, + "job_id": { + "type": "integer", + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_name": { + "type": "string", + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "API URL for the job." + }, + "job_html_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "Web URL for the job." + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "total_count": 3, + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress" + }, + { + "run_id": 30433643, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433643", + "status": "pending" + }, + { + "run_id": 30433644, + "run_name": "Deploy hotfix", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644", + "job_id": 798245260, + "job_name": "deploy", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260", + "status": "pending" + } + ] + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": [ + "string", + "null" + ] + }, + { + "type": [ + "integer", + "null" + ] + }, + { + "type": [ + "array", + "null" + ], + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/jobs/{job_id}": { "get": { "summary": "Get a job for a workflow run", @@ -352012,6 +355702,368 @@ } } }, + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a workflow run", + "description": "Lists all concurrency groups associated with a workflow run or its jobs.\n\nThe set of groups is derived from the run's configuration, so a group is\nincluded even when the run no longer has any items currently holding or\nwaiting in it. In that case the `group_members` array will be empty.\n`total_count` reflects the number of groups the run participates in by\nconfiguration, not the number with active items.\n\nThis differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`,\nwhich returns 404 when a group has no active items. That endpoint reports\nthe live state of a group repo-wide, while this endpoint reports the\ngroups associated with a specific run by configuration.\n\nResults are sorted by group name and support cursor-based pagination via\n`before` and `after`. The `after` cursor paginates forward only and does\nnot emit a `rel=\"prev\"` Link; use `before` to page backward from a\nforward page's `next` cursor.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-workflow-run", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "run_id", + "description": "The unique identifier of the workflow run.", + "in": "path", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "per_page", + "description": "The number of results per page (max 100). For more information, see \"[Using pagination in the REST API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "schema": { + "type": "integer", + "default": 30 + } + }, + { + "name": "before", + "description": "A cursor, as given in the [Link header](https://docs.github.com/enterprise-cloud@latest/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results before this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "after", + "description": "A cursor, as given in the [Link header](https://docs.github.com/enterprise-cloud@latest/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results after this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group Run List", + "description": "A list of concurrency groups associated with a workflow run.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer", + "description": "The total number of concurrency groups this workflow run participates in,\nderived from the run's configuration. This count is not filtered by\nwhether the run currently holds or is waiting in each group, so it can\ninclude groups whose `group_members` array is empty (for example, when\nthe run has already released its lease in that group)." + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group. May return 404 if the group\nhas no active items at the time it is requested, since the\nget-by-name endpoint reports the live repo-wide state of a group\nwhile this endpoint lists groups associated with a run by\nconfiguration." + }, + "group_members": { + "type": "array", + "description": "Items belonging to this workflow run that are either currently holding or\nwaiting for the concurrency group lease. May be empty if the run no\nlonger has any active or queued items in this group.", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status", + "position", + "position_url" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "API URL for the workflow run." + }, + "run_html_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "Web URL for the workflow run." + }, + "position": { + "type": "integer", + "description": "Queue position. 0 means the item holds the concurrency lease (in_progress), 1 or higher means queued (pending)." + }, + "position_url": { + "type": "string", + "format": "uri", + "description": "API URL to get items ahead of this item in the concurrency group." + }, + "job_id": { + "type": [ + "integer", + "null" + ], + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_name": { + "type": [ + "string", + "null" + ], + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "API URL for the job." + }, + "job_html_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "Web URL for the job." + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress", + "position": 0, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642" + } + ] + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "pending", + "position": 2, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260", + "job_id": 798245260, + "job_name": "build", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260" + } + ] + } + ] + } + } + } + } + }, + "headers": { + "Link": { + "example": "; rel=\"next\", ; rel=\"last\"", + "schema": { + "type": "string" + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": [ + "string", + "null" + ] + }, + { + "type": [ + "integer", + "null" + ] + }, + { + "type": [ + "array", + "null" + ], + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": { "post": { "summary": "Review custom deployment protection rules for a workflow run", diff --git a/descriptions-next/ghec/dereferenced/ghec.2022-11-28.deref.yaml b/descriptions-next/ghec/dereferenced/ghec.2022-11-28.deref.yaml index 8f3d45e06..f8f3094ff 100644 --- a/descriptions-next/ghec/dereferenced/ghec.2022-11-28.deref.yaml +++ b/descriptions-next/ghec/dereferenced/ghec.2022-11-28.deref.yaml @@ -1176,6 +1176,2530 @@ paths: enabledForGitHubApps: true category: security-advisories subcategory: global-advisories + "/agents/repos/{owner}/{repo}/tasks": + get: + summary: List tasks for repository + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a list of tasks for a specific repository + + **Fine-grained access tokens for "List tasks for repository"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + The fine-grained token must have the following permission set: + + * "Agent tasks" repository permissions (read) + + GitHub App installation access tokens are not supported for this endpoint. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks-for-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#list-tasks-for-repository + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: 'Comma-separated list of task states to filter by. Can be any + combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, + `waiting_for_user`, `timed_out`, `cancelled`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + - name: creator_id + in: query + schema: + type: integer + description: Filter tasks by creator user ID + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="prev" (when current page > 1), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; + rel="next", ; + rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - 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: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + post: + summary: Start a task + description: | + > [!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](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/create-task-in-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#start-a-task + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + requestBody: + required: true + description: The task creation parameters, including the user's prompt and + optional agent settings. + content: + application/json: + schema: + type: object + required: + - prompt + properties: + prompt: + type: string + description: The user's prompt for the agent + model: + type: string + description: '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`' + create_pull_request: + type: boolean + description: Whether to create a PR. + default: false + base_ref: + type: string + description: Base ref for new branch/PR + examples: + default: + value: + prompt: Fix the login button on the homepage + base_ref: main + responses: + '201': + description: Task created successfully + content: + application/json: + schema: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + examples: + default: + value: + 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: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T00:00:00Z' + '400': + description: Problems parsing JSON + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/repos/{owner}/{repo}/tasks/{task_id}": + get: + summary: Get a task by repo + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a task by ID scoped to an owner/repo path + + **Fine-grained access tokens for "Get a task by repo"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + The fine-grained token must have the following permission set: + + * "Agent tasks" repository permissions (read) + + GitHub App installation access tokens are not supported for this endpoint. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-repo-and-id + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#get-a-task-by-repo + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + 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: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks": + get: + summary: List tasks + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a list of tasks for the authenticated user + + **Fine-grained access tokens for "List tasks"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + The fine-grained token must have the following permission set: + + * "Agent tasks" repository permissions (read) + + GitHub App installation access tokens are not supported for this endpoint. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#list-tasks + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: 'Comma-separated list of task states to filter by. Can be any + combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, + `waiting_for_user`, `timed_out`, `cancelled`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; rel="next", + ; rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - id: 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: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks/{task_id}": + get: + summary: Get a task by ID + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a task by ID with its associated sessions + + **Fine-grained access tokens for "Get a task by ID"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + The fine-grained token must have the following permission set: + + * "Agent tasks" repository permissions (read) + + GitHub App installation access tokens are not supported for this endpoint. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-id + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#get-a-task-by-id + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + 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: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Problems parsing request + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation "/app": get: summary: Get the authenticated app @@ -68739,6 +71263,245 @@ paths: enabledForGitHubApps: true category: actions subcategory: cache + "/repos/{owner}/{repo}/actions/concurrency_groups": + get: + summary: List concurrency groups for a repository + description: |- + Lists the active concurrency groups for a repository. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository + parameters: + - *465 + - *466 + - *17 + - *109 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group List + description: A list of active concurrency groups for a repository. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - last_acquired_at + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + last_acquired_at: + type: + - string + - 'null' + format: date-time + examples: + default: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + last_acquired_at: '2026-01-15T16:14:23Z' + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + last_acquired_at: '2026-01-15T16:13:55Z' + headers: + Link: *45 + '422': *15 + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": + get: + summary: Get a concurrency group for a repository + description: |- + Gets a specific concurrency group for a repository, including all instances in the group's queue. + Returns 404 if the group is inactive or does not exist. + + Optionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items + ahead of the specified workflow run or job in the queue, plus the specified item itself + (returned as the last element). This is useful for determining what is blocking a particular + run or job. Returns 422 if the specified run or job is not in this concurrency group. + + When using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow + leases held on behalf of that run. Job-level leases within the run are not considered to + block the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow + leases on the job's ancestor paths. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/get-concurrency-group-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository + parameters: + - *465 + - *466 + - name: concurrency_group_name + description: The name of the concurrency group. + in: path + required: true + schema: + type: string + - name: ahead_of_run + description: |- + Filter to items ahead of this workflow run ID in the queue, plus the run itself. + Matches workflow-level concurrency and reusable-workflow leases held on behalf of + the run. Mutually exclusive with `ahead_of_job`. + in: query + required: false + schema: + type: integer + minimum: 1 + - name: ahead_of_job + description: |- + Filter to items ahead of this job ID in the queue, plus the job itself. + Matches job-level concurrency and reusable-workflow leases on the job's + ancestor paths. Mutually exclusive with `ahead_of_run`. + in: query + required: false + schema: + type: integer + minimum: 1 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group + description: |- + A concurrency group with the workflow runs and jobs that are either currently holding + or waiting for the concurrency group lease. + type: object + required: + - group_name + - group_url + - total_count + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + total_count: + type: integer + group_members: + type: array + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: + - string + - 'null' + format: uri + description: API URL for the workflow run. + run_html_url: + type: + - string + - 'null' + format: uri + description: Web URL for the workflow run. + job_id: + type: integer + description: The ID of the job, when the item represents + a job-level or reusable-workflow-level lease. + job_name: + type: string + description: The display name of the job, when the item + represents a job-level or reusable-workflow-level lease. + job_url: + type: + - string + - 'null' + format: uri + description: API URL for the job. + job_html_url: + type: + - string + - 'null' + format: uri + description: Web URL for the job. + status: + type: string + enum: + - in_progress + - pending + examples: + default: + value: + group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + total_count: 3 + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + - run_id: 30433643 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433643 + status: pending + - run_id: 30433644 + run_name: Deploy hotfix + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644 + job_id: 798245260 + job_name: deploy + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260 + status: pending + '404': *6 + '422': *15 + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/jobs/{job_id}": get: summary: Get a job for a workflow run @@ -71801,6 +74564,198 @@ paths: enabledForGitHubApps: true category: actions subcategory: workflow-runs + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": + get: + summary: List concurrency groups for a workflow run + description: |- + Lists all concurrency groups associated with a workflow run or its jobs. + + The set of groups is derived from the run's configuration, so a group is + included even when the run no longer has any items currently holding or + waiting in it. In that case the `group_members` array will be empty. + `total_count` reflects the number of groups the run participates in by + configuration, not the number with active items. + + This differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`, + which returns 404 when a group has no active items. That endpoint reports + the live state of a group repo-wide, while this endpoint reports the + groups associated with a specific run by configuration. + + Results are sorted by group name and support cursor-based pagination via + `before` and `after`. The `after` cursor paginates forward only and does + not emit a `rel="prev"` Link; use `before` to page backward from a + forward page's `next` cursor. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-workflow-run + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run + parameters: + - *465 + - *466 + - *489 + - *17 + - *108 + - *109 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group Run List + description: A list of concurrency groups associated with a workflow + run. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + description: |- + The total number of concurrency groups this workflow run participates in, + derived from the run's configuration. This count is not filtered by + whether the run currently holds or is waiting in each group, so it can + include groups whose `group_members` array is empty (for example, when + the run has already released its lease in that group). + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: |- + API URL for this concurrency group. May return 404 if the group + has no active items at the time it is requested, since the + get-by-name endpoint reports the live repo-wide state of a group + while this endpoint lists groups associated with a run by + configuration. + group_members: + type: array + description: |- + Items belonging to this workflow run that are either currently holding or + waiting for the concurrency group lease. May be empty if the run no + longer has any active or queued items in this group. + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + - position + - position_url + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: + - string + - 'null' + format: uri + description: API URL for the workflow run. + run_html_url: + type: + - string + - 'null' + format: uri + description: Web URL for the workflow run. + position: + type: integer + description: Queue position. 0 means the item holds + the concurrency lease (in_progress), 1 or higher + means queued (pending). + position_url: + type: string + format: uri + description: API URL to get items ahead of this item + in the concurrency group. + job_id: + type: + - integer + - 'null' + description: The ID of the job, when the item represents + a job-level or reusable-workflow-level lease. + job_name: + type: + - string + - 'null' + description: The display name of the job, when the + item represents a job-level or reusable-workflow-level + lease. + job_url: + type: + - string + - 'null' + format: uri + description: API URL for the job. + job_html_url: + type: + - string + - 'null' + format: uri + description: Web URL for the job. + status: + type: string + enum: + - in_progress + - pending + examples: + default: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + position: 0 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642 + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: pending + position: 2 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260 + job_id: 798245260 + job_name: build + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260 + headers: + Link: *45 + '404': *6 + '422': *15 + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": post: summary: Review custom deployment protection rules for a workflow run diff --git a/descriptions-next/ghec/dereferenced/ghec.2026-03-10.deref.json b/descriptions-next/ghec/dereferenced/ghec.2026-03-10.deref.json index f0deb8b20..54cbf90a8 100644 --- a/descriptions-next/ghec/dereferenced/ghec.2026-03-10.deref.json +++ b/descriptions-next/ghec/dereferenced/ghec.2026-03-10.deref.json @@ -2168,6 +2168,3174 @@ } } }, + "/agents/repos/{owner}/{repo}/tasks": { + "get": { + "summary": "List tasks for repository", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for a specific repository\n\n**Fine-grained access tokens for \"List tasks for repository\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks-for-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#list-tasks-for-repository" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "Comma-separated list of task states to filter by. Can be any combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, `waiting_for_user`, `timed_out`, `cancelled`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + }, + { + "name": "creator_id", + "in": "query", + "schema": { + "type": "integer" + }, + "description": "Filter tasks by creator user ID" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"prev\" (when current page > 1),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "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": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + }, + "post": { + "summary": "Start a task", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nStarts a new Copilot cloud agent task for a repository.\n\nThis endpoint is only available to users with a Copilot Business or Copilot Enterprise subscription.\n\n**Fine-grained access tokens for \"Start a task\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read and write)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/create-task-in-repo", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#start-a-task" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + } + ], + "requestBody": { + "required": true, + "description": "The task creation parameters, including the user's prompt and optional agent settings.", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "prompt" + ], + "properties": { + "prompt": { + "type": "string", + "description": "The user's prompt for the agent" + }, + "model": { + "type": "string", + "description": "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`" + }, + "create_pull_request": { + "type": "boolean", + "description": "Whether to create a PR.", + "default": false + }, + "base_ref": { + "type": "string", + "description": "Base ref for new branch/PR" + } + } + }, + "examples": { + "default": { + "value": { + "prompt": "Fix the login button on the homepage", + "base_ref": "main" + } + } + } + } + } + }, + "responses": { + "201": { + "description": "Task created successfully", + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "examples": { + "default": { + "value": { + "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" + } + } + } + } + } + }, + "400": { + "description": "Problems parsing JSON", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/repos/{owner}/{repo}/tasks/{task_id}": { + "get": { + "summary": "Get a task by repo", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID scoped to an owner/repo path\n\n**Fine-grained access tokens for \"Get a task by repo\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-repo-and-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#get-a-task-by-repo" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "owner", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The account owner of the repository. The name is not case sensitive." + }, + { + "name": "repo", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The name of the repository. The name is not case sensitive." + }, + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "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": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks": { + "get": { + "summary": "List tasks", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a list of tasks for the authenticated user\n\n**Fine-grained access tokens for \"List tasks\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/list-tasks", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#list-tasks" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "per_page", + "in": "query", + "schema": { + "type": "integer", + "default": 30, + "minimum": 1, + "maximum": 100 + }, + "description": "The number of results per page (max 100)." + }, + { + "name": "page", + "in": "query", + "schema": { + "type": "integer", + "default": 1, + "minimum": 1 + }, + "description": "The page number of the results to fetch." + }, + { + "name": "sort", + "in": "query", + "schema": { + "type": "string", + "default": "updated_at", + "enum": [ + "updated_at", + "created_at" + ] + }, + "description": "The field to sort results by. Can be `updated_at` or `created_at`." + }, + { + "name": "direction", + "in": "query", + "schema": { + "type": "string", + "default": "desc", + "enum": [ + "asc", + "desc" + ] + }, + "description": "The direction to sort results. Can be `asc` or `desc`." + }, + { + "name": "state", + "in": "query", + "schema": { + "type": "string" + }, + "description": "Comma-separated list of task states to filter by. Can be any combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, `waiting_for_user`, `timed_out`, `cancelled`." + }, + { + "name": "is_archived", + "in": "query", + "schema": { + "type": "boolean", + "default": false + }, + "description": "Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`." + }, + { + "name": "since", + "in": "query", + "schema": { + "type": "string", + "format": "date-time" + }, + "description": "Only show tasks updated at or after this time (ISO 8601 timestamp)" + } + ], + "responses": { + "200": { + "description": "Tasks retrieved successfully", + "headers": { + "Link": { + "description": "Pagination links. Contains rel=\"first\" (always),\nrel=\"next\" (when more pages exist), and rel=\"last\" (when on the final page).\n", + "schema": { + "type": "string" + }, + "example": "; rel=\"next\", ; rel=\"first\"" + } + }, + "content": { + "application/json": { + "schema": { + "type": "object", + "required": [ + "tasks" + ], + "properties": { + "tasks": { + "type": "array", + "items": { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + "description": "List of tasks" + }, + "total_active_count": { + "type": "integer", + "format": "int32", + "description": "Total count of active (non-archived) tasks" + }, + "total_archived_count": { + "type": "integer", + "format": "int32", + "description": "Total count of archived tasks" + } + } + }, + "examples": { + "default": { + "value": { + "tasks": [ + { + "id": "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": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Bad request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, + "/agents/tasks/{task_id}": { + "get": { + "summary": "Get a task by ID", + "description": "> [!NOTE]\n> This endpoint is in public preview and is subject to change.\n\nReturns a task by ID with its associated sessions\n\n**Fine-grained access tokens for \"Get a task by ID\"**\n\nThis endpoint works with the following fine-grained token types:\n\n* [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app)\n* [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token)\n\nThe fine-grained token must have the following permission set:\n\n* \"Agent tasks\" repository permissions (read)\n\nGitHub App installation access tokens are not supported for this endpoint.\n", + "tags": [ + "agent-tasks" + ], + "operationId": "agent-tasks/get-task-by-id", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#get-a-task-by-id" + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "agent-tasks", + "subcategory": "agent-tasks" + }, + "parameters": [ + { + "name": "task_id", + "in": "path", + "required": true, + "schema": { + "type": "string" + }, + "description": "The unique identifier of the task." + } + ], + "responses": { + "200": { + "description": "Task retrieved successfully", + "content": { + "application/json": { + "schema": { + "allOf": [ + { + "type": "object", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Unique task identifier" + }, + "url": { + "type": "string", + "description": "API URL for this task" + }, + "html_url": { + "type": "string", + "description": "Web URL for this task" + }, + "name": { + "type": "string", + "description": "Human-readable name derived from the task prompt" + }, + "creator": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + } + ], + "description": "The entity who created this task" + }, + "creator_type": { + "type": "string", + "description": "Type of the task creator", + "enum": [ + "user", + "organization" + ] + }, + "user_collaborators": { + "type": "array", + "items": { + "type": "object", + "description": "A GitHub user", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "description": "User objects of collaborators on this task", + "deprecated": true + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this task belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "state": { + "type": "string", + "description": "Current state of the task, derived from its most recent session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "session_count": { + "type": "integer", + "format": "int32", + "description": "Number of sessions in this task" + }, + "artifacts": { + "type": "array", + "items": { + "type": "object", + "description": "A resource generated by the task", + "required": [ + "provider", + "type", + "data" + ], + "properties": { + "provider": { + "type": "string", + "enum": [ + "github" + ], + "description": "Provider namespace" + }, + "type": { + "type": "string", + "enum": [ + "pull", + "branch" + ], + "description": "Type of artifact. Available Values: `pull`, `branch`.\n" + }, + "data": { + "oneOf": [ + { + "type": "object", + "description": "A GitHub resource (pull request, issue, etc.)", + "required": [ + "id" + ], + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "GitHub resource ID" + }, + "global_id": { + "type": "string", + "description": "GraphQL global ID" + } + } + }, + { + "type": "object", + "description": "A Git branch reference", + "required": [ + "head_ref", + "base_ref" + ], + "properties": { + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + } + } + } + ], + "description": "Resource data (shape depends on type)" + } + } + }, + "description": "Resources created by this task (PRs, branches, etc.)" + }, + "archived_at": { + "type": [ + "string", + "null" + ], + "format": "date-time", + "description": "Timestamp when the task was archived, null if not archived" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp of the most recent update" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Timestamp when the task was created" + } + } + }, + { + "type": "object", + "properties": { + "sessions": { + "type": "array", + "items": { + "type": "object", + "description": "Full session details within a task", + "required": [ + "id", + "state", + "created_at" + ], + "properties": { + "id": { + "type": "string", + "description": "Session ID" + }, + "name": { + "type": "string", + "description": "Session name" + }, + "user": { + "description": "The user who created this session", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "owner": { + "description": "The owner of the repository", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the user" + } + } + }, + "repository": { + "description": "The repository this session belongs to", + "type": "object", + "properties": { + "id": { + "type": "integer", + "format": "int64", + "description": "The unique identifier of the repository" + } + } + }, + "task_id": { + "type": "string", + "description": "Task ID this session belongs to" + }, + "state": { + "type": "string", + "description": "Current state of a session", + "enum": [ + "queued", + "in_progress", + "completed", + "failed", + "idle", + "waiting_for_user", + "timed_out", + "cancelled" + ] + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "Creation timestamp" + }, + "updated_at": { + "type": "string", + "format": "date-time", + "description": "Last update timestamp" + }, + "completed_at": { + "type": "string", + "format": "date-time", + "description": "Completion timestamp" + }, + "prompt": { + "type": "string", + "description": "Content of the triggering event" + }, + "head_ref": { + "type": "string", + "description": "Head branch name" + }, + "base_ref": { + "type": "string", + "description": "Base branch name" + }, + "model": { + "type": "string", + "description": "Model used for this session" + }, + "error": { + "type": "object", + "description": "Error details for a failed session", + "properties": { + "message": { + "type": "string", + "description": "Error message" + } + } + } + } + }, + "description": "Sessions associated with this task" + } + } + } + ] + }, + "examples": { + "default": { + "value": { + "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": "completed", + "session_count": 1, + "artifacts": [ + { + "provider": "github", + "type": "pull", + "data": { + "id": 42 + } + } + ], + "archived_at": null, + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "sessions": [ + { + "id": "s1a2b3c4-d5e6-7890-abcd-ef1234567890", + "name": "Fix the login button on the homepage", + "user": { + "id": 1 + }, + "owner": { + "id": 1 + }, + "repository": { + "id": 1296269 + }, + "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "state": "completed", + "created_at": "2025-01-01T00:00:00Z", + "updated_at": "2025-01-01T01:00:00Z", + "completed_at": "2025-01-01T01:00:00Z", + "prompt": "Fix the login button on the homepage", + "head_ref": "copilot/fix-1", + "base_ref": "main", + "model": "claude-sonnet-4.6" + } + ] + } + } + } + } + } + }, + "400": { + "description": "Problems parsing request", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "401": { + "description": "Authentication required", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "403": { + "description": "Insufficient permissions", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + }, + "422": { + "description": "Validation Failed", + "content": { + "application/json": { + "schema": { + "type": "object", + "description": "Structured error response following GitHub REST API conventions.\nFor 422 Unprocessable Entity the errors array contains validation\ndetails; for other error status codes only message and\ndocumentation_url are returned.", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string", + "description": "Summary message (e.g. \"Validation Failed\", \"Not Found\")" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "description": "A single validation error", + "required": [ + "code" + ], + "properties": { + "code": { + "type": "string", + "enum": [ + "missing", + "missing_field", + "invalid", + "already_exists", + "unprocessable", + "custom" + ], + "description": "Machine-readable error code" + }, + "message": { + "type": "string", + "description": "Human-readable message (populated when code is \"custom\")" + } + } + }, + "description": "List of validation errors (present only for 422 responses)" + }, + "documentation_url": { + "type": "string", + "description": "URL to relevant API documentation" + } + } + } + } + } + } + } + } + }, "/app": { "get": { "summary": "Get the authenticated app", @@ -326547,6 +329715,528 @@ } } }, + "/repos/{owner}/{repo}/actions/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a repository", + "description": "Lists the active concurrency groups for a repository.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "per_page", + "description": "The number of results per page (max 100). For more information, see \"[Using pagination in the REST API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "schema": { + "type": "integer", + "default": 30 + } + }, + { + "name": "after", + "description": "A cursor, as given in the [Link header](https://docs.github.com/enterprise-cloud@latest/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results after this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group List", + "description": "A list of active concurrency groups for a repository.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer" + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "last_acquired_at" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "last_acquired_at": { + "type": [ + "string", + "null" + ], + "format": "date-time" + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "last_acquired_at": "2026-01-15T16:14:23Z" + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "last_acquired_at": "2026-01-15T16:13:55Z" + } + ] + } + } + } + } + }, + "headers": { + "Link": { + "example": "; rel=\"next\", ; rel=\"last\"", + "schema": { + "type": "string" + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": [ + "string", + "null" + ] + }, + { + "type": [ + "integer", + "null" + ] + }, + { + "type": [ + "array", + "null" + ], + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": { + "get": { + "summary": "Get a concurrency group for a repository", + "description": "Gets a specific concurrency group for a repository, including all instances in the group's queue.\nReturns 404 if the group is inactive or does not exist.\n\nOptionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items\nahead of the specified workflow run or job in the queue, plus the specified item itself\n(returned as the last element). This is useful for determining what is blocking a particular\nrun or job. Returns 422 if the specified run or job is not in this concurrency group.\n\nWhen using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow\nleases held on behalf of that run. Job-level leases within the run are not considered to\nblock the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow\nleases on the job's ancestor paths.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/get-concurrency-group-for-repository", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "concurrency_group_name", + "description": "The name of the concurrency group.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "ahead_of_run", + "description": "Filter to items ahead of this workflow run ID in the queue, plus the run itself.\nMatches workflow-level concurrency and reusable-workflow leases held on behalf of\nthe run. Mutually exclusive with `ahead_of_job`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + }, + { + "name": "ahead_of_job", + "description": "Filter to items ahead of this job ID in the queue, plus the job itself.\nMatches job-level concurrency and reusable-workflow leases on the job's\nancestor paths. Mutually exclusive with `ahead_of_run`.", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 1 + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group", + "description": "A concurrency group with the workflow runs and jobs that are either currently holding\nor waiting for the concurrency group lease.", + "type": "object", + "required": [ + "group_name", + "group_url", + "total_count", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group." + }, + "total_count": { + "type": "integer" + }, + "group_members": { + "type": "array", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "API URL for the workflow run." + }, + "run_html_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "Web URL for the workflow run." + }, + "job_id": { + "type": "integer", + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_name": { + "type": "string", + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "API URL for the job." + }, + "job_html_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "Web URL for the job." + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "total_count": 3, + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress" + }, + { + "run_id": 30433643, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433643", + "status": "pending" + }, + { + "run_id": 30433644, + "run_name": "Deploy hotfix", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644", + "job_id": 798245260, + "job_name": "deploy", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260", + "status": "pending" + } + ] + } + } + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": [ + "string", + "null" + ] + }, + { + "type": [ + "integer", + "null" + ] + }, + { + "type": [ + "array", + "null" + ], + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/jobs/{job_id}": { "get": { "summary": "Get a job for a workflow run", @@ -344053,6 +347743,368 @@ } } }, + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": { + "get": { + "summary": "List concurrency groups for a workflow run", + "description": "Lists all concurrency groups associated with a workflow run or its jobs.\n\nThe set of groups is derived from the run's configuration, so a group is\nincluded even when the run no longer has any items currently holding or\nwaiting in it. In that case the `group_members` array will be empty.\n`total_count` reflects the number of groups the run participates in by\nconfiguration, not the number with active items.\n\nThis differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`,\nwhich returns 404 when a group has no active items. That endpoint reports\nthe live state of a group repo-wide, while this endpoint reports the\ngroups associated with a specific run by configuration.\n\nResults are sorted by group name and support cursor-based pagination via\n`before` and `after`. The `after` cursor paginates forward only and does\nnot emit a `rel=\"prev\"` Link; use `before` to page backward from a\nforward page's `next` cursor.\n\nOAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository.", + "tags": [ + "actions" + ], + "operationId": "actions/list-concurrency-groups-for-workflow-run", + "externalDocs": { + "description": "API method documentation", + "url": "https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run" + }, + "parameters": [ + { + "name": "owner", + "description": "The account owner of the repository. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "repo", + "description": "The name of the repository without the `.git` extension. The name is not case sensitive.", + "in": "path", + "required": true, + "schema": { + "type": "string" + } + }, + { + "name": "run_id", + "description": "The unique identifier of the workflow run.", + "in": "path", + "required": true, + "schema": { + "type": "integer" + } + }, + { + "name": "per_page", + "description": "The number of results per page (max 100). For more information, see \"[Using pagination in the REST API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "schema": { + "type": "integer", + "default": 30 + } + }, + { + "name": "before", + "description": "A cursor, as given in the [Link header](https://docs.github.com/enterprise-cloud@latest/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results before this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + }, + { + "name": "after", + "description": "A cursor, as given in the [Link header](https://docs.github.com/enterprise-cloud@latest/rest/guides/using-pagination-in-the-rest-api#using-link-headers). If specified, the query only searches for results after this cursor. For more information, see \"[Using pagination in the REST API](https://docs.github.com/enterprise-cloud@latest/rest/using-the-rest-api/using-pagination-in-the-rest-api).\"", + "in": "query", + "required": false, + "schema": { + "type": "string" + } + } + ], + "responses": { + "200": { + "description": "Response", + "content": { + "application/json": { + "schema": { + "title": "Concurrency Group Run List", + "description": "A list of concurrency groups associated with a workflow run.", + "type": "object", + "required": [ + "total_count", + "concurrency_groups" + ], + "properties": { + "total_count": { + "type": "integer", + "description": "The total number of concurrency groups this workflow run participates in,\nderived from the run's configuration. This count is not filtered by\nwhether the run currently holds or is waiting in each group, so it can\ninclude groups whose `group_members` array is empty (for example, when\nthe run has already released its lease in that group)." + }, + "concurrency_groups": { + "type": "array", + "items": { + "type": "object", + "required": [ + "group_name", + "group_url", + "group_members" + ], + "properties": { + "group_name": { + "type": "string", + "description": "The name of the concurrency group." + }, + "group_url": { + "type": "string", + "format": "uri", + "description": "API URL for this concurrency group. May return 404 if the group\nhas no active items at the time it is requested, since the\nget-by-name endpoint reports the live repo-wide state of a group\nwhile this endpoint lists groups associated with a run by\nconfiguration." + }, + "group_members": { + "type": "array", + "description": "Items belonging to this workflow run that are either currently holding or\nwaiting for the concurrency group lease. May be empty if the run no\nlonger has any active or queued items in this group.", + "items": { + "type": "object", + "required": [ + "run_id", + "run_name", + "run_url", + "run_html_url", + "status", + "position", + "position_url" + ], + "properties": { + "run_id": { + "type": "integer", + "description": "The ID of the workflow run." + }, + "run_name": { + "type": "string", + "description": "The name of the workflow run." + }, + "run_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "API URL for the workflow run." + }, + "run_html_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "Web URL for the workflow run." + }, + "position": { + "type": "integer", + "description": "Queue position. 0 means the item holds the concurrency lease (in_progress), 1 or higher means queued (pending)." + }, + "position_url": { + "type": "string", + "format": "uri", + "description": "API URL to get items ahead of this item in the concurrency group." + }, + "job_id": { + "type": [ + "integer", + "null" + ], + "description": "The ID of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_name": { + "type": [ + "string", + "null" + ], + "description": "The display name of the job, when the item represents a job-level or reusable-workflow-level lease." + }, + "job_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "API URL for the job." + }, + "job_html_url": { + "type": [ + "string", + "null" + ], + "format": "uri", + "description": "Web URL for the job." + }, + "status": { + "type": "string", + "enum": [ + "in_progress", + "pending" + ] + } + } + } + } + } + } + } + } + }, + "examples": { + "default": { + "value": { + "total_count": 2, + "concurrency_groups": [ + { + "group_name": "deploy-prod", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "in_progress", + "position": 0, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642" + } + ] + }, + { + "group_name": "ci-build", + "group_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build", + "group_members": [ + { + "run_id": 30433642, + "run_name": "Deploy to production", + "run_url": "https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642", + "run_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642", + "status": "pending", + "position": 2, + "position_url": "https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build?ahead_of_job=798245260", + "job_id": 798245260, + "job_name": "build", + "job_url": "https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260", + "job_html_url": "https://github.com/octocat/Hello-World/actions/runs/30433642/job/798245260" + } + ] + } + ] + } + } + } + } + }, + "headers": { + "Link": { + "example": "; rel=\"next\", ; rel=\"last\"", + "schema": { + "type": "string" + } + } + } + }, + "404": { + "description": "Resource not found", + "content": { + "application/json": { + "schema": { + "title": "Basic Error", + "description": "Basic Error", + "type": "object", + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "url": { + "type": "string" + }, + "status": { + "type": "string" + } + } + } + } + } + }, + "422": { + "description": "Validation failed, or the endpoint has been spammed.", + "content": { + "application/json": { + "schema": { + "title": "Validation Error", + "description": "Validation Error", + "type": "object", + "required": [ + "message", + "documentation_url" + ], + "properties": { + "message": { + "type": "string" + }, + "documentation_url": { + "type": "string" + }, + "errors": { + "type": "array", + "items": { + "type": "object", + "required": [ + "code" + ], + "properties": { + "resource": { + "type": "string" + }, + "field": { + "type": "string" + }, + "message": { + "type": "string" + }, + "code": { + "type": "string" + }, + "index": { + "type": "integer" + }, + "value": { + "oneOf": [ + { + "type": [ + "string", + "null" + ] + }, + { + "type": [ + "integer", + "null" + ] + }, + { + "type": [ + "array", + "null" + ], + "items": { + "type": "string" + } + } + ] + } + } + } + } + } + } + } + } + } + }, + "x-github": { + "githubCloudOnly": false, + "enabledForGitHubApps": true, + "category": "actions", + "subcategory": "concurrency-groups" + } + } + }, "/repos/{owner}/{repo}/actions/runs/{run_id}/deployment_protection_rule": { "post": { "summary": "Review custom deployment protection rules for a workflow run", diff --git a/descriptions-next/ghec/dereferenced/ghec.2026-03-10.deref.yaml b/descriptions-next/ghec/dereferenced/ghec.2026-03-10.deref.yaml index 74985f54e..868d88115 100644 --- a/descriptions-next/ghec/dereferenced/ghec.2026-03-10.deref.yaml +++ b/descriptions-next/ghec/dereferenced/ghec.2026-03-10.deref.yaml @@ -1141,6 +1141,2530 @@ paths: enabledForGitHubApps: true category: security-advisories subcategory: global-advisories + "/agents/repos/{owner}/{repo}/tasks": + get: + summary: List tasks for repository + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a list of tasks for a specific repository + + **Fine-grained access tokens for "List tasks for repository"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + The fine-grained token must have the following permission set: + + * "Agent tasks" repository permissions (read) + + GitHub App installation access tokens are not supported for this endpoint. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks-for-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#list-tasks-for-repository + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: 'Comma-separated list of task states to filter by. Can be any + combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, + `waiting_for_user`, `timed_out`, `cancelled`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + - name: creator_id + in: query + schema: + type: integer + description: Filter tasks by creator user ID + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="prev" (when current page > 1), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; + rel="next", ; + rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - 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: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + post: + summary: Start a task + description: | + > [!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](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + 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. + tags: + - agent-tasks + operationId: agent-tasks/create-task-in-repo + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#start-a-task + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + requestBody: + required: true + description: The task creation parameters, including the user's prompt and + optional agent settings. + content: + application/json: + schema: + type: object + required: + - prompt + properties: + prompt: + type: string + description: The user's prompt for the agent + model: + type: string + description: '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`' + create_pull_request: + type: boolean + description: Whether to create a PR. + default: false + base_ref: + type: string + description: Base ref for new branch/PR + examples: + default: + value: + prompt: Fix the login button on the homepage + base_ref: main + responses: + '201': + description: Task created successfully + content: + application/json: + schema: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + examples: + default: + value: + 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: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T00:00:00Z' + '400': + description: Problems parsing JSON + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/repos/{owner}/{repo}/tasks/{task_id}": + get: + summary: Get a task by repo + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a task by ID scoped to an owner/repo path + + **Fine-grained access tokens for "Get a task by repo"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + The fine-grained token must have the following permission set: + + * "Agent tasks" repository permissions (read) + + GitHub App installation access tokens are not supported for this endpoint. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-repo-and-id + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#get-a-task-by-repo + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: owner + in: path + required: true + schema: + type: string + description: The account owner of the repository. The name is not case sensitive. + - name: repo + in: path + required: true + schema: + type: string + description: The name of the repository. The name is not case sensitive. + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + 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: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks": + get: + summary: List tasks + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a list of tasks for the authenticated user + + **Fine-grained access tokens for "List tasks"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + The fine-grained token must have the following permission set: + + * "Agent tasks" repository permissions (read) + + GitHub App installation access tokens are not supported for this endpoint. + tags: + - agent-tasks + operationId: agent-tasks/list-tasks + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#list-tasks + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: per_page + in: query + schema: + type: integer + default: 30 + minimum: 1 + maximum: 100 + description: The number of results per page (max 100). + - name: page + in: query + schema: + type: integer + default: 1 + minimum: 1 + description: The page number of the results to fetch. + - name: sort + in: query + schema: + type: string + default: updated_at + enum: + - updated_at + - created_at + description: The field to sort results by. Can be `updated_at` or `created_at`. + - name: direction + in: query + schema: + type: string + default: desc + enum: + - asc + - desc + description: The direction to sort results. Can be `asc` or `desc`. + - name: state + in: query + schema: + type: string + description: 'Comma-separated list of task states to filter by. Can be any + combination of: `queued`, `in_progress`, `completed`, `failed`, `idle`, + `waiting_for_user`, `timed_out`, `cancelled`.' + - name: is_archived + in: query + schema: + type: boolean + default: false + description: Filter by archived status. When `true`, returns only archived + tasks. When `false` or omitted, returns only non-archived tasks. Defaults + to `false`. + - name: since + in: query + schema: + type: string + format: date-time + description: Only show tasks updated at or after this time (ISO 8601 timestamp) + responses: + '200': + description: Tasks retrieved successfully + headers: + Link: + description: | + Pagination links. Contains rel="first" (always), + rel="next" (when more pages exist), and rel="last" (when on the final page). + schema: + type: string + example: ; rel="next", + ; rel="first" + content: + application/json: + schema: + type: object + required: + - tasks + properties: + tasks: + type: array + items: + type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its + most recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: + `pull`, `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null + if not archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + description: List of tasks + total_active_count: + type: integer + format: int32 + description: Total count of active (non-archived) tasks + total_archived_count: + type: integer + format: int32 + description: Total count of archived tasks + examples: + default: + value: + tasks: + - id: 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: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + '400': + description: Bad request + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + "/agents/tasks/{task_id}": + get: + summary: Get a task by ID + description: | + > [!NOTE] + > This endpoint is in public preview and is subject to change. + + Returns a task by ID with its associated sessions + + **Fine-grained access tokens for "Get a task by ID"** + + This endpoint works with the following fine-grained token types: + + * [GitHub App user access tokens](https://docs.github.com/enterprise-cloud@latest/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app) + * [Fine-grained personal access tokens](https://docs.github.com/enterprise-cloud@latest/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token) + + The fine-grained token must have the following permission set: + + * "Agent tasks" repository permissions (read) + + GitHub App installation access tokens are not supported for this endpoint. + tags: + - agent-tasks + operationId: agent-tasks/get-task-by-id + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/agent-tasks/agent-tasks#get-a-task-by-id + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: agent-tasks + subcategory: agent-tasks + parameters: + - name: task_id + in: path + required: true + schema: + type: string + description: The unique identifier of the task. + responses: + '200': + description: Task retrieved successfully + content: + application/json: + schema: + allOf: + - type: object + required: + - id + - state + - created_at + properties: + id: + type: string + description: Unique task identifier + url: + type: string + description: API URL for this task + html_url: + type: string + description: Web URL for this task + name: + type: string + description: Human-readable name derived from the task prompt + creator: + oneOf: + - type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: The entity who created this task + creator_type: + type: string + description: Type of the task creator + enum: + - user + - organization + user_collaborators: + type: array + items: + type: object + description: A GitHub user + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + description: User objects of collaborators on this task + deprecated: true + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this task belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + state: + type: string + description: Current state of the task, derived from its most + recent session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + session_count: + type: integer + format: int32 + description: Number of sessions in this task + artifacts: + type: array + items: + type: object + description: A resource generated by the task + required: + - provider + - type + - data + properties: + provider: + type: string + enum: + - github + description: Provider namespace + type: + type: string + enum: + - pull + - branch + description: 'Type of artifact. Available Values: `pull`, + `branch`. + + ' + data: + oneOf: + - type: object + description: A GitHub resource (pull request, issue, + etc.) + required: + - id + properties: + id: + type: integer + format: int64 + description: GitHub resource ID + global_id: + type: string + description: GraphQL global ID + - type: object + description: A Git branch reference + required: + - head_ref + - base_ref + properties: + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + description: Resource data (shape depends on type) + description: Resources created by this task (PRs, branches, + etc.) + archived_at: + type: + - string + - 'null' + format: date-time + description: Timestamp when the task was archived, null if not + archived + updated_at: + type: string + format: date-time + description: Timestamp of the most recent update + created_at: + type: string + format: date-time + description: Timestamp when the task was created + - type: object + properties: + sessions: + type: array + items: + type: object + description: Full session details within a task + required: + - id + - state + - created_at + properties: + id: + type: string + description: Session ID + name: + type: string + description: Session name + user: + description: The user who created this session + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + owner: + description: The owner of the repository + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the user + repository: + description: The repository this session belongs to + type: object + properties: + id: + type: integer + format: int64 + description: The unique identifier of the repository + task_id: + type: string + description: Task ID this session belongs to + state: + type: string + description: Current state of a session + enum: + - queued + - in_progress + - completed + - failed + - idle + - waiting_for_user + - timed_out + - cancelled + created_at: + type: string + format: date-time + description: Creation timestamp + updated_at: + type: string + format: date-time + description: Last update timestamp + completed_at: + type: string + format: date-time + description: Completion timestamp + prompt: + type: string + description: Content of the triggering event + head_ref: + type: string + description: Head branch name + base_ref: + type: string + description: Base branch name + model: + type: string + description: Model used for this session + error: + type: object + description: Error details for a failed session + properties: + message: + type: string + description: Error message + description: Sessions associated with this task + examples: + default: + value: + 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: completed + session_count: 1 + artifacts: + - provider: github + type: pull + data: + id: 42 + archived_at: + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + sessions: + - id: s1a2b3c4-d5e6-7890-abcd-ef1234567890 + name: Fix the login button on the homepage + user: + id: 1 + owner: + id: 1 + repository: + id: 1296269 + task_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 + state: completed + created_at: '2025-01-01T00:00:00Z' + updated_at: '2025-01-01T01:00:00Z' + completed_at: '2025-01-01T01:00:00Z' + prompt: Fix the login button on the homepage + head_ref: copilot/fix-1 + base_ref: main + model: claude-sonnet-4.6 + '400': + description: Problems parsing request + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '401': + description: Authentication required + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '403': + description: Insufficient permissions + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '404': + description: Resource not found + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation + '422': + description: Validation Failed + content: + application/json: + schema: + type: object + description: |- + 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. + required: + - message + - documentation_url + properties: + message: + type: string + description: Summary message (e.g. "Validation Failed", "Not Found") + errors: + type: array + items: + type: object + description: A single validation error + required: + - code + properties: + code: + type: string + enum: + - missing + - missing_field + - invalid + - already_exists + - unprocessable + - custom + description: Machine-readable error code + message: + type: string + description: Human-readable message (populated when code + is "custom") + description: List of validation errors (present only for 422 responses) + documentation_url: + type: string + description: URL to relevant API documentation "/app": get: summary: Get the authenticated app @@ -68303,6 +70827,245 @@ paths: enabledForGitHubApps: true category: actions subcategory: cache + "/repos/{owner}/{repo}/actions/concurrency_groups": + get: + summary: List concurrency groups for a repository + description: |- + Lists the active concurrency groups for a repository. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#list-concurrency-groups-for-a-repository + parameters: + - *465 + - *466 + - *17 + - *109 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group List + description: A list of active concurrency groups for a repository. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - last_acquired_at + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + last_acquired_at: + type: + - string + - 'null' + format: date-time + examples: + default: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + last_acquired_at: '2026-01-15T16:14:23Z' + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + last_acquired_at: '2026-01-15T16:13:55Z' + headers: + Link: *45 + '422': *15 + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups + "/repos/{owner}/{repo}/actions/concurrency_groups/{concurrency_group_name}": + get: + summary: Get a concurrency group for a repository + description: |- + Gets a specific concurrency group for a repository, including all instances in the group's queue. + Returns 404 if the group is inactive or does not exist. + + Optionally, pass `ahead_of_run` or `ahead_of_job` to filter the results to only the items + ahead of the specified workflow run or job in the queue, plus the specified item itself + (returned as the last element). This is useful for determining what is blocking a particular + run or job. Returns 422 if the specified run or job is not in this concurrency group. + + When using `ahead_of_run`, this matches workflow-level concurrency and any reusable-workflow + leases held on behalf of that run. Job-level leases within the run are not considered to + block the run as a whole. Use `ahead_of_job` to match job-level concurrency and reusable-workflow + leases on the job's ancestor paths. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/get-concurrency-group-for-repository + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#get-a-concurrency-group-for-a-repository + parameters: + - *465 + - *466 + - name: concurrency_group_name + description: The name of the concurrency group. + in: path + required: true + schema: + type: string + - name: ahead_of_run + description: |- + Filter to items ahead of this workflow run ID in the queue, plus the run itself. + Matches workflow-level concurrency and reusable-workflow leases held on behalf of + the run. Mutually exclusive with `ahead_of_job`. + in: query + required: false + schema: + type: integer + minimum: 1 + - name: ahead_of_job + description: |- + Filter to items ahead of this job ID in the queue, plus the job itself. + Matches job-level concurrency and reusable-workflow leases on the job's + ancestor paths. Mutually exclusive with `ahead_of_run`. + in: query + required: false + schema: + type: integer + minimum: 1 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group + description: |- + A concurrency group with the workflow runs and jobs that are either currently holding + or waiting for the concurrency group lease. + type: object + required: + - group_name + - group_url + - total_count + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: API URL for this concurrency group. + total_count: + type: integer + group_members: + type: array + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: + - string + - 'null' + format: uri + description: API URL for the workflow run. + run_html_url: + type: + - string + - 'null' + format: uri + description: Web URL for the workflow run. + job_id: + type: integer + description: The ID of the job, when the item represents + a job-level or reusable-workflow-level lease. + job_name: + type: string + description: The display name of the job, when the item + represents a job-level or reusable-workflow-level lease. + job_url: + type: + - string + - 'null' + format: uri + description: API URL for the job. + job_html_url: + type: + - string + - 'null' + format: uri + description: Web URL for the job. + status: + type: string + enum: + - in_progress + - pending + examples: + default: + value: + group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + total_count: 3 + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + - run_id: 30433643 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433643 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433643 + status: pending + - run_id: 30433644 + run_name: Deploy hotfix + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433644 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644 + job_id: 798245260 + job_name: deploy + job_url: https://api.github.com/repos/octocat/Hello-World/actions/jobs/798245260 + job_html_url: https://github.com/octocat/Hello-World/actions/runs/30433644/job/798245260 + status: pending + '404': *6 + '422': *15 + x-github: + githubCloudOnly: false + enabledForGitHubApps: true + category: actions + subcategory: concurrency-groups "/repos/{owner}/{repo}/actions/jobs/{job_id}": get: summary: Get a job for a workflow run @@ -71365,6 +74128,198 @@ paths: enabledForGitHubApps: true category: actions subcategory: workflow-runs + "/repos/{owner}/{repo}/actions/runs/{run_id}/concurrency_groups": + get: + summary: List concurrency groups for a workflow run + description: |- + Lists all concurrency groups associated with a workflow run or its jobs. + + The set of groups is derived from the run's configuration, so a group is + included even when the run no longer has any items currently holding or + waiting in it. In that case the `group_members` array will be empty. + `total_count` reflects the number of groups the run participates in by + configuration, not the number with active items. + + This differs from `GET /repos/{owner}/{repo}/actions/concurrency_groups/{group_name}`, + which returns 404 when a group has no active items. That endpoint reports + the live state of a group repo-wide, while this endpoint reports the + groups associated with a specific run by configuration. + + Results are sorted by group name and support cursor-based pagination via + `before` and `after`. The `after` cursor paginates forward only and does + not emit a `rel="prev"` Link; use `before` to page backward from a + forward page's `next` cursor. + + OAuth app tokens and personal access tokens (classic) need the `repo` scope to use this endpoint with a private repository. + tags: + - actions + operationId: actions/list-concurrency-groups-for-workflow-run + externalDocs: + description: API method documentation + url: https://docs.github.com/enterprise-cloud@latest/rest/actions/concurrency-groups#list-concurrency-groups-for-a-workflow-run + parameters: + - *465 + - *466 + - *489 + - *17 + - *108 + - *109 + responses: + '200': + description: Response + content: + application/json: + schema: + title: Concurrency Group Run List + description: A list of concurrency groups associated with a workflow + run. + type: object + required: + - total_count + - concurrency_groups + properties: + total_count: + type: integer + description: |- + The total number of concurrency groups this workflow run participates in, + derived from the run's configuration. This count is not filtered by + whether the run currently holds or is waiting in each group, so it can + include groups whose `group_members` array is empty (for example, when + the run has already released its lease in that group). + concurrency_groups: + type: array + items: + type: object + required: + - group_name + - group_url + - group_members + properties: + group_name: + type: string + description: The name of the concurrency group. + group_url: + type: string + format: uri + description: |- + API URL for this concurrency group. May return 404 if the group + has no active items at the time it is requested, since the + get-by-name endpoint reports the live repo-wide state of a group + while this endpoint lists groups associated with a run by + configuration. + group_members: + type: array + description: |- + Items belonging to this workflow run that are either currently holding or + waiting for the concurrency group lease. May be empty if the run no + longer has any active or queued items in this group. + items: + type: object + required: + - run_id + - run_name + - run_url + - run_html_url + - status + - position + - position_url + properties: + run_id: + type: integer + description: The ID of the workflow run. + run_name: + type: string + description: The name of the workflow run. + run_url: + type: + - string + - 'null' + format: uri + description: API URL for the workflow run. + run_html_url: + type: + - string + - 'null' + format: uri + description: Web URL for the workflow run. + position: + type: integer + description: Queue position. 0 means the item holds + the concurrency lease (in_progress), 1 or higher + means queued (pending). + position_url: + type: string + format: uri + description: API URL to get items ahead of this item + in the concurrency group. + job_id: + type: + - integer + - 'null' + description: The ID of the job, when the item represents + a job-level or reusable-workflow-level lease. + job_name: + type: + - string + - 'null' + description: The display name of the job, when the + item represents a job-level or reusable-workflow-level + lease. + job_url: + type: + - string + - 'null' + format: uri + description: API URL for the job. + job_html_url: + type: + - string + - 'null' + format: uri + description: Web URL for the job. + status: + type: string + enum: + - in_progress + - pending + examples: + default: + value: + total_count: 2 + concurrency_groups: + - group_name: deploy-prod + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-World/actions/runs/30433642 + status: in_progress + position: 0 + position_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/deploy-prod?ahead_of_run=30433642 + - group_name: ci-build + group_url: https://api.github.com/repos/octocat/Hello-World/actions/concurrency_groups/ci-build + group_members: + - run_id: 30433642 + run_name: Deploy to production + run_url: https://api.github.com/repos/octocat/Hello-World/actions/runs/30433642 + run_html_url: https://github.com/octocat/Hello-Wo{"code":"deadline_exceeded","msg":"operation timed out"}