This page is generated from the public contract. Descriptions are shown in the original Korean.
Cluster 소속 Topic, Message Definition·사용 설명 항목.
Topic 조회#
GET /api/messaging-clusters/{cluster_id}/topics
q·sort·page·per_page를 모두 생략하면 전체 배열을 반환합니다. 다른 query·중복 키와 본문은 400이며 조건 헤더는 무시합니다.
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
cluster_id | path | string | Yes | |
q | query | string | No | 앞뒤 U+0020 제거, 대소문자 구분 리터럴 부분 검색(name·summary·description 중 하나라도 일치하면 포함) |
sort | query | string | No | 생략 시 기존 기본 순서(name 오름차순, ID 오름차순) 유지 Values: name, -name |
page | query | integer | No | page·per_page 중 하나라도 있으면 페이지 모드. 생략 시 1 |
per_page | query | integer | No | 생략 시 100, 최대 500 |
Responses
| Status | Description |
|---|---|
200 | 성공. 페이지 모드에서만 X-Pagination-* 헤더를 반환합니다. |
400 | 오류 |
401 | UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다. |
403 | ORGANIZATION_UNVERIFIED: 현재 Organization 또는 Agent 토큰의 Organization이 인증 대기입니다. |
404 | 오류 |
405 | 오류 |
409 | ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다. |
500 | 오류 |
200 response body
An array (Topic[]). The table lists item fields.
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | |
summary | string | Yes | 목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다. |
description | string | Yes | |
partition_count | integer | null | Yes | |
cleanup_policy | any[] | null | Yes | |
time_retention_ms | integer | null | Yes | |
retention_order_description | string | Yes | |
external_references | Kafka.ExternalReference[] | Yes | |
message_definitions | MessageDefinition[] | Yes | |
usages | Usage[] | Yes | |
cluster_id | string | Yes | |
id | string | Yes | |
created_at | string(date-time) | Yes | |
updated_at | string(date-time) | Yes |
Topic 생성#
POST /api/messaging-clusters/{cluster_id}/topics
Topic 본문은 4194304바이트 이하(초과 413)입니다. 부모 Cluster가 없으면 404 CLUSTER_NOT_FOUND입니다. query는 400이며 조건 헤더는 무시합니다.
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
cluster_id | path | string | Yes | |
Origin | header | string | No | 세션 쿠키로 인증한 상태 변경 요청에서 필수이며 서버 origin과 같아야 합니다. Bearer 토큰 요청에는 적용하지 않습니다. |
Request body
application/json · Required: Yes
Type: TopicCreate
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | |
summary | string | No | 목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다. |
description | string | No | |
partition_count | integer | null | No | |
cleanup_policy | any[] | null | No | |
time_retention_ms | integer | null | No | |
retention_order_description | string | No | |
external_references | Kafka.ExternalReference[] | No | |
message_definitions | MessageDefinition[] | No | |
usages | UsageInput[] | No |
Responses
| Status | Description |
|---|---|
201 | 성공 |
400 | 오류 |
401 | UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다. |
403 | Origin 검사 실패 또는 인증 대기 Organization 사용 거부입니다. |
404 | 오류 |
405 | 오류 |
409 | 오류 또는 ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다. |
413 | 오류 |
415 | 오류 |
422 | 오류 |
500 | 오류 |
201 response body
Type: Topic
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | |
summary | string | Yes | 목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다. |
description | string | Yes | |
partition_count | integer | null | Yes | |
cleanup_policy | any[] | null | Yes | |
time_retention_ms | integer | null | Yes | |
retention_order_description | string | Yes | |
external_references | Kafka.ExternalReference[] | Yes | |
message_definitions | MessageDefinition[] | Yes | |
usages | Usage[] | Yes | |
cluster_id | string | Yes | |
id | string | Yes | |
created_at | string(date-time) | Yes | |
updated_at | string(date-time) | Yes |
Topic 조회#
GET /api/kafka-topics/{id}
query·본문은 400입니다. If-None-Match가 약한 비교로 일치하면 304와 ETag를 반환합니다.
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | |
If-None-Match | header | string | No | 약한 비교, 태그 목록 또는 * |
Responses
| Status | Description |
|---|---|
200 | 성공 |
304 | 성공 |
400 | 오류 |
401 | UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다. |
403 | ORGANIZATION_UNVERIFIED: 현재 Organization 또는 Agent 토큰의 Organization이 인증 대기입니다. |
404 | 오류 |
405 | 오류 |
409 | ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다. |
500 | 오류 |
200 response body
Type: Topic
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | |
summary | string | Yes | 목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다. |
description | string | Yes | |
partition_count | integer | null | Yes | |
cleanup_policy | any[] | null | Yes | |
time_retention_ms | integer | null | Yes | |
retention_order_description | string | Yes | |
external_references | Kafka.ExternalReference[] | Yes | |
message_definitions | MessageDefinition[] | Yes | |
usages | Usage[] | Yes | |
cluster_id | string | Yes | |
id | string | Yes | |
created_at | string(date-time) | Yes | |
updated_at | string(date-time) | Yes |
Topic 전체 수정#
PUT /api/kafka-topics/{id}
Topic 본문은 4194304바이트 이하(초과 413)입니다. If-Match는 단일 강한 태그가 필수이며 누락 428·형식 오류 400·불일치 412입니다.
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | |
If-Match | header | string | Yes | 단일 강한 태그, 누락 428 |
Origin | header | string | No | 세션 쿠키로 인증한 상태 변경 요청에서 필수이며 서버 origin과 같아야 합니다. Bearer 토큰 요청에는 적용하지 않습니다. |
Request body
application/json · Required: Yes
Type: TopicUpdate
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | |
summary | string | Yes | 목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다. |
description | string | Yes | |
partition_count | integer | null | Yes | |
cleanup_policy | any[] | null | Yes | |
time_retention_ms | integer | null | Yes | |
retention_order_description | string | Yes | |
external_references | Kafka.ExternalReference[] | Yes | |
message_definitions | MessageDefinition[] | Yes | |
usages | UsageInput[] | Yes |
Responses
| Status | Description |
|---|---|
200 | 성공 |
400 | 오류 |
401 | UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다. |
403 | Origin 검사 실패 또는 인증 대기 Organization 사용 거부입니다. |
404 | 오류 |
405 | 오류 |
409 | 오류 또는 ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다. |
412 | 오류 |
413 | 오류 |
415 | 오류 |
422 | 오류 |
428 | 오류 |
500 | 오류 |
200 response body
Type: Topic
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | |
summary | string | Yes | 목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다. |
description | string | Yes | |
partition_count | integer | null | Yes | |
cleanup_policy | any[] | null | Yes | |
time_retention_ms | integer | null | Yes | |
retention_order_description | string | Yes | |
external_references | Kafka.ExternalReference[] | Yes | |
message_definitions | MessageDefinition[] | Yes | |
usages | Usage[] | Yes | |
cluster_id | string | Yes | |
id | string | Yes | |
created_at | string(date-time) | Yes | |
updated_at | string(date-time) | Yes |
Topic 삭제#
DELETE /api/kafka-topics/{id}
query·본문은 400입니다. If-Match는 단일 강한 태그가 필수이며 누락 428·형식 오류 400·불일치 412입니다.
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | |
If-Match | header | string | Yes | 단일 강한 태그, 누락 428 |
Origin | header | string | No | 세션 쿠키로 인증한 상태 변경 요청에서 필수이며 서버 origin과 같아야 합니다. Bearer 토큰 요청에는 적용하지 않습니다. |
Responses
| Status | Description |
|---|---|
204 | 성공 |
400 | 오류 |
401 | UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다. |
403 | Origin 검사 실패 또는 인증 대기 Organization 사용 거부입니다. |
404 | 오류 |
405 | 오류 |
409 | ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다. |
412 | 오류 |
428 | 오류 |
500 | 오류 |
현재 Organization 전체 Topic 조회#
GET /api/kafka-topics
현재 Organization의 default Workspace 안의 모든 Cluster 소속 Topic을 조회합니다. cluster_id를 포함한 기존 객체 배열을 반환합니다. q·sort·page·per_page는 다른 Catalog 목록과 같은 공통 목록 규칙을 따릅니다. 페이지 옵션을 생략하면 전체 배열을 반환합니다. 쓰기는 지원하지 않습니다(Allow: GET).
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
q | query | string | No | 앞뒤 U+0020 제거, 대소문자 구분 리터럴 부분 검색(name·summary·description 중 하나라도 일치하면 포함) |
sort | query | string | No | 생략 시 기존 기본 순서(name 오름차순, ID 오름차순) 유지 Values: name, -name |
page | query | integer | No | page·per_page 중 하나라도 있으면 페이지 모드. 생략 시 1 |
per_page | query | integer | No | 생략 시 100, 최대 500 |
Responses
| Status | Description |
|---|---|
200 | 성공. 페이지 모드에서만 X-Pagination-* 헤더를 반환합니다. |
400 | 오류 |
401 | UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다. |
403 | ORGANIZATION_UNVERIFIED: 현재 Organization 또는 Agent 토큰의 Organization이 인증 대기입니다. |
405 | 지원하지 않는 Method. HEAD 응답에는 본문이 없습니다. |
409 | ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다. |
500 | 오류 |
200 response body
An array (Topic[]). The table lists item fields.
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | |
summary | string | Yes | 목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다. |
description | string | Yes | |
partition_count | integer | null | Yes | |
cleanup_policy | any[] | null | Yes | |
time_retention_ms | integer | null | Yes | |
retention_order_description | string | Yes | |
external_references | Kafka.ExternalReference[] | Yes | |
message_definitions | MessageDefinition[] | Yes | |
usages | Usage[] | Yes | |
cluster_id | string | Yes | |
id | string | Yes | |
created_at | string(date-time) | Yes | |
updated_at | string(date-time) | Yes |
사용 설명 한 항목 추가 또는 교체#
PUT /api/kafka-topics/{topic_id}/usages/{id}
Topic 상세 ETag가 필수입니다. 같은 ID는 교체, 없는 ID는 배열 끝에 추가합니다. 같은 ID·정규화된 내용이면 시각·revision을 유지합니다. stale ETag는 내용 일치보다 먼저 412로 거부합니다. 성공은 최신 Topic이며 ETag는 상세 GET으로 다시 읽습니다.
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
topic_id | path | string | Yes | |
id | path | string | Yes | |
If-Match | header | string | Yes | 단일 강한 태그, 누락 428 |
Origin | header | string | No | 세션 쿠키로 인증한 상태 변경 요청에서 필수이며 서버 origin과 같아야 합니다. Bearer 토큰 요청에는 적용하지 않습니다. |
Request body
application/json · Required: Yes
UTF-8 JSON 64 KiB 이하. ID는 본문 대신 경로에 지정합니다.
Type: UsageBody
| Name | Type | Required | Description |
|---|---|---|---|
direction | any | Yes | Values: producer, consumer |
application_name | string | Yes | |
description | string | Yes | |
consumer_group | string | null | Yes | |
service_id | string | null | No | 선택적 사용 Service 참조. 현재 Organization의 Service ID이며 생략·null은 미연결입니다. 없는 Service는 422 service_id / not_found입니다. application_name에서 추정해 연결하지 않습니다. |
Responses
| Status | Description |
|---|---|
200 | 성공 |
400 | 오류 |
401 | UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다. |
403 | Origin 검사 실패 또는 인증 대기 Organization 사용 거부입니다. |
404 | 오류 |
405 | 오류 |
409 | 오류 또는 ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다. |
412 | 오류 |
413 | 오류 |
415 | 오류 |
422 | 오류 |
428 | 오류 |
500 | 오류 |
200 response body
Type: Topic
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | |
summary | string | Yes | 목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다. |
description | string | Yes | |
partition_count | integer | null | Yes | |
cleanup_policy | any[] | null | Yes | |
time_retention_ms | integer | null | Yes | |
retention_order_description | string | Yes | |
external_references | Kafka.ExternalReference[] | Yes | |
message_definitions | MessageDefinition[] | Yes | |
usages | Usage[] | Yes | |
cluster_id | string | Yes | |
id | string | Yes | |
created_at | string(date-time) | Yes | |
updated_at | string(date-time) | Yes |
사용 설명 한 항목 삭제#
DELETE /api/kafka-topics/{topic_id}/usages/{id}
Topic 상세 ETag가 필수입니다. 항목이 이미 없으면 최신 ETag에서 no-op입니다. stale ETag는 412입니다. 성공은 최신 Topic이며 ETag는 상세 GET으로 다시 읽습니다.
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
topic_id | path | string | Yes | |
id | path | string | Yes | |
If-Match | header | string | Yes | 단일 강한 태그, 누락 428 |
Origin | header | string | No | 세션 쿠키로 인증한 상태 변경 요청에서 필수이며 서버 origin과 같아야 합니다. Bearer 토큰 요청에는 적용하지 않습니다. |
Responses
| Status | Description |
|---|---|
200 | 성공 |
400 | 오류 |
401 | UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다. |
403 | Origin 검사 실패 또는 인증 대기 Organization 사용 거부입니다. |
404 | 오류 |
405 | 오류 |
409 | 오류 또는 ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다. |
412 | 오류 |
428 | 오류 |
500 | 오류 |
200 response body
Type: Topic
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | |
summary | string | Yes | 목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다. |
description | string | Yes | |
partition_count | integer | null | Yes | |
cleanup_policy | any[] | null | Yes | |
time_retention_ms | integer | null | Yes | |
retention_order_description | string | Yes | |
external_references | Kafka.ExternalReference[] | Yes | |
message_definitions | MessageDefinition[] | Yes | |
usages | Usage[] | Yes | |
cluster_id | string | Yes | |
id | string | Yes | |
created_at | string(date-time) | Yes | |
updated_at | string(date-time) | Yes |
Topic 생성 후보 사전 검증#
POST /api/messaging-clusters/{cluster_id}/topics/validate
실제 저장과 같은 본문·인증·검사 순서를 사용하며 저장하지 않습니다. 성공은 관찰 시점의 유효성으로 저장 성공·ID 예약·충돌 방지를 보장하지 않습니다. ETag·Location은 반환하지 않습니다. 검증 성공 전후 Catalog·자식 데이터·revision·updated_at은 유지되며, SELECT FOR UPDATE 잠금이 발생할 수 있습니다.
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
cluster_id | path | string | Yes | |
Origin | header | string | No | 세션 쿠키로 인증한 상태 변경 요청에서 필수이며 서버 origin과 같아야 합니다. Bearer 토큰 요청에는 적용하지 않습니다. |
Request body
application/json · Required: Yes
Type: TopicCreate
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | |
summary | string | No | 목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다. |
description | string | No | |
partition_count | integer | null | No | |
cleanup_policy | any[] | null | No | |
time_retention_ms | integer | null | No | |
retention_order_description | string | No | |
external_references | Kafka.ExternalReference[] | No | |
message_definitions | MessageDefinition[] | No | |
usages | UsageInput[] | No |
Responses
| Status | Description |
|---|---|
200 | 저장 없는 검증 성공 |
400 | 오류 |
401 | UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다. |
403 | Origin 검사 실패 또는 인증 대기 Organization 사용 거부입니다. |
404 | 오류 |
405 | 오류 |
409 | 오류 또는 ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다. |
413 | 오류 |
415 | 오류 |
422 | 오류 |
500 | 오류 |
200 response body
Type: ValidationResult
| Name | Type | Required | Description |
|---|---|---|---|
valid | true | Yes | |
operation | string | Yes | Values: create, update |
Topic 수정 후보 사전 검증#
PUT /api/kafka-topics/{id}/validate
실제 저장과 같은 본문·인증·검사 순서를 사용하며 저장하지 않습니다. 성공은 관찰 시점의 유효성으로 저장 성공·ID 예약·충돌 방지를 보장하지 않습니다. ETag·Location은 반환하지 않습니다. 검증 성공 전후 Catalog·자식 데이터·revision·updated_at은 유지되며, SELECT FOR UPDATE 잠금이 발생할 수 있습니다.
Authentication: Session cookie or Agent token
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
id | path | string | Yes | |
If-Match | header | string | Yes | 단일 강한 태그, 누락 428 |
Origin | header | string | No | 세션 쿠키로 인증한 상태 변경 요청에서 필수이며 서버 origin과 같아야 합니다. Bearer 토큰 요청에는 적용하지 않습니다. |
Request body
application/json · Required: Yes
Type: TopicUpdate
| Name | Type | Required | Description |
|---|---|---|---|
name | string | Yes | |
summary | string | Yes | 목록·테이블에 한 줄로 표시하는 핵심 요약입니다. 최대 120 Unicode 코드 포인트이며 앞뒤 공백을 보존합니다. 줄바꿈·탭 등 제어 문자는 거부합니다. 빈 문자열은 요약 없음입니다. 상세 설명은 description에 기록합니다. |
description | string | Yes | |
partition_count | integer | null | Yes | |
cleanup_policy | any[] | null | Yes | |
time_retention_ms | integer | null | Yes | |
retention_order_description | string | Yes | |
external_references | Kafka.ExternalReference[] | Yes | |
message_definitions | MessageDefinition[] | Yes | |
usages | UsageInput[] | Yes |
Responses
| Status | Description |
|---|---|
200 | 저장 없는 검증 성공 |
400 | 오류 |
401 | UNAUTHENTICATED: 세션·토큰이 없거나 만료·폐기되었습니다. |
403 | Origin 검사 실패 또는 인증 대기 Organization 사용 거부입니다. |
404 | 오류 |
405 | 오류 |
409 | 오류 또는 ORGANIZATION_REQUIRED: 세션에 현재 Organization이 없습니다. |
412 | 오류 |
413 | 오류 |
415 | 오류 |
422 | 오류 |
428 | 오류 |
500 | 오류 |
200 response body
Type: ValidationResult
| Name | Type | Required | Description |
|---|---|---|---|
valid | true | Yes | |
operation | string | Yes | Values: create, update |