HTTP API

The UI talks to klens through a JSON API under /api. Scripts can call the same API. Field names on the wire are in camel case, and enum values are in screaming snake case, such as NEWEST.

ConventionsCopy Anchor Link

• Sessions. With auth, every route except /api/auth/* needs the klens_session cookie. Without a session, a route answers 401 UNAUTHORIZED. Without auth, every caller holds every privilege on every cluster.
• Hosts. Without auth, klens answers a request only when its Host is in allowed_hosts. Any other request gets 403 HOST_NOT_ALLOWED.
• Errors. An error body is {"error": "<message>", "code": "<CODE>"}. Errors lists the codes.
• Lists in a query. A repeated key is a list: partition=0&partition=2.
• Writes. A write needs a cluster with writable: true and the privilege the route names. klens checks writable first, so a read-only cluster answers 403 READ_ONLY_CLUSTER before it checks the privilege. After a write succeeds, klens waits up to 10 seconds for its projection to show the change, then answers.
• Compression. klens compresses a response with zstd, brotli, or gzip, as the Accept-Encoding header allows. It never compresses a server-sent event stream.
• Unknown paths. An unknown path under /api answers 404 NOT_FOUND. A known path with the wrong method answers 405 INVALID_REQUEST.

A cluster outside the caller's roles answers 404 UNKNOWN_CLUSTER, the same as a cluster that does not exist.

HealthCopy Anchor Link

Both routes answer every host, need no session, and return no body. Point liveness checks at /health and readiness checks or load balancer health checks at /ready.

Sign-inCopy Anchor Link

These routes exist only with auth. Without it, they answer 404.

AccessCopy Anchor Link

ClustersCopy Anchor Link

Cluster health holds ready, the counts of topics, partitions, groups, brokers, and subjects, underReplicatedPartitions, offlinePartitions, and one entry for each lane: topology, watermarks, offsets, configs, subjects, logDirs, acls, quotas, and scramUsers. A lane entry is {updatedAt, checkedAt, lastError, lastPollMs, healthy}.

TopicsCopy Anchor Link

source is DYNAMIC_TOPIC_CONFIG, DYNAMIC_BROKER_CONFIG, DYNAMIC_DEFAULT_BROKER_CONFIG, STATIC_BROKER_CONFIG, or DEFAULT_CONFIG. A config edit must name at least one config, and no config in both set and reset. A write to an internal topic answers 422 INTERNAL_TOPIC.

RecordsCopy Anchor Link

Page queryCopy Anchor Link

A from later than to answers 400 INVERTED_TIMESTAMP_RANGE. An unknown partition answers 404 UNKNOWN_PARTITION.

Record pageCopy Anchor Link

A page is {records, complete, obfuscated, nextCursor, prevCursor}.

• complete is false when the read reached tuning.kafka.consume_timeout before it read every offset in its window. More matches may exist. When the read reaches the timeout before it reads anything, the page answers 504 TIMEOUT.
• obfuscated is true when an obfuscation rule covers the topic.

A record is {topic, partition, offset, timestamp, key, value, schemaId, headers, sizeBytes, verbatim}. headers is a list of {key, value}. verbatim is true when key and value show the exact bytes.

Single recordCopy Anchor Link

The route answers 404 UNKNOWN_OFFSET when the partition holds no record at that offset. Retention, compaction, or a transaction marker can leave an offset without a record.

ExportCopy Anchor Link

The export reads every record that matches the query and streams it as application/x-ndjson, with the file name <topic>.ndjson. It reads the end offsets once at the start, so records that arrive during the export are not in it. It reads in pages of tuning.records.max_limit records and checks the session and the records privilege before each page. An error after the stream starts ends the stream without a JSON error.

ProduceCopy Anchor Link

key and value are each a payload or null. A null key writes a record without a key. A null value writes a tombstone.

headers is a list of {key, value} with text values. Without partition, the producer picks a partition.

Delete recordsCopy Anchor Link

partition names the partitions, and every partition when it is absent. before deletes the records before that offset, and every record when it is absent.

Consumer groupsCopy Anchor Link

A group ID may contain /. lagComplete is false when the lag leaves out partitions whose end offset klens has not read yet.

An offset reset moves the committed offsets of topic, or of every topic the group committed when topic is absent. partitions needs topic. to is one of these targets:

With dryRun: true, klens returns the moves and changes nothing. A dry run needs the same privilege and a writable cluster. A real reset and a group deletion answer 409 ACTIVE_GROUP while the group has members. Deleting the offsets of a topic the group still consumes answers 409 CONSUMED_TOPIC.

BrokersCopy Anchor Link

A log dir is {path, error, totalBytes, usableBytes, cordoned, sizeBytes, replicaCount}.

Schema subjectsCopy Anchor Link

A row is {subject, id, type, latestVersion, versions, compatibility}. type is AVRO, JSON, or PROTOBUF. compatibility is BACKWARD, BACKWARD_TRANSITIVE, FORWARD, FORWARD_TRANSITIVE, FULL, FULL_TRANSITIVE, or NONE. A delete without version deletes every version. permanent defaults to false, which keeps the schema IDs in the registry. A route on a cluster without a registry answers 404 NO_SCHEMA_REGISTRY.

ACLsCopy Anchor Link

A binding is {resourceType, resourceName, patternType, principal, host, operation, permission}.

status is PENDING before the first read, ENABLED, DISABLED when the cluster runs no authorizer, or DENIED when the Kafka user of klens may not describe ACLs.

QuotasCopy Anchor Link

entity is a list of {entityType, name}. entityType is USER, CLIENT_ID, or IP, and a null name means the default for that type. A PUT sets the quota values it names and removes every value it leaves out or sets to null. status is PENDING, DESCRIBED, or DENIED.

SCRAM usersCopy Anchor Link

mechanism is SHA256 or SHA512. iterations defaults to 4096 and must be from 4096 to 16384. A user is {name, credentials: [{mechanism, iterations}]}. Kafka never returns a password or a salt.

Live updatesCopy Anchor Link

GET /api/clusters/{cluster}/updates is a server-sent event stream that tells the UI what changed in the projection. It needs no privilege, since its frames carry names, counts, and rates only. The query takes topic and group to narrow it. With group, klens reads the offsets of that group every tuning.ingest.fast_offset while the stream is open.

Each frame's event name is the value of its type field.

klens checks the session again on each change and sends error with SESSION_EXPIRED when it has ended. It sends a keep-alive comment every 15 seconds.

Live tailCopy Anchor Link

GET /api/clusters/{cluster}/topics/{topic}/records/tail follows a topic from the current end of each partition. It answers 503 TOO_MANY_TAILS when tuning.tail.max_live tails already run.

A records frame holds at most tuning.tail.batch_limit records, and frames are at least tuning.tail.interval apart. When a topic produces faster than that, each frame keeps the newest records and skipped counts the rest. A partition that falls far behind skips ahead to its newest records. A frame can hold no records and a skipped count. klens checks the session after each frame and every 15 seconds.

ErrorsCopy Anchor Link