REST API endpoints for Copilot custom agents - GitHub Enterprise Cloud Docs

Get custom agents for an enterprise

Gets the list of all custom agents defined in the /agents/*.md files in the .github-private repository for the enterprise.

If no source repository has been configured, returns null for custom_agents.

Enterprise owners with read access to AI Controls can use this endpoint.

OAuth app tokens and personal access tokens (classic) need the admin:enterprise scope to use this endpoint.

Fine-grained access tokens for "Get custom agents for an enterprise"

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

The fine-grained token must have the following permission set:

"Enterprise AI controls" enterprise permissions (read)

Parameters for "Get custom agents for an enterprise"

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

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.

Query parameters
Name, Type, Description
`per_page` integer The number of results per page (max 100). For more information, see "Using pagination in the REST API." Default: `30`
`page` integer The page number of the results to fetch. For more information, see "Using pagination in the REST API." Default: `1`

HTTP response status codes for "Get custom agents for an enterprise"

Status code	Description
`200`	Success
`401`	Requires authentication
`403`	Forbidden
`404`	Not found or source repository not found
`500`	Internal Error

Code samples for "Get custom agents for an enterprise"

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

Request examples

Select the example type

get/enterprises/{enterprise}/copilot/custom-agents

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/enterprises/ENTERPRISE/copilot/custom-agents

Response with custom agents

Status: 200

{
  "custom_agents": [
    {
      "name": "Security Reviewer",
      "file_path": "agents/security_reviewer.md",
      "url": "https://github.com/my-org/.github-private/blob/main/agents/security_reviewer.md"
    },
    {
      "name": "Code Documenter",
      "file_path": "agents/code_documenter.md",
      "url": "https://github.com/my-org/.github-private/blob/main/agents/code_documenter.md"
    }
  ]
}

Get the source organization for custom agents in an enterprise

Gets the organization and repository configured as the source for custom agent definitions in an enterprise.

Custom agents are enterprise-defined AI agents stored as markdown files in a special repository. An enterprise admin configures one organization as the "source" and that org must have a repo named .github-private containing agent definitions in /agents/*.md.

Enterprise owners with read access to AI Controls can use this endpoint.

OAuth app tokens and personal access tokens (classic) need the admin:enterprise scope to use this endpoint.

Fine-grained access tokens for "Get the source organization for custom agents in an enterprise"

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

The fine-grained token must have the following permission set:

"Enterprise AI controls" enterprise permissions (read)

Parameters for "Get the source organization for custom agents in an enterprise"

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

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.

HTTP response status codes for "Get the source organization for custom agents in an enterprise"

Status code	Description
`200`	OK
`403`	Forbidden
`404`	Resource not found

Code samples for "Get the source organization for custom agents in an enterprise"

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/enterprises/{enterprise}/copilot/custom-agents/source

curl -L \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/enterprises/ENTERPRISE/copilot/custom-agents/source

Response

Status: 200

{
  "organization": {
    "id": 1,
    "login": "octocat-org"
  },
  "repository": {
    "id": 123,
    "name": ".github-private",
    "full_name": "octocat-org/.github-private"
  }
}

Set the source organization for custom agents in an enterprise

Sets an organization as the source for custom agent definitions in the enterprise. The organization must have a .github-private repository containing agent definitions.

By default, this endpoint also creates an enterprise-level ruleset to protect agent definition files (agents/.md and .github/agents/.md). You can opt out of ruleset creation by setting create_ruleset to false.

Enterprise owners with write access to AI Controls can use this endpoint.

OAuth app tokens and personal access tokens (classic) need the admin:enterprise scope to use this endpoint.

Fine-grained access tokens for "Set the source organization for custom agents in an enterprise"

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

The fine-grained token must have the following permission set:

"Enterprise AI controls" enterprise permissions (write)

Parameters for "Set the source organization for custom agents in an enterprise"

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

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.

Body parameters
Name, Type, Description
`organization_id` integer Required The ID of the organization to use as the custom agents source.
`create_ruleset` boolean Whether to create a ruleset to protect agent definition files. Defaults to true. Default: `true`

HTTP response status codes for "Set the source organization for custom agents in an enterprise"

Status code	Description
`200`	Success
`401`	Requires authentication
`403`	Forbidden
`404`	Resource not found
`422`	Validation failed
`500`	Internal Error

Code samples for "Set the source organization for custom agents in an enterprise"

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

Request example

put/enterprises/{enterprise}/copilot/custom-agents/source

curl -L \
  -X PUT \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/enterprises/ENTERPRISE/copilot/custom-agents/source \
  -d '{"organization_id":123,"create_ruleset":false}'

Response without ruleset

Status: 200

{
  "organization": {
    "id": 123,
    "login": "my-org",
    "avatar_url": "https://avatars.githubusercontent.com/u/123"
  },
  "repository": {
    "id": 456,
    "name": ".github-private",
    "full_name": "my-org/.github-private"
  }
}

Delete the custom agents source for an enterprise

Removes the custom agents source configuration for the enterprise. This effectively disables custom agents for the enterprise by removing the reference to the source organization's .github-private repository.

Note: This does not delete the .github-private repository or any agent definition files. It only removes the association between the enterprise and the source repository.

Enterprise owners with write access to AI Controls can use this endpoint.

OAuth app tokens and personal access tokens (classic) need the admin:enterprise scope to use this endpoint.

Fine-grained access tokens for "Delete the custom agents source for an enterprise"

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

The fine-grained token must have the following permission set:

"Enterprise AI controls" enterprise permissions (write)

Parameters for "Delete the custom agents source for an enterprise"

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

Path parameters
Name, Type, Description
`enterprise` string Required The slug version of the enterprise name.

HTTP response status codes for "Delete the custom agents source for an enterprise"

Status code	Description
`204`	No Content - The custom agents source was successfully removed.
`403`	Forbidden - The user does not have enterprise admin access.
`404`	Not found - Enterprise not found, feature not enabled, or no custom agents source is configured.

Code samples for "Delete the custom agents source for an enterprise"

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/enterprises/{enterprise}/copilot/custom-agents/source

curl -L \
  -X DELETE \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: Bearer <YOUR-TOKEN>" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  https://api.github.com/enterprises/ENTERPRISE/copilot/custom-agents/source

No Content - The custom agents source was successfully removed.

Status: 204