POST /v1/topics

from metadata.sdk import configure
from metadata.sdk.entities import Topics
from metadata.generated.schema.api.data.createTopic import CreateTopicRequest

configure(
    host="https://your-company.open-metadata.org/api",
    jwt_token="your-jwt-token"
)

request = CreateTopicRequest(
    name="address_book",
    displayName="Address Book",
    service="sample_kafka",
    description="All Protobuf record related events gets captured in this topic",
    messageSchema={
        "schemaType": "Protobuf",
        "schemaText": "syntax = \"proto2\";\npackage tutorial;\nmessage Person { ... }"
    },
    partitions=1,
    cleanupPolicies=["delete"],
    replicationFactor=1,
    maximumMessageSize=1,
    retentionSize=-1
)

topic = Topics.create(request)
print(f"Created: {topic.fullyQualifiedName}")

import static org.openmetadata.sdk.fluent.Topics.*;

// Create using builder pattern
var topic = Topics.builder()
    .name("address_book")
    .displayName("Address Book")
    .service("sample_kafka")
    .description("All Protobuf record related events gets captured in this topic")
    .partitions(1)
    .cleanupPolicies(List.of("delete"))
    .replicationFactor(1)
    .create();

curl -X POST "{base_url}/api/v1/topics" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "address_book",
    "service": "sample_kafka",
    "description": "All Protobuf record related events gets captured in this topic",
    "messageSchema": {
      "schemaType": "Protobuf",
      "schemaText": "syntax = \"proto2\";\npackage tutorial;\nmessage Person { ... }"
    },
    "partitions": 1,
    "cleanupPolicies": ["delete"],
    "replicationFactor": 1,
    "maximumMessageSize": 1,
    "retentionSize": -1
  }'

{
  "id": "0a021819-982e-4ee4-a5a2-4af30eaa3016",
  "name": "address_book",
  "fullyQualifiedName": "sample_kafka.address_book",
  "description": "All Protobuf record related events gets captured in this topic",
  "version": 0.1,
  "updatedAt": 1769982663546,
  "updatedBy": "admin",
  "service": {
    "id": "469ef25e-9bdf-4d5f-8553-eb0ce8581f30",
    "type": "messagingService",
    "name": "sample_kafka",
    "fullyQualifiedName": "sample_kafka",
    "displayName": "sample_kafka",
    "deleted": false
  },
  "serviceType": "Kafka",
  "messageSchema": {
    "schemaText": "syntax = \"proto2\";\npackage tutorial;\nmessage Person { ... }",
    "schemaType": "Protobuf",
    "schemaFields": [
      {
        "name": "AddressBook",
        "dataType": "RECORD",
        "fullyQualifiedName": "sample_kafka.address_book.AddressBook",
        "children": []
      }
    ]
  },
  "partitions": 1,
  "cleanupPolicies": ["delete"],
  "replicationFactor": 1,
  "maximumMessageSize": 1,
  "retentionSize": -1,
  "href": "http://localhost:8585/api/v1/topics/0a021819-982e-4ee4-a5a2-4af30eaa3016",
  "deleted": false,
  "owners": [],
  "tags": [],
  "followers": [],
  "votes": {
    "upVotes": 0,
    "downVotes": 0,
    "upVoters": [],
    "downVoters": []
  },
  "domains": []
}

POST

topics

POST /v1/topics

from metadata.sdk import configure
from metadata.sdk.entities import Topics
from metadata.generated.schema.api.data.createTopic import CreateTopicRequest

configure(
    host="https://your-company.open-metadata.org/api",
    jwt_token="your-jwt-token"
)

request = CreateTopicRequest(
    name="address_book",
    displayName="Address Book",
    service="sample_kafka",
    description="All Protobuf record related events gets captured in this topic",
    messageSchema={
        "schemaType": "Protobuf",
        "schemaText": "syntax = \"proto2\";\npackage tutorial;\nmessage Person { ... }"
    },
    partitions=1,
    cleanupPolicies=["delete"],
    replicationFactor=1,
    maximumMessageSize=1,
    retentionSize=-1
)

topic = Topics.create(request)
print(f"Created: {topic.fullyQualifiedName}")

import static org.openmetadata.sdk.fluent.Topics.*;

// Create using builder pattern
var topic = Topics.builder()
    .name("address_book")
    .displayName("Address Book")
    .service("sample_kafka")
    .description("All Protobuf record related events gets captured in this topic")
    .partitions(1)
    .cleanupPolicies(List.of("delete"))
    .replicationFactor(1)
    .create();

curl -X POST "{base_url}/api/v1/topics" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "address_book",
    "service": "sample_kafka",
    "description": "All Protobuf record related events gets captured in this topic",
    "messageSchema": {
      "schemaType": "Protobuf",
      "schemaText": "syntax = \"proto2\";\npackage tutorial;\nmessage Person { ... }"
    },
    "partitions": 1,
    "cleanupPolicies": ["delete"],
    "replicationFactor": 1,
    "maximumMessageSize": 1,
    "retentionSize": -1
  }'

{
  "id": "0a021819-982e-4ee4-a5a2-4af30eaa3016",
  "name": "address_book",
  "fullyQualifiedName": "sample_kafka.address_book",
  "description": "All Protobuf record related events gets captured in this topic",
  "version": 0.1,
  "updatedAt": 1769982663546,
  "updatedBy": "admin",
  "service": {
    "id": "469ef25e-9bdf-4d5f-8553-eb0ce8581f30",
    "type": "messagingService",
    "name": "sample_kafka",
    "fullyQualifiedName": "sample_kafka",
    "displayName": "sample_kafka",
    "deleted": false
  },
  "serviceType": "Kafka",
  "messageSchema": {
    "schemaText": "syntax = \"proto2\";\npackage tutorial;\nmessage Person { ... }",
    "schemaType": "Protobuf",
    "schemaFields": [
      {
        "name": "AddressBook",
        "dataType": "RECORD",
        "fullyQualifiedName": "sample_kafka.address_book.AddressBook",
        "children": []
      }
    ]
  },
  "partitions": 1,
  "cleanupPolicies": ["delete"],
  "replicationFactor": 1,
  "maximumMessageSize": 1,
  "retentionSize": -1,
  "href": "http://localhost:8585/api/v1/topics/0a021819-982e-4ee4-a5a2-4af30eaa3016",
  "deleted": false,
  "owners": [],
  "tags": [],
  "followers": [],
  "votes": {
    "upVotes": 0,
    "downVotes": 0,
    "upVoters": [],
    "downVoters": []
  },
  "domains": []
}

Create a Topic

Create a new topic within a messaging service.

Body Parameters

name

string

required

Name of the topic. Must be unique within the parent messaging service.

service

string

required

Fully qualified name of the parent MessagingService (e.g., sample_kafka).

messageSchema

object

Schema definition for messages in the topic.

Show properties

schemaType

string

Type of schema (e.g., Avro, Protobuf, JSON, Other).

schemaText

string

The schema definition text.

partitions

integer

Number of partitions for the topic.

cleanupPolicies

array

Array of cleanup policies for the topic (e.g., delete, compact).

replicationFactor

integer

Replication factor for the topic.

maximumMessageSize

integer

Maximum message size in bytes.

retentionSize

integer

Retention size in bytes. Use -1 for unlimited.

displayName

string

Human-readable display name for the topic.

description

string

Description of the topic in Markdown format.

owners

array

Array of owner references (users or teams) to assign to the topic.

Show properties

string

UUID of the owner entity.

type

string

Type of owner entity (e.g., user, team).

name

string

Name of the owner entity.

domain

string

Fully qualified name of the domain to assign for governance purposes.

tags

array

Array of classification tags to apply to the topic.

Show properties

tagFQN

string

required

Fully qualified name of the tag.

labelType

string

Type of label (e.g., Manual, Derived, Propagated).

state

string

State of the tag (e.g., Suggested, Confirmed).

extension

object

Custom property values defined by your organization’s metadata schema.

POST /v1/topics

from metadata.sdk import configure
from metadata.sdk.entities import Topics
from metadata.generated.schema.api.data.createTopic import CreateTopicRequest

configure(
    host="https://your-company.open-metadata.org/api",
    jwt_token="your-jwt-token"
)

request = CreateTopicRequest(
    name="address_book",
    displayName="Address Book",
    service="sample_kafka",
    description="All Protobuf record related events gets captured in this topic",
    messageSchema={
        "schemaType": "Protobuf",
        "schemaText": "syntax = \"proto2\";\npackage tutorial;\nmessage Person { ... }"
    },
    partitions=1,
    cleanupPolicies=["delete"],
    replicationFactor=1,
    maximumMessageSize=1,
    retentionSize=-1
)

topic = Topics.create(request)
print(f"Created: {topic.fullyQualifiedName}")

import static org.openmetadata.sdk.fluent.Topics.*;

// Create using builder pattern
var topic = Topics.builder()
    .name("address_book")
    .displayName("Address Book")
    .service("sample_kafka")
    .description("All Protobuf record related events gets captured in this topic")
    .partitions(1)
    .cleanupPolicies(List.of("delete"))
    .replicationFactor(1)
    .create();

curl -X POST "{base_url}/api/v1/topics" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "address_book",
    "service": "sample_kafka",
    "description": "All Protobuf record related events gets captured in this topic",
    "messageSchema": {
      "schemaType": "Protobuf",
      "schemaText": "syntax = \"proto2\";\npackage tutorial;\nmessage Person { ... }"
    },
    "partitions": 1,
    "cleanupPolicies": ["delete"],
    "replicationFactor": 1,
    "maximumMessageSize": 1,
    "retentionSize": -1
  }'

{
  "id": "0a021819-982e-4ee4-a5a2-4af30eaa3016",
  "name": "address_book",
  "fullyQualifiedName": "sample_kafka.address_book",
  "description": "All Protobuf record related events gets captured in this topic",
  "version": 0.1,
  "updatedAt": 1769982663546,
  "updatedBy": "admin",
  "service": {
    "id": "469ef25e-9bdf-4d5f-8553-eb0ce8581f30",
    "type": "messagingService",
    "name": "sample_kafka",
    "fullyQualifiedName": "sample_kafka",
    "displayName": "sample_kafka",
    "deleted": false
  },
  "serviceType": "Kafka",
  "messageSchema": {
    "schemaText": "syntax = \"proto2\";\npackage tutorial;\nmessage Person { ... }",
    "schemaType": "Protobuf",
    "schemaFields": [
      {
        "name": "AddressBook",
        "dataType": "RECORD",
        "fullyQualifiedName": "sample_kafka.address_book.AddressBook",
        "children": []
      }
    ]
  },
  "partitions": 1,
  "cleanupPolicies": ["delete"],
  "replicationFactor": 1,
  "maximumMessageSize": 1,
  "retentionSize": -1,
  "href": "http://localhost:8585/api/v1/topics/0a021819-982e-4ee4-a5a2-4af30eaa3016",
  "deleted": false,
  "owners": [],
  "tags": [],
  "followers": [],
  "votes": {
    "upVotes": 0,
    "downVotes": 0,
    "upVoters": [],
    "downVoters": []
  },
  "domains": []
}

Returns

Returns the created topic object with all specified properties and system-generated fields.

Response

string

Unique identifier for the topic (UUID format).

name

string

Topic name.

fullyQualifiedName

string

Fully qualified name in format service.topicName.

displayName

string

Human-readable display name.

description

string

Description of the topic in Markdown format.

service

object

Reference to the parent messaging service.

Show properties

string

UUID of the messaging service.

type

string

Type of entity (always messagingService).

name

string

Name of the messaging service.

fullyQualifiedName

string

Fully qualified name of the messaging service.

messageSchema

object

Schema definition for messages in the topic.

Show properties

schemaType

string

Type of schema (e.g., Avro, Protobuf, JSON).

schemaText

string

The schema definition text.

schemaFields

array

Parsed schema fields.

partitions

integer

Number of partitions for the topic.

cleanupPolicies

array

Cleanup policies for the topic.

replicationFactor

integer

Replication factor for the topic.

maximumMessageSize

integer

Maximum message size in bytes.

retentionSize

integer

Retention size in bytes.

serviceType

string

Type of messaging service (e.g., Kafka, Redpanda, Kinesis).

owners

array

List of owners assigned to the topic.

Show properties

string

UUID of the owner entity.

type

string

Type of owner entity (e.g., user, team).

name

string

Name of the owner entity.

domains

array

Domain assignments for governance.

Create or Update (PUT)

Use PUT /v1/topics instead of POST to perform an upsert. If a topic with the same fullyQualifiedName already exists, it will be updated; otherwise, a new topic is created. The request body is the same as POST.

curl -X PUT "{base_url}/api/v1/topics" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{ ... same body as POST ... }'

PUT will not return a 409 conflict error if the entity already exists — it will update the existing entity instead.

Bulk Create or Update (PUT)

Use PUT /v1/topics/bulk to create or update multiple topics in a single request. The request body is an array of create request objects.

curl -X PUT "{base_url}/api/v1/topics/bulk" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '[
    { "name": "topic_one", "service": "sample_kafka" },
    { "name": "topic_two", "service": "sample_kafka" }
  ]'

Error Handling

Code	Error Type	Description
`400`	`BAD_REQUEST`	Invalid request body or missing required fields
`401`	`UNAUTHORIZED`	Invalid or missing authentication token
`403`	`FORBIDDEN`	User lacks permission to create topics
`409`	`ENTITY_ALREADY_EXISTS`	Topic with same name already exists in service (POST only)

Topics

Delete a Topic

​Create a Topic

​Body Parameters

​Returns

​Response

​Create or Update (PUT)

​Bulk Create or Update (PUT)

​Error Handling

Create a Topic

Body Parameters

Returns

Response

Create or Update (PUT)

Bulk Create or Update (PUT)

Error Handling