Namespaces API - Apache Pulsar

Overview

Namespaces are logical groupings of topics within a tenant. They provide isolation and allow you to configure policies like retention, TTL, replication, and more. The Namespaces API provides comprehensive control over namespace configuration. Base Path: /admin/v2/namespaces

List Namespaces

Get all namespaces for a specific tenant.

GET /admin/v2/namespaces/{tenant}

Path Parameters

tenant

string

required

The tenant name

Example

curl -X GET http://localhost:8080/admin/v2/namespaces/my-tenant \
  -H "Authorization: Bearer <token>"

Response Example

[
  "my-tenant/ns1",
  "my-tenant/ns2",
  "my-tenant/production"
]

Get Namespace Policies

Retrieve all policies configured for a namespace.

GET /admin/v2/namespaces/{tenant}/{namespace}

Path Parameters

tenant

string

required

The tenant name

namespace

string

required

The namespace name

Response

auth_policies

object

Permission policies for roles

replication_clusters

array

List of clusters for geo-replication

bundles

object

Bundle split configuration

backlog_quota_map

object

Backlog quota policies

persistence_policies

object

Message persistence configuration

retention_policies

object

Message retention settings

message_ttl_in_seconds

integer

Time-to-live for messages

Example

curl -X GET http://localhost:8080/admin/v2/namespaces/my-tenant/my-namespace \
  -H "Authorization: Bearer <token>"

Create Namespace

Create a new namespace within a tenant.

PUT /admin/v2/namespaces/{tenant}/{namespace}

Path Parameters

tenant

string

required

The tenant name

namespace

string

required

The namespace name to create

Request Body

policies

object

Optional policies to set during creation

Example

curl -X PUT http://localhost:8080/admin/v2/namespaces/my-tenant/my-namespace \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{}'

Response Codes

Code	Description
204	Namespace created successfully
403	Don’t have admin permission
404	Tenant doesn’t exist
409	Namespace already exists
412	Namespace name is not valid

Delete Namespace

Delete a namespace and all its topics.

DELETE /admin/v2/namespaces/{tenant}/{namespace}

Path Parameters

tenant

string

required

The tenant name

namespace

string

required

The namespace name to delete

Query Parameters

force

boolean

default:"false"

Force delete even if namespace is not empty

authoritative

boolean

default:"false"

Whether this broker is authoritative for the operation

Example

curl -X DELETE http://localhost:8080/admin/v2/namespaces/my-tenant/my-namespace \
  -H "Authorization: Bearer <token>"

Get Topics

List all topics in a namespace.

GET /admin/v2/namespaces/{tenant}/{namespace}/topics

Path Parameters

tenant

string

required

The tenant name

namespace

string

required

The namespace name

Query Parameters

mode

string

default:"PERSISTENT"

Topic mode: PERSISTENT, NON_PERSISTENT, or ALL

includeSystemTopic

boolean

default:"false"

Whether to include system topics

Example

curl -X GET http://localhost:8080/admin/v2/namespaces/my-tenant/my-namespace/topics \
  -H "Authorization: Bearer <token>"

Permissions

Grant Permission

Grant permissions to a role on a namespace.

POST /admin/v2/namespaces/{tenant}/{namespace}/permissions/{role}

Path Parameters

tenant

string

required

The tenant name

namespace

string

required

The namespace name

role

string

required

The role name

Request Body

actions

array

required

Array of actions: “produce”, “consume”, “functions”

Example

curl -X POST http://localhost:8080/admin/v2/namespaces/my-tenant/my-namespace/permissions/my-role \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '["produce", "consume"]'

Get Permissions

Retrieve permissions for a namespace.

GET /admin/v2/namespaces/{tenant}/{namespace}/permissions

Example

curl -X GET http://localhost:8080/admin/v2/namespaces/my-tenant/my-namespace/permissions \
  -H "Authorization: Bearer <token>"

Revoke Permission

Revoke all permissions from a role on a namespace.

DELETE /admin/v2/namespaces/{tenant}/{namespace}/permissions/{role}

Example

curl -X DELETE http://localhost:8080/admin/v2/namespaces/my-tenant/my-namespace/permissions/my-role \
  -H "Authorization: Bearer <token>"

Message TTL

Set Message TTL

Set the time-to-live for messages in a namespace.

POST /admin/v2/namespaces/{tenant}/{namespace}/messageTTL

Request Body

messageTTL

integer

required

TTL in seconds

Example

curl -X POST http://localhost:8080/admin/v2/namespaces/my-tenant/my-namespace/messageTTL \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '3600'

Get Message TTL

Get the message TTL for a namespace.

GET /admin/v2/namespaces/{tenant}/{namespace}/messageTTL

Remove Message TTL

Remove the message TTL setting.

DELETE /admin/v2/namespaces/{tenant}/{namespace}/messageTTL

Replication

Set Replication Clusters

Configure geo-replication for a namespace.

POST /admin/v2/namespaces/{tenant}/{namespace}/replication

Request Body

clusterIds

array

required

List of cluster names for replication

Example

curl -X POST http://localhost:8080/admin/v2/namespaces/my-tenant/my-namespace/replication \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '["us-west", "us-east", "eu-central"]'

Get Replication Clusters

Get the list of replication clusters.

GET /admin/v2/namespaces/{tenant}/{namespace}/replication

Deduplication

Enable/Disable Deduplication

POST /admin/v2/namespaces/{tenant}/{namespace}/deduplication

Request Body

enableDeduplication

boolean

required

Enable or disable broker-side deduplication

Example

curl -X POST http://localhost:8080/admin/v2/namespaces/my-tenant/my-namespace/deduplication \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d 'true'

Get Deduplication Status

GET /admin/v2/namespaces/{tenant}/{namespace}/deduplication

Auto Topic Creation

Set Auto Topic Creation

Configure automatic topic creation settings.

POST /admin/v2/namespaces/{tenant}/{namespace}/autoTopicCreation

Request Body

allowAutoTopicCreation

boolean

required

Whether to allow automatic topic creation

topicType

string

required

Type of topics to create: “partitioned” or “non-partitioned”

defaultNumPartitions

integer

Default number of partitions for partitioned topics

Example

curl -X POST http://localhost:8080/admin/v2/namespaces/my-tenant/my-namespace/autoTopicCreation \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "allowAutoTopicCreation": true,
    "topicType": "partitioned",
    "defaultNumPartitions": 3
  }'

Best Practices

Namespace Organization

Create separate namespaces for different environments (dev, staging, prod)
Use namespaces to isolate different applications or teams
Keep related topics in the same namespace

Policy Configuration

Set appropriate retention policies based on use case
Configure message TTL to prevent unbounded growth
Enable deduplication for exactly-once semantics

Geo-Replication

Configure replication for disaster recovery
Consider network latency between clusters
Monitor replication lag

Permissions

Use least privilege principle
Grant permissions at namespace level when possible
Regularly audit and review permissions

Tenants API

Manage parent tenant resources

Topics API

Manage topics within namespaces

REST API

CLI Tools

​Overview

​List Namespaces

​Path Parameters

​Example

​Response Example

​Get Namespace Policies

​Path Parameters

​Response

​Example

​Create Namespace

​Path Parameters

​Request Body

​Example

​Response Codes

​Delete Namespace

​Path Parameters

​Query Parameters

​Example

​Get Topics

​Path Parameters

​Query Parameters

​Example

​Permissions

​Grant Permission

​Path Parameters

​Request Body

​Example

​Get Permissions

​Example

​Revoke Permission

​Example

​Message TTL

​Set Message TTL

​Request Body

​Example

​Get Message TTL

​Remove Message TTL

​Replication

​Set Replication Clusters

​Request Body

​Example

​Get Replication Clusters

​Deduplication

​Enable/Disable Deduplication

​Request Body

​Example

​Get Deduplication Status

​Auto Topic Creation

​Set Auto Topic Creation

​Request Body

​Example

​Best Practices

​Namespace Organization

​Policy Configuration

​Geo-Replication

​Permissions

​Related Resources

Tenants API

Topics API

Build docs developers (and LLMs) love

Overview

List Namespaces

Path Parameters

Example

Response Example

Get Namespace Policies

Path Parameters

Response

Example

Create Namespace

Path Parameters

Request Body

Example

Response Codes

Delete Namespace

Path Parameters

Query Parameters

Example

Get Topics

Path Parameters

Query Parameters

Example

Permissions

Grant Permission

Path Parameters

Request Body

Example

Get Permissions

Example

Revoke Permission

Example

Message TTL

Set Message TTL

Request Body

Example

Get Message TTL

Remove Message TTL

Replication

Set Replication Clusters

Request Body

Example

Get Replication Clusters

Deduplication

Enable/Disable Deduplication

Request Body

Example

Get Deduplication Status

Auto Topic Creation

Set Auto Topic Creation

Request Body

Example

Best Practices

Namespace Organization

Policy Configuration

Geo-Replication

Permissions

Related Resources