---
title: "Create a bouncer"
method: POST
path: "/organizations/{organization}/databases/{database}/branches/{branch}/bouncers"
tags: ["Bouncers"]
---

# Create a bouncer

`POST /organizations/{organization}/databases/{database}/branches/{branch}/bouncers`

### Authorization
A service token or OAuth token must have at least one of the following access or scopes in order to use this API endpoint:

**Service Token Accesses**
 `write_database`

**OAuth Scopes**

 | Resource | Scopes |
| :------- | :---------- |
| Organization | `write_databases` |
| Database | `write_database` |

## Path parameters

- `organization` string, required
- `database` string, required
- `branch` string, required

## Request body

- object
  - `name` string — The bouncer name
  - `target` string — The type of server the bouncer targets
  - `bouncer_size` string — The size SKU for the bouncer
  - `replicas_per_cell` integer — The number of replica servers per cell

## Response `200`

Returns the new bouncer

- object
  - `id` string, required — The ID of the bouncer
  - `name` string, required — The name of the bouncer
  - `sku` object, required
    - `name` string, required — The name of the Postgres bouncer SKU
    - `display_name` string, required — The display name
    - `cpu` string, required — The CPU allocation
    - `ram` integer, required — The amount of memory in bytes
    - `sort_order` integer, required — The sort order of the Postgres bouncer SKU
  - `target` 'primary' | 'replica' | 'replica_az_affinity', required — The instance type the bouncer targets
  - `replicas_per_cell` integer, required — The count of replicas in each cell
  - `created_at` string, required — When the bouncer was created
  - `updated_at` string, required — When the bouncer was updated
  - `deleted_at` string, nullable, required — When the bouncer was deleted
  - `actor` object, required
    - `id` string, required — The ID of the actor
    - `display_name` string, required — The name of the actor
    - `avatar_url` string, required — The URL of the actor's avatar
  - `branch` object, required
    - `id` string, required — The ID for the resource
    - `name` string, required — The name for the resource
    - `created_at` string, required — When the resource was created
    - `updated_at` string, required — When the resource was last updated
    - `deleted_at` string, nullable, required — When the resource was deleted, if deleted
  - `parameters` object[], required
    - `id` string, required — The ID of the parameter
    - `namespace` 'pgbouncer', required — The namespace of the parameter
    - `name` string, required — The name of the parameter
    - `display_name` string, required — The display name of the parameter
    - `category` string, required — The category of the parameter
    - `description` string, required — The description of the parameter
    - `immutable` boolean, required — Whether the parameter can be changed
    - `parameter_type` 'array' | 'integer' | 'seconds' | 'select' | 'string', required — The type of the parameter
    - `default_value` string, required — The default value of the parameter
    - `value` string, required — The configured value of the parameter
    - `required` boolean, required — Whether the parameter is required
    - `created_at` string, required — When the parameter was created
    - `updated_at` string, required — When the parameter was last updated
    - `restart` boolean, required — True if processes require a server restart on change
    - `max` number, required — The maximum value of the parameter
    - `min` number, required — The minimum value of the parameter
    - `url` string, required — The URL of the parameter
    - `options` string[], required — Valid options for the parameter value
    - `actor` object, required
      - `id` string, required — The ID of the actor
      - `display_name` string, required — The name of the actor
      - `avatar_url` string, required — The URL of the actor's avatar

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `500` — Internal Server Error

## Changes

- **2026-08-18** `249942995489` — 1 breaking
  - removed the required property `parameters/items/step` from the response with the `200` status
- **2026-06-01** `72506953f367` — 2 breaking
  - the response property `branch/deleted_at` became nullable for the status `200`
  - the response property `deleted_at` became nullable for the status `200`
- **2026-02-24** `3c33e46f8ff2` — 1 warning, 2 info
  - added the new `string` enum value to the `parameters/items/parameter_type` response property for the response status `200`
  - removed the `internal` enum value from the `parameters/items/parameter_type` response property for the response status `200`
  - added the required property `parameters/items/immutable` to the response with the `200` status
- **2026-02-10** `ed1825db11c6` — 5 info
  - removed the `boolean` enum value from the `parameters/items/parameter_type` response property for the response status `200`
  - removed the `bytes` enum value from the `parameters/items/parameter_type` response property for the response status `200`
  - removed the `float` enum value from the `parameters/items/parameter_type` response property for the response status `200`
  - removed the `string` enum value from the `parameters/items/parameter_type` response property for the response status `200`
  - …1 more
- **2025-12-09** `d710019068fb` — 1 breaking
  - the `replicas_per_cell` request property type/format changed from `number`/`` to `integer`/``

[Full history](https://skmtc.dev/planetscale/apis/planetscale-api/changes/organizations/:organization/databases/:database/branches/:branch/bouncers/post.md)

---

[API](https://skmtc.dev/planetscale/apis/planetscale-api.md) · [All operations](https://skmtc.dev/planetscale/apis/planetscale-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/planetscale/planetscale-api/revisions/6d28c038c4fd/schema)