REST API endpoints for agent automations

List automations for user

Returns automations whose created_by user is the authenticated caller, across repositories the caller can read. This includes both user-owned and repository-owned automations created by the caller but excludes repository-owned automations created by someone else even if the caller has write access to the repository.

Use the repository-scoped list operation for those automations. The owner_type filter only narrows this creator-scoped collection.

Fine-grained access tokens for "List automations for user"

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

The fine-grained token must have one of the following permission sets for each repository accessed by this request:

"Agent tasks" repository permissions (read)
"Contents" repository permissions (read)

The required permission set depends on each repository's Automation permission configuration.

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

Parameters for "List automations for user"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Query parameters
Name, Type, Description
`page` integer The page number of the results to fetch. Default: `1`
`per_page` integer The number of results per page (max 100). Default: `30`
`owner_type` string Filter automations by owner type. `user` returns automations owned by their creator, `repository` returns automations owned by the repository. Omit to return both. Can be one of: `user`, `repository`

HTTP response status codes for "List automations for user"

Status code	Description
`200`	Automations retrieved successfully
`400`	Bad request
`401`	Authentication required

Code samples for "List automations for user"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/agents/automations

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/agents/automations

Automations retrieved successfully

Status: 200

[
  {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "repository": {
      "id": 123456,
      "owner": "octo-org",
      "name": "octo-repo"
    },
    "name": "Issue triage",
    "enabled": true,
    "owner_type": "user",
    "write_scope": "trigger",
    "require_actor_write_permission": false,
    "triggers": {
      "issue_opened": {
        "query": "is:open"
      }
    },
    "model": "gpt-5.4",
    "reasoning_effort": "high",
    "created_at": "2026-05-01T12:00:00Z",
    "updated_at": "2026-05-03T14:30:00Z",
    "created_by": {
      "id": 123
    }
  }
]

List available automation tools

Returns the tools available to the authenticated caller for use when creating or updating an automation.

Fine-grained access tokens for "List available automation tools"

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

This endpoint does not require repository permissions.

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

HTTP response status codes for "List available automation tools"

Status code	Description
`200`	Available automation tools retrieved successfully
`401`	Authentication required

Code samples for "List available automation tools"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/agents/automations/available-tools

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/agents/automations/available-tools

Available automation tools retrieved successfully

Status: 200

[
  {
    "id": "issues",
    "title": "Issues",
    "tools": [
      {
        "id": "github/issue_read",
        "title": "Read issue",
        "description": "Fetch a single issue by its number, including its title, body, state, labels, assignees, and other metadata.",
        "scope": "read"
      }
    ]
  }
]

List available automation triggers

Returns the triggers available to the authenticated caller, including machine-readable schemas for their configurable fields.

Fine-grained access tokens for "List available automation triggers"

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

This endpoint does not require repository permissions.

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

HTTP response status codes for "List available automation triggers"

Status code	Description
`200`	Available automation triggers retrieved successfully
`401`	Authentication required

Code samples for "List available automation triggers"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/agents/automations/available-triggers

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/agents/automations/available-triggers

Available automation triggers retrieved successfully

Status: 200

[
  {
    "id": "issue_opened",
    "title": "Issue opened",
    "description": "Runs when an issue is opened.",
    "fields": [
      {
        "id": "query",
        "label": "Issue query",
        "required": false,
        "description": "Only run for issues matching this query, using [issue search syntax](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/filtering-and-searching-issues-and-pull-requests).",
        "schema": {
          "type": "string",
          "minLength": 1
        }
      },
      {
        "id": "write_scope",
        "label": "Write scope",
        "required": false,
        "description": "Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`.",
        "schema": {
          "type": "string",
          "enum": [
            "trigger",
            "repository"
          ]
        }
      }
    ]
  },
  {
    "id": "interval",
    "title": "Schedule",
    "description": "Runs on a schedule.",
    "fields": [
      {
        "id": "cadence",
        "label": "Cadence",
        "required": true,
        "schema": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "hourly",
              "daily",
              "weekly"
            ]
          },
          "minItems": 1,
          "uniqueItems": true
        }
      },
      {
        "id": "hour_utc",
        "label": "UTC hour",
        "required": false,
        "description": "UTC hour anchor (0 through 23) for daily and weekly schedules. Omitted daily and weekly values default to `0` (midnight UTC).",
        "schema": {
          "type": "integer",
          "minimum": 0,
          "maximum": 23
        }
      },
      {
        "id": "day_of_week",
        "label": "Day of week",
        "required": false,
        "description": "UTC weekday anchor for weekly schedules, where `0` is Sunday and `6` is Saturday. Omitted weekly values default to Monday (`1`).",
        "schema": {
          "type": "integer",
          "minimum": 0,
          "maximum": 6
        }
      },
      {
        "id": "minute_utc",
        "label": "UTC minute",
        "required": false,
        "description": "UTC minute anchor for daily and weekly schedules. Omitted daily and weekly values default to `0`. Must be omitted whenever `cadence` includes `hourly`.",
        "schema": {
          "type": "integer",
          "enum": [
            0,
            15,
            30,
            45
          ]
        }
      },
      {
        "id": "write_scope",
        "label": "Write scope",
        "required": false,
        "description": "Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`.",
        "schema": {
          "type": "string",
          "enum": [
            "trigger",
            "repository"
          ]
        }
      }
    ]
  },
  {
    "id": "pull_request_opened",
    "title": "Pull request opened",
    "description": "Runs when a pull request is opened.",
    "fields": [
      {
        "id": "query",
        "label": "Pull request query",
        "required": false,
        "description": "Only run for pull requests matching this query, using [issue search syntax](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/filtering-and-searching-issues-and-pull-requests).",
        "schema": {
          "type": "string",
          "minLength": 1
        }
      },
      {
        "id": "paths",
        "label": "Path filter",
        "required": false,
        "description": "Only run for pull requests where the changed files match one or more of these [gitignore-style path globs](https://git-scm.com/docs/gitignore#_pattern_format).",
        "schema": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          },
          "minItems": 1
        }
      },
      {
        "id": "write_scope",
        "label": "Write scope",
        "required": false,
        "description": "Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`.",
        "schema": {
          "type": "string",
          "enum": [
            "trigger",
            "repository"
          ]
        }
      }
    ]
  },
  {
    "id": "pull_request_review_submitted",
    "title": "Pull request review submitted",
    "description": "Runs when a pull request review is submitted.",
    "fields": [
      {
        "id": "query",
        "label": "Pull request query",
        "required": false,
        "description": "Only run for pull requests matching this query, using [issue search syntax](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/filtering-and-searching-issues-and-pull-requests).",
        "schema": {
          "type": "string",
          "minLength": 1
        }
      },
      {
        "id": "paths",
        "label": "Path filter",
        "required": false,
        "description": "Only run for pull requests where the changed files match one or more of these [gitignore-style path globs](https://git-scm.com/docs/gitignore#_pattern_format).",
        "schema": {
          "type": "array",
          "items": {
            "type": "string",
            "minLength": 1
          },
          "minItems": 1
        }
      },
      {
        "id": "states",
        "label": "Review state",
        "required": true,
        "description": "Only run for submitted reviews with one of these states.",
        "schema": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "approved",
              "changes_requested",
              "commented"
            ]
          },
          "minItems": 1,
          "maxItems": 3,
          "uniqueItems": true
        }
      },
      {
        "id": "write_scope",
        "label": "Write scope",
        "required": false,
        "description": "Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`.",
        "schema": {
          "type": "string",
          "enum": [
            "trigger",
            "repository"
          ]
        }
      }
    ]
  },
  {
    "id": "automation_completed",
    "title": "Automation completed",
    "description": "Runs when an upstream Automation completes successfully.",
    "fields": [
      {
        "id": "automation_ids",
        "label": "Upstream Automations",
        "required": true,
        "description": "Only run after one of these Automations completes successfully in this repository.",
        "schema": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "minItems": 1,
          "maxItems": 3,
          "uniqueItems": true
        }
      },
      {
        "id": "write_scope",
        "label": "Write scope",
        "required": false,
        "description": "Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`.",
        "schema": {
          "type": "string",
          "enum": [
            "trigger",
            "repository"
          ]
        }
      }
    ],
    "supports_run_now": false
  }
]

Get an automation by ID

Returns an automation by ID without requiring repository context when its created_by user is the authenticated caller and the caller can read its repository. This includes both user-owned and repository-owned automations created by the caller but excludes repository-owned automations created by someone else even if the caller has write access to the repository.

Use the repository-scoped get operation for those automations. The response includes repository identity so clients can link back to the repository.

Fine-grained access tokens for "Get an automation by ID"

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

The fine-grained token must have one of the following permission sets for each repository accessed by this request:

"Agent tasks" repository permissions (read)
"Contents" repository permissions (read)

The required permission set depends on each repository's Automation permission configuration.

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

Parameters for "Get an automation by ID"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`automation_id` string Required The unique identifier of the automation.

HTTP response status codes for "Get an automation by ID"

Status code	Description
`200`	Automation retrieved successfully
`400`	Bad request
`401`	Authentication required
`404`	Resource not found

Code samples for "Get an automation by ID"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/agents/automations/{automation_id}

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/agents/automations/AUTOMATION_ID

Automation retrieved successfully

Status: 200

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "repository": {
    "id": 123456,
    "owner": "octo-org",
    "name": "octo-repo"
  },
  "name": "Issue triage",
  "enabled": true,
  "owner_type": "user",
  "write_scope": "trigger",
  "require_actor_write_permission": false,
  "triggers": {
    "issue_opened": {
      "query": "label:auto-triage"
    }
  },
  "prompt": "When a new issue is opened, inspect it and suggest labels, priority, and next steps.",
  "tools": [
    "github/get_file_contents",
    "github/issue_read",
    "github/search_issues"
  ],
  "model": "gpt-5.4",
  "reasoning_effort": "high",
  "created_at": "2026-05-01T12:00:00Z",
  "updated_at": "2026-05-03T14:30:00Z",
  "created_by": {
    "id": 123
  }
}

List tasks for an automation

Returns a list of tasks triggered by the specified automation.

User-owned automation history is available only to its creator, while repository-owned automation history is available to anyone with read access to the repository. Deleted and unlisted tasks are excluded. Tasks produced by private-session agents are excluded unless the caller created the task, is a task collaborator, or the task is shared.

Fine-grained access tokens for "List tasks for an automation"

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

The fine-grained token must have one of the following permission sets for each repository accessed by this request:

"Agent tasks" repository permissions (read)
"Contents" repository permissions (read)

The required permission set depends on each repository's Automation permission configuration.

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

Parameters for "List tasks for an automation"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`automation_id` string Required The unique identifier of the automation.

Query parameters
Name, Type, Description
`per_page` integer The number of results per page (max 100). Default: `30`
`page` integer The page number of the results to fetch. Default: `1`
`sort` string The field to sort results by. Can be `updated_at` or `created_at`. Default: `updated_at` Can be one of: `updated_at`, `created_at`
`direction` string The direction to sort results. Can be `asc` or `desc`. Default: `desc` Can be one of: `asc`, `desc`
`state` string 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`.
`is_archived` boolean Filter by archived status. When `true`, returns only archived tasks. When `false` or omitted, returns only non-archived tasks. Defaults to `false`. Default: `false`

HTTP response status codes for "List tasks for an automation"

Status code	Description
`200`	Tasks retrieved successfully
`401`	Authentication required
`404`	Not found
`422`	Validation Failed

Code samples for "List tasks for an automation"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/agents/automations/{automation_id}/tasks

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/agents/automations/AUTOMATION_ID/tasks

Tasks retrieved successfully

Status: 200

{
  "tasks": [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "name": "Triage issue #42",
      "creator": {
        "id": 123
      },
      "creator_type": "user",
      "repository": {
        "id": 1296269
      },
      "state": "completed",
      "session_count": 1,
      "artifacts": [],
      "archived_at": null,
      "created_at": "2026-05-02T12:00:00Z",
      "updated_at": "2026-05-02T12:05:00Z"
    }
  ]
}

List automations for a repository

Returns a paginated list of the authenticated user's automations for a repository, together with every repository-owned automation in it. total_count is the number of caller-visible automations matching the supplied filters across all pages. Repository-owned automations are visible to anyone with read access to the repository, so the results are not limited to automations the caller created. Use the owner_type field on each automation to tell the two apart.

Fine-grained access tokens for "List automations for a repository"

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

The fine-grained token must have one of the following permission sets for each repository accessed by this request:

"Agent tasks" repository permissions (read)
"Contents" repository permissions (read)

The required permission set depends on each repository's Automation permission configuration.

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

Parameters for "List automations for a repository"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`owner` string Required The account owner of the repository. The name is not case sensitive.
`repo` string Required The name of the repository. The name is not case sensitive.

Query parameters
Name, Type, Description
`page` integer The page number of the results to fetch. Default: `1`
`per_page` integer The number of results per page (max 100). Default: `30`
`owner_type` string Filter automations by owner type. `user` returns automations owned by their creator, `repository` returns automations owned by the repository. Omit to return both. Can be one of: `user`, `repository`

HTTP response status codes for "List automations for a repository"

Status code	Description
`200`	Automations retrieved successfully
`400`	Bad request
`401`	Authentication required
`404`	Resource not found

Code samples for "List automations for a repository"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/agents/repos/{owner}/{repo}/automations

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/agents/repos/OWNER/REPO/automations

Automations retrieved successfully

Status: 200

{
  "automations": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Issue triage",
      "enabled": true,
      "owner_type": "user",
      "require_actor_write_permission": false,
      "triggers": {
        "issue_opened": {
          "query": "is:open"
        }
      },
      "model": "gpt-5.4",
      "reasoning_effort": "high",
      "created_at": "2026-05-01T12:00:00Z",
      "updated_at": "2026-05-03T14:30:00Z",
      "created_by": {
        "id": 123
      }
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "name": "Nightly dependency sweep",
      "enabled": true,
      "owner_type": "repository",
      "require_actor_write_permission": false,
      "triggers": {
        "interval": {
          "cadence": [
            "daily"
          ],
          "hour_utc": 3
        }
      },
      "created_at": "2026-05-02T09:00:00Z",
      "updated_at": "2026-05-04T11:15:00Z",
      "created_by": {
        "id": 456
      }
    }
  ],
  "total_count": 3
}

Create an automation for a repository

Creates a new automation in a repository. User-owned automations remain private to their creator. Repository-owned automations are visible to anyone with read access to the repository and manageable by anyone with write access to the repository.

Fine-grained access tokens for "Create an automation for a repository"

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

The fine-grained token must have one of the following permission sets for each repository accessed by this request:

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

The required permission set depends on each repository's Automation permission configuration.

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

Parameters for "Create an automation for a repository"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`owner` string Required The account owner of the repository. The name is not case sensitive.
`repo` string Required The name of the repository. The name is not case sensitive.

Name, Type, Description

name string Required

The name of the automation.

triggers object

Public trigger configuration keyed by stable public trigger identifier. Each trigger has a closed, trigger-specific configuration schema.

Properties of triggers

Name, Type, Description

interval object

Properties of interval

Name, Type, Description
`cadence` array of strings Required One or more schedules on which the Automation runs. Supported values are: `hourly`, `daily`, `weekly`
`hour_utc` integer UTC hour anchor (0 through 23) for daily and weekly schedules. Omitted daily and weekly values default to `0` (midnight UTC).
`day_of_week` integer UTC weekday anchor for weekly schedules, where `0` is Sunday and `6` is Saturday. Omitted weekly values default to Monday (`1`).
`minute_utc` integer UTC minute anchor for daily and weekly schedules. Omitted daily and weekly values default to `0`. Must be omitted whenever `cadence` includes `hourly`. Default: `0` Can be one of: `0`, `15`, `30`, `45`
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

issue_opened object

Properties of issue_opened

Name, Type, Description
`query` string A GitHub issue or pull request search query.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

issue_labeled object

Properties of issue_labeled

Name, Type, Description
`query` string A GitHub issue or pull request search query.
`labels` array of strings Label names matched case-insensitively against the label added by the event. Omit or use an empty array to match every added label.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

workflow_run object

Properties of workflow_run

Name, Type, Description
`workflows` array of strings Required Workflow names matched against the name in each workflow YAML file.
`conclusions` array of strings Required Workflow conclusions to match. The current trigger supports failure. Supported values are: `failure`
`query` string A GitHub issue or pull request search query.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

pull_request_opened object

Properties of pull_request_opened

Name, Type, Description
`query` string A GitHub issue or pull request search query.
`paths` array of strings Gitignore-style changed-file path globs.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

pull_request_synchronize object

Properties of pull_request_synchronize

Name, Type, Description
`query` string A GitHub issue or pull request search query.
`paths` array of strings Gitignore-style changed-file path globs.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

pull_request_merged object

Properties of pull_request_merged

Name, Type, Description
`query` string A GitHub issue or pull request search query.
`paths` array of strings Gitignore-style changed-file path globs.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

issue_comment object

Properties of issue_comment

Name, Type, Description
`body_substring` string A case-insensitive substring matched against the event body.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

pull_request_comment object

Properties of pull_request_comment

Name, Type, Description
`comment_types` array of strings Required Pull request conversation and inline review comment types to match. Supported values are: `timeline_comment`, `review_comment`
`body_substring` string A case-insensitive substring matched against the event body.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

discussion_opened object

Properties of discussion_opened

Name, Type, Description
`categories` array of strings Discussion category names matched case-insensitively.
`body_substring` string A case-insensitive substring matched against the event body.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

discussion_updated object

Properties of discussion_updated

Name, Type, Description
`categories` array of strings Discussion category names matched case-insensitively.
`body_substring` string A case-insensitive substring matched against the event body.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

discussion_comment object

Properties of discussion_comment

Name, Type, Description
`comment_types` array of strings Top-level discussion comments and replies to match. Omit to match both. Supported values are: `comment`, `reply`
`categories` array of strings Discussion category names matched case-insensitively.
`body_substring` string A case-insensitive substring matched against the event body.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

issue_assigned object

Properties of issue_assigned

Name, Type, Description
`query` string A GitHub issue or pull request search query.
`assignees` array of strings Affected assignee logins matched case-insensitively.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

pull_request_assigned object

Properties of pull_request_assigned

Name, Type, Description
`query` string A GitHub issue or pull request search query.
`paths` array of strings Gitignore-style changed-file path globs.
`assignees` array of strings Affected assignee logins matched case-insensitively.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

sub_issue_added object

Properties of sub_issue_added

Name, Type, Description
`query` string A GitHub issue or pull request search query.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

pull_request_ready_for_review object

Properties of pull_request_ready_for_review

Name, Type, Description
`query` string A GitHub issue or pull request search query.
`paths` array of strings Gitignore-style changed-file path globs.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

pull_request_labeled object

Properties of pull_request_labeled

Name, Type, Description
`query` string A GitHub issue or pull request search query.
`paths` array of strings Gitignore-style changed-file path globs.
`labels` array of strings Label names matched case-insensitively against the label added by the event. Omit or use an empty array to match every added label.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

pull_request_merge_conflict object

Properties of pull_request_merge_conflict

Name, Type, Description
`query` string A GitHub issue or pull request search query.
`paths` array of strings Gitignore-style changed-file path globs.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

pull_request_review_submitted object

Properties of pull_request_review_submitted

Name, Type, Description
`query` string A GitHub issue or pull request search query.
`paths` array of strings Gitignore-style changed-file path globs.
`states` array of strings Required Submitted review states to match. Supported values are: `approved`, `changes_requested`, `commented`
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

pull_request_review_requested object

Properties of pull_request_review_requested

Name, Type, Description
`query` string A GitHub issue or pull request search query.
`paths` array of strings Gitignore-style changed-file path globs.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

automation_completed object

Properties of automation_completed

Name, Type, Description
`automation_ids` array of strings Required Upstream Automation IDs in the same repository.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

prompt string Required

The prompt template for the automation.

model string

The model to use for sessions triggered by this automation. Omit to use the platform default.

reasoning_effort string

The reasoning effort to use for sessions triggered by this automation. Omit or leave empty for no override. Currently supported values: none, low, medium, high, xhigh, max

tools array of strings

The tools available to the automation.

allowed_custom_agents array of strings

Custom agents (subagents) this automation is allowed to invoke.

enabled boolean

Whether the automation should be created enabled. Defaults to true when omitted.

Default: true

owner_type string

Who owns the automation, fixed at creation. user keeps it private to its creator and its runs act as that user. repository makes it belong to the repository, visible to anyone with read access to the repository and maintainable by anyone with write access to the repository, and its runs act as the Copilot app rather than as a person. repository is rejected when repository ownership is not available for the repository. Supported values: user, repository. Defaults to user.

Default: user

Can be one of: user, repository

write_scope string

Controls which repository resources a run may modify. trigger limits writes to the resource that started the run, when one exists, and resources created during the run; repository allows writes to any resource in the repository. Supported values: trigger, repository.

Default: trigger

Can be one of: trigger, repository

require_actor_write_permission boolean

When true, event-triggered runs require the event actor to have repo write permission, even when the org's allow_read_access_triggers policy is enabled. Does not apply to interval-scheduled runs, which always run as the automation owner. Defaults to false.

HTTP response status codes for "Create an automation for a repository"

Status code	Description
`201`	Automation created successfully
`400`	Bad request
`401`	Authentication required
`403`	Insufficient permissions
`404`	Resource not found
`422`	Validation Failed

Code samples for "Create an automation for a repository"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

post/agents/repos/{owner}/{repo}/automations

curl -L \
  -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/agents/repos/OWNER/REPO/automations \
  -d '{"name":"Issue triage","enabled":true,"owner_type":"user","triggers":{"issue_opened":{"query":"is:open"}},"prompt":"Inspect the new issue and suggest labels, priority, and next steps.","tools":["github/get_file_contents","github/issue_read"],"model":"gpt-5.4","reasoning_effort":"high"}'

Automation created successfully

Status: 201

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Issue triage",
  "enabled": true,
  "owner_type": "user",
  "write_scope": "trigger",
  "require_actor_write_permission": false,
  "triggers": {
    "issue_opened": {
      "query": "is:open"
    }
  },
  "prompt": "Inspect the new issue and suggest labels, priority, and next steps.",
  "tools": [
    "github/get_file_contents",
    "github/issue_read"
  ],
  "model": "gpt-5.4",
  "reasoning_effort": "high",
  "created_at": "2026-05-01T12:00:00Z",
  "updated_at": "2026-05-01T12:00:00Z",
  "created_by": {
    "id": 123
  }
}

Get an automation for a repository

Returns an automation by ID in a repository.

User-owned automations are visible only to their creator. Repository-owned automations are visible to anyone with read access to the repository. The created_by field identifies the creator and is distinct from the automation's owner_type.

Fine-grained access tokens for "Get an automation for a repository"

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

The fine-grained token must have one of the following permission sets for each repository accessed by this request:

"Agent tasks" repository permissions (read)
"Contents" repository permissions (read)

The required permission set depends on each repository's Automation permission configuration.

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

Parameters for "Get an automation for a repository"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`owner` string Required The account owner of the repository. The name is not case sensitive.
`repo` string Required The name of the repository. The name is not case sensitive.
`automation_id` string Required The unique identifier of the automation.

HTTP response status codes for "Get an automation for a repository"

Status code	Description
`200`	Automation retrieved successfully
`400`	Bad request
`401`	Authentication required
`404`	Resource not found

Code samples for "Get an automation for a repository"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

get/agents/repos/{owner}/{repo}/automations/{automation_id}

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/agents/repos/OWNER/REPO/automations/AUTOMATION_ID

Automation retrieved successfully

Status: 200

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Issue triage",
  "enabled": true,
  "owner_type": "repository",
  "write_scope": "trigger",
  "require_actor_write_permission": false,
  "triggers": {
    "issue_opened": {
      "query": "is:open"
    }
  },
  "prompt": "Inspect the new issue and suggest labels, priority, and next steps.",
  "model": "gpt-5.4",
  "reasoning_effort": "high",
  "created_at": "2026-05-01T12:00:00Z",
  "updated_at": "2026-05-03T14:30:00Z",
  "created_by": {
    "id": 123
  }
}

Edit an automation for a repository

Edits specified fields on an existing automation in a repository. Omitted fields are left unchanged. The automation's owner_type is immutable and cannot be changed by this operation.

Fine-grained access tokens for "Edit an automation for a repository"

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

The fine-grained token must have one of the following permission sets for each repository accessed by this request:

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

The required permission set depends on each repository's Automation permission configuration.

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

Parameters for "Edit an automation for a repository"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`owner` string Required The account owner of the repository. The name is not case sensitive.
`repo` string Required The name of the repository. The name is not case sensitive.
`automation_id` string Required The unique identifier of the automation.

Name, Type, Description

name string

The name of the automation.

enabled boolean

Set to true to enable, false to disable. Omit to leave unchanged.

write_scope string

Controls which repository resources a run may modify. trigger limits writes to the resource that started the run, when one exists, and resources created during the run; repository allows writes to any resource in the repository. Supported values: trigger, repository. Omit to leave unchanged.

Can be one of: trigger, repository

require_actor_write_permission boolean

When true, event-triggered runs require the event actor to have repo write permission, even when the org's allow_read_access_triggers policy is enabled. Does not apply to interval-scheduled runs, which always run as the automation owner. Omit to leave unchanged.

model string

The model to use for sessions triggered by this automation. Omit to leave unchanged. Send an empty string to clear the model and revert to the platform default.

reasoning_effort string

The reasoning effort to use for sessions triggered by this automation. Omit to leave unchanged. Send an empty string to clear the override. Currently supported values: none, low, medium, high, xhigh, max

triggers object

Public trigger configuration keyed by stable public trigger identifier. Each trigger has a closed, trigger-specific configuration schema.

Properties of triggers

Name, Type, Description

interval object

Properties of interval

Name, Type, Description
`cadence` array of strings Required One or more schedules on which the Automation runs. Supported values are: `hourly`, `daily`, `weekly`
`hour_utc` integer UTC hour anchor (0 through 23) for daily and weekly schedules. Omitted daily and weekly values default to `0` (midnight UTC).
`day_of_week` integer UTC weekday anchor for weekly schedules, where `0` is Sunday and `6` is Saturday. Omitted weekly values default to Monday (`1`).
`minute_utc` integer UTC minute anchor for daily and weekly schedules. Omitted daily and weekly values default to `0`. Must be omitted whenever `cadence` includes `hourly`. Default: `0` Can be one of: `0`, `15`, `30`, `45`
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

issue_opened object

Properties of issue_opened

Name, Type, Description
`query` string A GitHub issue or pull request search query.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

issue_labeled object

Properties of issue_labeled

Name, Type, Description
`query` string A GitHub issue or pull request search query.
`labels` array of strings Label names matched case-insensitively against the label added by the event. Omit or use an empty array to match every added label.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

workflow_run object

Properties of workflow_run

Name, Type, Description
`workflows` array of strings Required Workflow names matched against the name in each workflow YAML file.
`conclusions` array of strings Required Workflow conclusions to match. The current trigger supports failure. Supported values are: `failure`
`query` string A GitHub issue or pull request search query.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

pull_request_opened object

Properties of pull_request_opened

Name, Type, Description
`query` string A GitHub issue or pull request search query.
`paths` array of strings Gitignore-style changed-file path globs.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

pull_request_synchronize object

Properties of pull_request_synchronize

Name, Type, Description
`query` string A GitHub issue or pull request search query.
`paths` array of strings Gitignore-style changed-file path globs.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

pull_request_merged object

Properties of pull_request_merged

Name, Type, Description
`query` string A GitHub issue or pull request search query.
`paths` array of strings Gitignore-style changed-file path globs.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

issue_comment object

Properties of issue_comment

Name, Type, Description
`body_substring` string A case-insensitive substring matched against the event body.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

pull_request_comment object

Properties of pull_request_comment

Name, Type, Description
`comment_types` array of strings Required Pull request conversation and inline review comment types to match. Supported values are: `timeline_comment`, `review_comment`
`body_substring` string A case-insensitive substring matched against the event body.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

discussion_opened object

Properties of discussion_opened

Name, Type, Description
`categories` array of strings Discussion category names matched case-insensitively.
`body_substring` string A case-insensitive substring matched against the event body.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

discussion_updated object

Properties of discussion_updated

Name, Type, Description
`categories` array of strings Discussion category names matched case-insensitively.
`body_substring` string A case-insensitive substring matched against the event body.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

discussion_comment object

Properties of discussion_comment

Name, Type, Description
`comment_types` array of strings Top-level discussion comments and replies to match. Omit to match both. Supported values are: `comment`, `reply`
`categories` array of strings Discussion category names matched case-insensitively.
`body_substring` string A case-insensitive substring matched against the event body.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

issue_assigned object

Properties of issue_assigned

Name, Type, Description
`query` string A GitHub issue or pull request search query.
`assignees` array of strings Affected assignee logins matched case-insensitively.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

pull_request_assigned object

Properties of pull_request_assigned

Name, Type, Description
`query` string A GitHub issue or pull request search query.
`paths` array of strings Gitignore-style changed-file path globs.
`assignees` array of strings Affected assignee logins matched case-insensitively.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

sub_issue_added object

Properties of sub_issue_added

Name, Type, Description
`query` string A GitHub issue or pull request search query.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

pull_request_ready_for_review object

Properties of pull_request_ready_for_review

Name, Type, Description
`query` string A GitHub issue or pull request search query.
`paths` array of strings Gitignore-style changed-file path globs.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

pull_request_labeled object

Properties of pull_request_labeled

Name, Type, Description
`query` string A GitHub issue or pull request search query.
`paths` array of strings Gitignore-style changed-file path globs.
`labels` array of strings Label names matched case-insensitively against the label added by the event. Omit or use an empty array to match every added label.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

pull_request_merge_conflict object

Properties of pull_request_merge_conflict

Name, Type, Description
`query` string A GitHub issue or pull request search query.
`paths` array of strings Gitignore-style changed-file path globs.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

pull_request_review_submitted object

Properties of pull_request_review_submitted

Name, Type, Description
`query` string A GitHub issue or pull request search query.
`paths` array of strings Gitignore-style changed-file path globs.
`states` array of strings Required Submitted review states to match. Supported values are: `approved`, `changes_requested`, `commented`
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

pull_request_review_requested object

Properties of pull_request_review_requested

Name, Type, Description
`query` string A GitHub issue or pull request search query.
`paths` array of strings Gitignore-style changed-file path globs.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

automation_completed object

Properties of automation_completed

Name, Type, Description
`automation_ids` array of strings Required Upstream Automation IDs in the same repository.
`write_scope` string Override the Automation `write_scope` for runs started by this trigger. If omitted, the automation's `write_scope` is used. Organization or repository policy may restrict the effective scope to `trigger`. Can be one of: `trigger`, `repository`

prompt string

The prompt template for the automation.

tools array of strings

The tools available to the automation. Send an empty array to clear all tools.

allowed_custom_agents array of strings

Custom agents (subagents) this automation is allowed to invoke. Send an empty array to clear all custom agents.

HTTP response status codes for "Edit an automation for a repository"

Status code	Description
`200`	Automation updated successfully
`400`	Bad request
`401`	Authentication required
`404`	Resource not found
`422`	Validation Failed

Code samples for "Edit an automation for a repository"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

patch/agents/repos/{owner}/{repo}/automations/{automation_id}

curl -L \
  -X PATCH \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/agents/repos/OWNER/REPO/automations/AUTOMATION_ID \
  -d '{"name":"Issue triage and prioritization","enabled":true,"model":"gpt-5.4","reasoning_effort":"high","triggers":{"issue_opened":{"query":"is:open label:auto-triage"}}}'

Automation updated successfully

Status: 200

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Issue triage and prioritization",
  "enabled": true,
  "owner_type": "user",
  "write_scope": "trigger",
  "require_actor_write_permission": false,
  "triggers": {
    "issue_opened": {
      "query": "is:open label:auto-triage"
    }
  },
  "prompt": "Inspect the new issue and suggest labels, priority, and next steps.",
  "model": "gpt-5.4",
  "reasoning_effort": "high",
  "created_at": "2026-05-01T12:00:00Z",
  "updated_at": "2026-05-03T14:30:00Z",
  "created_by": {
    "id": 123
  }
}

Delete an automation for a repository

Deletes an automation in a repository.

Fine-grained access tokens for "Delete an automation for a repository"

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

The fine-grained token must have one of the following permission sets for each repository accessed by this request:

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

The required permission set depends on each repository's Automation permission configuration.

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

Parameters for "Delete an automation for a repository"

Headers
Name, Type, Description
`accept` string Setting to `application/vnd.github+json` is recommended.

Path parameters
Name, Type, Description
`owner` string Required The account owner of the repository. The name is not case sensitive.
`repo` string Required The name of the repository. The name is not case sensitive.
`automation_id` string Required The unique identifier of the automation.

HTTP response status codes for "Delete an automation for a repository"

Status code	Description
`204`	Automation deleted successfully
`400`	Bad request
`401`	Authentication required
`404`	Resource not found

Code samples for "Delete an automation for a repository"

If you access GitHub at GHE.com, replace api.github.com with your enterprise's dedicated subdomain at api.SUBDOMAIN.ghe.com.

Request example

delete/agents/repos/{owner}/{repo}/automations/{automation_id}

curl -L \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2026-03-10" \
  https://api.github.com/agents/repos/OWNER/REPO/automations/AUTOMATION_ID

Automation deleted successfully

Status: 204