---
title: "Create Blocklist"
method: POST
path: "/v3/workspaces/{workspace_id}/blocklists"
tags: ["Blocklists"]
---

# Create Blocklist

`POST /v3/workspaces/{workspace_id}/blocklists`

Create a new blocklist in the specified workspace. The blocklist is defined by a GNQL query and will automatically refresh its IP list.

## Path parameters

- `workspace_id` string, uuid, required

## Request body

- CreateBlocklistRequest
  - `query` string, required — GNQL query that defines the blocklist.
  - `name` string — Human-readable name for the blocklist.
  - `ip_limit` integer, nullable — Maximum number of IPs to return. Must be greater than 0 when provided.
  - `enabled` boolean — Whether the blocklist should be active. Defaults to true if omitted.
  - `query_workspace_id` string, uuid — Workspace whose data the query runs against. Requires the GNQL Diff entitlement.

## Response `201`

Created - blocklist successfully created.

- BlocklistResponse
  - `id` string, uuid — Blocklist ID.
  - `workspace_id` string, uuid — Owning workspace ID.
  - `query` string — GNQL query that defines the blocklist.
  - `query_hash` string — Hash of the GNQL query.
  - `name` string, nullable — Human-readable name for the blocklist.
  - `ip_limit` integer, nullable — Maximum number of IPs the blocklist will return.
  - `entitlement_level` string — The entitlement level used when the blocklist was created.
  - `enabled` boolean — Whether the blocklist is active.
  - `last_ip_count` integer — Number of IPs returned on last refresh.
  - `query_workspace_id` string, uuid — Workspace whose data the query runs against, when different from the owning workspace.
  - `token` string — Opaque token for unauthenticated blocklist access. Returned on list, create, and single-get operations.
  - `created_at` string, date-time — Creation timestamp.
  - `updated_at` string, date-time — Last update timestamp.

## Other responses

- `400` — Bad request - request syntax is invalid for the specified endpoint. Verify request syntax and try again.
- `401` — Unauthorized. Please check your API key.
- `403` — Forbidden - request is not authorized due to an invalid API key or plan limitations. If due to plan limitations, contact sales@greynoise.io to upgrade your plan and unlock full results.
- `500` — Unexpected error

---

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