Skip to main content

​
Introduction

The Pulsar Admin API is a RESTful interface that allows you to manage and monitor all aspects of your Pulsar cluster. It provides comprehensive control over resources including tenants, namespaces, topics, schemas, clusters, and brokers.

​
Base URL

The Admin API is available at: 
http://<broker-url>:8080/admin/v2/
For secure connections: 
https://<broker-url>:8443/admin/v2/

​
API Version

This documentation covers Admin API v2, which is the current stable version. All endpoints are prefixed with /admin/v2/.

​
Authentication

Most Admin API operations require authentication. Pulsar supports multiple authentication mechanisms:
  • Token-based authentication: Pass JWT tokens via the Authorization header
  • TLS authentication: Use client certificates
  • OAuth 2.0: Authenticate using OAuth tokens

​
Example with Token Authentication

curl -H "Authorization: Bearer <token>" \
  http://localhost:8080/admin/v2/tenants

​
Authorization

Admin API operations require specific permissions:
  • Super-user: Full access to all resources
  • Tenant admin: Manage specific tenants and their resources
  • Namespace permissions: Control access at the namespace level
  • Topic permissions: Fine-grained control over individual topics

​
API Resources

The Admin API is organized into the following resource categories:

​
Core Resources

Tenants

Manage multi-tenant organizations and their configurations

Namespaces

Configure namespaces, policies, and resource quotas

Topics

Create and manage persistent and non-persistent topics

Schemas

Manage schema definitions and compatibility

​
Infrastructure Resources

Clusters

Configure and monitor Pulsar clusters

Brokers

Monitor and manage broker nodes

​
Common Response Codes

The Admin API uses standard HTTP status codes:
CodeMeaningDescription
200OKRequest successful
204No ContentOperation successful, no response body
307Temporary RedirectRequest redirected to the correct broker
400Bad RequestInvalid request parameters
401UnauthorizedAuthentication required
403ForbiddenInsufficient permissions
404Not FoundResource doesn’t exist
409ConflictResource already exists
412Precondition FailedValidation failed
500Internal Server ErrorServer error
503Service UnavailableService temporarily unavailable

​
Error Responses

Error responses include a JSON body with details: 
{
  "reason": "Namespace already exists",
  "message": "Namespace public/default already exists"
}

​
Rate Limiting

Admin API requests may be rate-limited based on your cluster configuration. Check the following headers in responses:
  • X-RateLimit-Limit: Maximum requests allowed
  • X-RateLimit-Remaining: Remaining requests in current window
  • X-RateLimit-Reset: Time when the limit resets

​
Async Operations

Many Admin API operations are asynchronous. For long-running operations:
  1. The API returns immediately with a 202 (Accepted) status
  2. Poll the operation status using the provided status endpoint
  3. The operation completes with success or failure

​
Client Libraries

Instead of using the REST API directly, you can use Pulsar’s admin clients: 
PulsarAdmin admin = PulsarAdmin.builder()
    .serviceHttpUrl("http://localhost:8080")
    .authentication(AuthenticationFactory.token(token))
    .build();

// List tenants
List<String> tenants = admin.tenants().getTenants();

​
Best Practices

​
Use Async Operations

For operations that may take time (like creating partitioned topics), use async endpoints when available.

​
Handle Redirects

The API may return 307 redirects when a broker doesn’t serve a particular resource. Ensure your client follows redirects.

​
Implement Retry Logic

Implement exponential backoff for transient errors (5xx responses).

​
Cache Responses

Cache configuration data that doesn’t change frequently to reduce API load.

​
Use Bulk Operations

When available, use bulk endpoints instead of making multiple individual requests.

​
Next Steps

Manage Tenants

Learn how to create and configure tenants

Configure Namespaces

Set up namespaces with policies and quotas

Work with Topics

Create and manage topics and subscriptions

Manage Schemas

Define and enforce schema compatibility

Build docs developers (and LLMs) love

Get started for freeTalk to us