---
title: "Create or update an Agent Pool."
method: PUT
path: "/api/test-distribution/agent-pools/{poolId}"
tags: ["TestDistribution", "GradleEnterprise", "Develocity"]
---

# Create or update an Agent Pool.

`PUT /api/test-distribution/agent-pools/{poolId}`

## Request

- Base URL: `https://develocity.example.com`
- URL: `https://develocity.example.com/api/test-distribution/agent-pools/{poolId}`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/develocity/apis/develocity-api/docs/api/test-distribution/agent-pools/:poolId/put.ts> (a function with typed inputs; its response is checked against the schema)

Create a new Agent Pool in Develocity or update the configuration of an existing one.
The orderIndex element is optional and can be used to specify the priority order in which the Agent Pool is considered.
When not specified, the Agent Pool will be either added last on creation, or will not change position on update.
When specified, the Agent Pool will be added at/moved to the specified index and all other Agent Pools will be moved down.
If the specified index is out of bounds, the Agent Pool will be added last with the orderIndex adjusted accordingly.

## Request body

- TestDistributionAgentPoolConfiguration: An agent pool configuration.
  - `name` string, required: The alias or display name of the agent pool.
  - `minimumSize` integer, required
  - `maximumSize` integer, required
  - `orderIndex` integer, nullable: The order in which the agent pool is considered for allocation. Lower values are considered first.
  - `capabilities` string[], required
  - `restrictAccessToProjectGroups` boolean: Controls whether this pool can be used by everyone, or only the assigned project groups. A `true` value implies that `projectGroupIds` is present and has at least one entry. Conversely, a `false` value implies that `projectGroupIds` is empty.
  - `projectGroupIds` string[]: Controls which project groups can use this pool. If it is empty, then `restrictAccessToProjectGroups` must be `false`. Conversely, if it has values then `restrictAccessToProjectGroups` must be `true`.

## Response `200`

The Agent Pool was created or its configuration was updated successfully.

- TestDistributionAgentPoolConfigurationWithId: An agent pool configuration.
  - `id` string, required: The unique identifier of the agent pool.
  - `name` string, required: The alias or display name of the agent pool.
  - `minimumSize` integer, required
  - `maximumSize` integer, required
  - `orderIndex` integer, required: The order in which the agent pool is considered for allocation. Lower values are considered first.
  - `capabilities` string[], required
  - `restrictAccessToProjectGroups` boolean: Controls whether this pool can be used by everyone, or only the assigned project groups. A `true` value implies that `projectGroupIds` is present and has at least one entry. Conversely, a `false` value implies that `projectGroupIds` is empty.
  - `projectGroupIds` string[]: Controls which project groups can use this pool. If it is empty, then `restrictAccessToProjectGroups` must be `false`. Conversely, if it has values then `restrictAccessToProjectGroups` must be `true`.

## Other responses

- `400`: The request body is malformed or contains invalid values for at least one of the properties.
- `403`: The authenticated user has insufficient permissions.
- `404`: No API key was specified in the request, the key has been revoked, or the user bearing the key lacks permissions for this operation.

---

[API](https://skmtc.dev/develocity/apis/develocity-api.md) - [All operations](https://skmtc.dev/develocity/apis/develocity-api/llms.txt) - [OpenAPI document](https://skmtc.dev/develocity/apis/develocity-api/revisions/b49835fbf065?raw)