Public API

Public API

The Public API allows programmatic access to manage your data streams. This guide covers authentication, endpoints, and common use cases.

Authentication

All API requests require authentication using a service user API key. The key should be included in the Authorization header using the Bearer token scheme:
  1. Authorization: Bearer kdk_srv_xxxxxxxxxxxxx

Setting Up API Access

Configure your API key as an environment variable:
  1. XEOTEK_KADECK_API_KEY=kdk_srv_xxxxxxxxxxxxx
Test your authentication:
  1. curl --location 'https://your-instance.com/public/v1/test' \
  2. --header 'Authorization: Bearer kdk_srv_xxxxxxxxxxxxx'
A successful response (200) will return:
  1. Hello from Data Streamhouse's Public API!

Best Practices

API Key Security
  1. Store API keys securely as environment variables
  2. Rotate keys periodically
  3. Never commit API keys to source control
Error Handling
  1. Always check for error responses
  2. Implement proper retry logic for failed requests

Manage Data Catalog Metadata

The API allows you to update metadata for data streams in your catalog. You can identify streams using their connection ID and stream name.

Update Stream Metadata

  1. PUT /public/v1/datacatalog/connections/{connection_id}/streams/{stream_name}/metadata

Full Update Example

  1. curl --location --request PUT 'https://your-instance.com/public/v1/datacatalog/connections/42/streams/spacecraft.telemetry.raw/metadata' \
  2. --header 'Content-Type: application/json' \
  3. --header 'Authorization: Bearer kdk_srv_xxxxxxxxxxxxx' \
  4. --data-raw '{
  5.     "metadata": {
  6.         "tags": ["spacecraft", "telemetry", "raw-data"],
  7.         "ownerId": "sarah.connor@skynet.com",
  8.         "domainId": "9f83cc67-d3da-4432-b0b7-0d08e7b41d86",
  9.         "documentation": "<h1>Spacecraft Telemetry Stream</h1><p>This stream contains raw telemetry data from our spacecraft fleet, including:</p><ul><li>Position data</li><li>System health metrics</li><li>Environmental readings</li></ul>",
  10.         "updatedBy": "sarah.connor@skynet.com",
  11.         "updatedAt": 1707347405000
  12.     }
  13. }'

Partial Update Example

You can update specific fields without affecting others:
  1. curl --location --request PUT 'https://your-instance.com/public/v1/datacatalog/connections/42/streams/spacecraft.telemetry.raw/metadata' \
  2. --header 'Content-Type: application/json' \
  3. --header 'Authorization: Bearer kdk_srv_xxxxxxxxxxxxx' \
  4. --data '{
  5.     "metadata": {
  6.         "tags": ["spacecraft", "telemetry", "processed"],
  7.         "documentation": "<h1>Spacecraft Telemetry Stream</h1><p>Updated: This stream now contains processed telemetry data.</p>"
  8.     }
  9. }'

Metadata Fields

Field
Type
Description
Required
tags
string[]
Labels for categorizing the stream
optional
ownerId
string
User id of the stream owner
optional
domainId
string (UUID)
Domain identifier
optional
documentation
string
Rich text documentation (HTML)
optional
updatedBy
string
User id of the user making the documentation update
optional
updatedAt
long
Unix timestamp in millis
optional

Best Practices

  1. Use partial updates when possible to avoid overwriting existing data
  2. Include meaningful documentation
  3. Keep tags consistent and meaningful

Common errors

Status Code
Description
Solution
401
Unauthorized
Check your API key
404
Stream not found
Verify connection ID and stream name
400
Invalid request
Check your request payload format


Manage Topics

The Topic Management API allows programmatic access to create and delete topics in your data streaming platform. 

Create Topic

​Creates a new topic with specified configuration.
  1. POST /public/v1/topics

Request Body

  1. {
  2.     "name": "my.new.topic",
  3.     "metadata": {
  4.         "partitions": 3,
  5.         "replicationFactor": 2
  6.     },
  7.     "configs": [
  8.         {
  9.             "name": "cleanup.policy",
  10.             "value": "delete"
  11.         },
  12.         {
  13.             "name": "retention.ms",
  14.             "value": "604800000"
  15.         }
  16.     ]
  17. }

Example Request

  1. curl --location 'https://your-instance.com/public/v1/topics' \
  2. --header 'Content-Type: application/json' \
  3. --header 'Authorization: Bearer kdk_srv_xxxxxxxxxxxxx' \
  4. --data-raw '{
  5.     "name": "my.new.topic",
  6.     "metadata": {
  7.         "partitions": 3,
  8.         "replicationFactor": 2
  9.     },
  10.     "configs": [
  11.         {
  12.             "name": "cleanup.policy",
  13.             "value": "delete"
  14.         }
  15.     ]
  16. }'

Delete Topic

Deletes an existing topic.
  1. DELETE /public/v1/connections/{server}/streams/{topic}

Example Request

  1. curl --location --request DELETE 'https://your-instance.com/public/v1/connections/my-server/streams/my.topic' \
  2. --header 'Authorization: Bearer kdk_srv_xxxxxxxxxxxxx'

Request Models

TopicCreateRequest

FieldTypeDescriptionRequired
namestringName of the topic to createYes
metadataTopicMetadataTopic metadata configurationYes
configsTopicConfig[]Array of key value config pairsoptional

TopicMetadata

FieldTypeDescriptionRequired
partitionsintegerNumber of partitions for the topicYes
replicationFactorinteger Replication factor for the topicYes

TopicConfig

FieldTypeDescriptionRequired
namestringConfiguration parameter nameYes
valuestringConfiguration parameter valueYes


Best Practices

1. Choose appropriate partition counts based on expected throughput
2. Set reasonable replication factors for data safety
3. Configure retention policies based on data lifecycle requirements

Common Errors

Status CodeDescriptionSolution
401UnauthorizedCheck your API key
404Topic not foundVerify connection ID and stream name
400Invalid requestCheck your request payload format
409
Topic already exists
Use a different topic name or delete existing topic first


    • Related Articles

    • Data Protection Policies and Data Masking

      Data protection is a crucial aspect of business operations, especially when dealing with sensitive information. Kadeck Teams Enterprise is equipped with a Data Protection Policy module that helps you define data protection policies through the ...

    • Topic Overview & Documentation

      Kadeck’s Topic Overview, provides a consolidated glance at all topic details and documentation. This article will guide you through what information you can find in this view and how to document your topic. Overview Page When you open the Data ...

    • Introduction to the Quick Processor

      The Quick Processor allows you to create filters and modify records using JavaScript. In this article, we show how to create a Quick Processor and how to access, filter, and modify records. A Quick Processor is always linked to a view. This means ...

    • Data Limit and Parallel Factor

      Data Display Limit (no unit) How many records will be displayed in the UI of the Data Browser. After this limit is hit, all data coming from the backend for the same request will be ignored. Parallelism Factor (Kafka only) (no unit) How many ...

    • Release 6.X

      This article describes the changes of the version 6.x update. Latest image tag: xeotek/kadeck:6.0.0 Release 6 Patch notes This section contains all patch notes for Kadeck 6.x. Release 6.0.0 Streamlined API & Access Management Kadeck 6 introduces a ...