> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dbhost.app/llms.txt
> Use this file to discover all available pages before exploring further.

# IP allowlist API: list, add and remove CIDRs

> Manage which client networks can connect to a DBHost database through PgBouncer. An empty allowlist accepts connections from any IP.

The IP allowlist controls which client networks can connect to a database
through PgBouncer on port `6432`. It does not affect dashboard or API access.

* An empty allowlist accepts connections from any IP address.
* As soon as the list has one or more entries, only matching networks can
  connect.
* Removing the last entry opens the database to any IP again.

Selected-database keys can use these routes for databases they are assigned
to; full-account keys for any database you own. API access requires a Pro or
Business plan.

## List entries

`GET /api/v1/databases/{id}/network/allowlist`

```http theme={null}
GET /api/v1/databases/{id}/network/allowlist
Authorization: Bearer <api-key>
```

```json 200 OK theme={null}
{
  "data": [
    {
      "id": "3f2b8c1e-9a4d-4b7e-8f21-6c0d5e7a9b10",
      "cidr": "198.51.100.0/24",
      "label": "Office",
      "createdAt": "2026-10-14T09:00:00.000Z"
    }
  ]
}
```

## Add an entry

`POST /api/v1/databases/{id}/network/allowlist`

| Field | Type | Required | Description |
| - | - | - | - |
| `cidr` | string | Yes | IPv4 or IPv6 block in `address/prefix` form, for example `198.51.100.0/24` or `2001:db8::/48`. Use `/32` (IPv4) or `/128` (IPv6) for a single address. |
| `label` | string | No | Note for the entry, at most 120 characters after trimming. Defaults to an empty string. |

The prefix is required; a bare IP address is rejected. DBHost stores the CIDR
as you send it, after trimming whitespace.

```http theme={null}
POST /api/v1/databases/{id}/network/allowlist
Authorization: Bearer <api-key>
Content-Type: application/json

{"cidr":"198.51.100.0/24","label":"Office"}
```

```json 201 Created theme={null}
{
  "message": "Allowlist entry added.",
  "data": {
    "id": "3f2b8c1e-9a4d-4b7e-8f21-6c0d5e7a9b10",
    "databaseId": "550e8400-e29b-41d4-a716-446655440000",
    "cidr": "198.51.100.0/24",
    "label": "Office",
    "createdByUserId": "<user-id>",
    "createdAt": "2026-10-14T09:00:00.000Z"
  }
}
```

Adding a CIDR that is already on the list returns `200 OK` with the message
`Allowlist entry already exists.` and the existing entry. The existing label is
not changed.

The new list is applied before the request returns. If DBHost cannot apply
it, the request fails and the entry is not saved.

## Remove an entry

`DELETE /api/v1/databases/{id}/network/allowlist/{entryId}`

`entryId` is the `id` from the list or add response. On success the route
returns `204 No Content` with an empty body.

```http theme={null}
DELETE /api/v1/databases/{id}/network/allowlist/{entryId}
Authorization: Bearer <api-key>
```

## Errors

| Status | Code | Description |
| - | - | - |
| 400 | `VALIDATION_ERROR` | `cidr` is not a valid IPv4 or IPv6 CIDR block, or `label` is longer than 120 characters |
| 400 | `INVALID_JSON` | Request body is not valid JSON |
| 401 | `UNAUTHORIZED` | Missing or invalid API key |
| 403 | `PLAN_API_ACCESS_REQUIRED` | The account is not on Pro or Business |
| 404 | `DATABASE_NOT_FOUND` | Database does not exist or is not visible to this key |
| 404 | `ALLOWLIST_ENTRY_NOT_FOUND` | No entry with this ID on this database |
| 409 | State code, for example `DATABASE_STOPPED` | The database's current state does not allow the change |
| 413 | `PAYLOAD_TOO_LARGE` | Request body is larger than 64 KB |
| 429 | `RATE_LIMITED` | Too many requests; retry after `Retry-After` seconds |
| 502 | `AGENT_ERROR` | The change could not be applied, for example while the database is being deleted. The list is unchanged. |
| 503 | `MAINTENANCE` | Scheduled maintenance; retry after `Retry-After` seconds |

During maintenance the body is `{"error":"MAINTENANCE","message":"..."}`
instead of the standard error envelope.

The dashboard manages the same list in the **Allowed IPs** section on the **Access** tab; see
[Databases](/dashboard/databases). The CLI equivalents are
`dbhost network list|add|remove`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.