Pub/Sub API

Common error codes

Response Error Syntax

{
    "error": {
        "code": int,
        "message": string
    }
}

// Example
{
    "error": {
        "code": 3,
        "message": "you have passed an invalid ack ID to the service (ack_id=MTZBRklHTVZTREZTJEpTLkFQSQ==)"
    }
}

Error messages and troubleshooting

Error Code	HTTP Code	Response details and solutions
3 (INVALID_ARGUMENT)	400	Invalid request The request is invalid; a required argument may be missing, exceeds limits, or has an invalid value. Solution: Check the error message and retry the request.
9 (FAILED_PRECONDITION)	400	Failed precondition Certain conditions must be met before this operation can proceed. Solution: Verify the request and retry.
7 (PERMISSION_DENIED)	403	Permission denied The certification is invalid. Solution: Obtain the required permissions and retry.
5 (NOT_FOUND)	404	Topic or subscription not found The referenced topic or subscription was not found. In JSON requests, this may also occur if the URL path is incorrect. For publish and pull operations, allow a few seconds for object creation propagation. Solution: If the resource was recently created, retry the request or ensure the topic/subscription exists before retrying.
13 (INTERNAL)	500	Internal server error This error should not occur. If it does, please report it to cloud support. The issue is likely transient. Solution: Retry the request.
14 (UNAVAILABLE)	503	Internal server error This error should not occur. If it does, please report it to cloud support. The issue is likely transient. Solution: Retry the request.

Topics

The following APIs are related to topics.

Create topic

Creates a topic with the specified name.

API call method

Method	URI
PUT	{endpoint-url}/v1/domains/{domain-id}/projects/{project-id}/topics/{topic-name}

Path	Type	Required	Description
domain-id	string	Required	Organization ID of the project
project-id	string	Required	Project ID in KakaoCloud
topic-name	string	Required	Name of the topic

Request header

Request	Type	Required	Description
Credential-ID	string	Required	Access key ID
Credential-Secret	string	Required	Secret access key

Request Body

Create topic Request Body

{
    "topic":{
        "description": "topic description",
        "messageRetentionDuration": "604800s"
    }
}

Response elements

Field	Type	Required	Description
description	string	Optional	Description of the topic
messageRetentionDuration	string	Optional	Message retention period - Default: 604800s (7 days)

Response body

Create Topic Response Body

{
    "id": string,
    "domain": string,
    "project": string,
    "name": string,
    "messageRetentionDuration": string,
    "subscriptionCount": int,
    "description": string,
    "creator": string,
    "createdAt": string
}

Response Elements

Response	Type	Description	Output Only
id	string	ID of the topic	O
domain	string	ID of the organization containing the topic
project	string	ID of the project containing the topic
name	string	Name of the topic
messageRetentionDuration	string	Message retention period of the topic
subscriptionCount	int	Number of subscriptions linked to the topic	O
description	string	Description of the topic
creator	string	Creator of the topic	O
createdAt	timestamp	Time when the topic was created	O

Retrieve topic list

Fetches the list of topics created in a project.

API call method

Method	URI
GET	{endpoint-url}/v1/domains/{domain-id}/projects/{project-id}/topics

Path	Type	Required	Description
domain-id	string	Required	ID of the organization containing the project
project-id	string	Required	Project ID in KakaoCloud

Request header

Request	Type	Required	Description
Credential-ID	string	Required	Access key ID
Credential-Secret	string	Required	Secret access key

Query parameters

Request	Type	Description
pageSize	int	Number of items to retrieve per request
pageToken	string	Token to fetch the next page of results

Response body

Retrieve topic list Response Body

{
    "topics": [
        {
             object (Topic)
        }
    ],
    "nextPageToken": string
}

//object (Topic) Example
{
    "id": string,
    "domain": string,
    "project": string,
    "name": string,
    "messageRetentionDuration": string,
    "subscriptionCount": int,
    "description": string,
    "creator": string,
    "createdAt": string
}

Response Elements

Field	Type	Description
topics	Object Array (Topic)	List of topics and their details
nextPageToken	string	Token to fetch the next page of topics

Object Array (Topic)

Field	Type	Description	Output Only
id	string	ID of the topic	O
domain	string	ID of the organization containing the topic
project	string	ID of the project containing the topic
name	string	Name of the topic
messageRetentionDuration	string	Message retention duration of the topic
subscriptionCount	int	Number of subscriptions linked to the topic	O
description	string	Description of the topic
creator	string	Creator of the topic	O
createdAt	timestamp	Time when the topic was created	O

Retrieve topic details

Fetches detailed information about a specific topic.

API call method

Method	Request URL
GET	{endpoint-url}/v1/domains/{domain-id}/projects/{project-id}/topics/{topic-name}

Path	Type	Required	Description
domain-id	string	Required	ID of the organization containing the project
project-id	string	Required	Project ID in KakaoCloud
topic-name	string	Required	Name of the topic

Request header

Request	Type	Required	Description
Credential-ID	string	Required	Access key ID
Credential-Secret	string	Required	Secret access key

Response body

Retrieve Topic Details Response Body

{
    "id": string,
    "domain": string,
    "project": string,
    "name": string,
    "messageRetentionDuration": string,
    "subscriptionCount": int,
    "description": string,
    "creator": string,
    "createdAt": string
}

Response Elements

Field	Type	Description	Output Only
id	string	ID of the topic	O
domain	string	ID of the organization containing the topic
project	string	ID of the project containing the topic
name	string	Name of the topic
messageRetentionDuration	string	Message retention duration of the topic
subscriptionCount	int	Number of subscriptions linked to the topic	O
description	string	Description of the topic
creator	string	Creator of the topic	O
createdAt	timestamp	Time when the topic was created	O

Publish message

Sends one or more messages to a topic.

API call method

Method	Request URL
POST	{endpoint-url}/v1/domains/{domain-id}/projects/{project-id}/topics/{topic-name}/publish

Path	Type	Required	Description
domain-id	string	Required	ID of the organization containing the project
project-id	string	Required	Project ID in KakaoCloud
topic-name	string	Required	Name of the topic

Request header

Request	Type	Required	Description
Credential-ID	string	Required	Access key ID
Credential-Secret	string	Required	Secret access key

Request body

Publish Message Request Body

{
  "messages": [
    {
      "data": "66mU7Iuc7KeAIOqyjOyLnCDthYzsiqTtirjsnoXri4jri6Qu",
      "attributes": {
        "key1": "value1",
        "key2": "value2"
      }
    },
    {
      "data": "message-2"
    }
  ]
}

Request Elements

Request	Type	Required	Description
messages	Object Array	Required	List of messages to send to the topic - Max: 100
message[].data	string	Required (if attributes are absent)	Message content - Max size: 1 MiB ⚠️ Note: Must be Base64-encoded.
message[].attributes	map [string : string]	Required (if data is absent)	Message attributes - Max count: 100 - Key: 1~256 characters - Value: 1~1024 characters - Total size of Key and Value must not exceed 60 KiB. ⚠️ Note: Keys starting with kakaoc are not allowed.

Response body

Publish Message Response Body

{
    "messageIds": [
        string,
        string
    ]
}

Response Elements

Response	유형	설명
messageIds	string array	메시지 별로 발급된 고유 ID

Response	Type	Description
messageIds	string array	Unique ID assigned to each message

Modify topic

Modify the description, message retention period, and other properties of a topic. The message retention period can only be extended beyond the previously set value.
For user-created topics, the retention period can be extended up to 7 days, while Default-Topics can be extended up to 31 days.

API call method

Method	Request URL
PATCH	{endpoint-url}/v1/domains/{domain-id}/projects/{project-id}/topics/{topic-name}

Path	Type	Required	Description
domain-id	string	Required	ID of the organization containing the project
project-id	string	Required	Project ID in KakaoCloud
topic-name	string	Required	Name of the topic

Request header

Request	Type	Required	Description
Credential-ID	string	Required	Access key ID
Credential-Secret	string	Required	Secret access key

Request body

Modify Topic Request Body

{
  "topic": {
    "description": "topic description",
    "messageRetentionDuration": "604800s"
  },
  "updateMask": "messageRetentionDuration,description"
}

Request Elements

Request	Type	Required	Description
topic.description	string	Required	Description of the topic
topic.messageRetentionDuration	string	Optional (Required if included in updateMask)	Message retention period - Can only be extended beyond the previously set value (in seconds)
updateMask	string	Required	List of fields to update - Separated by commas (,)

Response body

Modify Topic Response Body

{
        object (Topic) // Topic details
}

// object (Topic) Example
{
    "id": string,
    "domain": string,
    "project": string,
    "name": string,
    "messageRetentionDuration": string,
    "subscriptionCount": int,
    "description": string,
    "creator": string,
    "createdAt": string
}

Response Elements

Response	Type	Description	Output Only
id	string	ID of the topic	O
domain	string	ID of the organization containing the topic
project	string	ID of the project containing the topic
name	string	Name of the topic
messageRetentionDuration	string	Message retention duration of the topic
subscriptionCount	int	Number of subscriptions linked to the topic	O
description	string	Description of the topic
creator	string	Creator of the topic	O
createdAt	timestamp	Time when the topic was created	O

Delete topic

Deletes a topic with the specified name.

Caution

Deleting a topic will also delete all its associated subscriptions.

API call method

Method	URI
DELETE	{endpoint-url}/v1/domains/{domain-id}/projects/{project-id}/topics/{topic-name}

Path	Type	Required	Description
domain-id	string	Required	ID of the organization containing the project
project-id	string	Required	Project ID in KakaoCloud
topic-name	string	Required	Name of the topic

Request header

Request	Type	Required	Description
Credential-ID	string	Required	Access key ID
Credential-Secret	string	Required	Secret access key

Retrieve subscriptions of a topic

Fetches a list of subscriptions linked to a topic.

API call method

Method	URI
GET	{endpoint-url}/v1/domains/{domain-id}/projects/{project-id}/topics/{topic-name}/subscriptions

Path	Type	Required	Description
domain-id	string	Required	ID of the organization containing the project
project-id	string	Required	Project ID in KakaoCloud
topic-name	string	Required	Name of the topic

Request header

Request	Type	Required	Description
Credential-ID	string	Required	Access key ID
Credential-Secret	string	Required	Secret access key

Query parameters

Request	Type	Description
pageSize	int	Number of items to retrieve per request
pageToken	string	Token to fetch the next page of results

Response body

Retrieve Subscriptions of a Topic Response Body

{
    "subscriptions": [
        string
    ],
    "nextPageToken": string
}

Response Elements

Field	Type	Description
subscriptions	string Array	List of subscription names linked to the topic
nextPageToken	string	Token to fetch the next page of subscription results

Subscription

The following APIs are related to subscriptions.

Create subscription

Creates a subscription with the specified name.

API call method

Method	URI
PUT	{endpoint-url}/v1/domains/{domain-id}/projects/{project-id}/subscriptions/{sub-name}

Path	Type	Required	Description
domain-id	string	Required	ID of the organization containing the project
project-id	string	Required	Project ID in KakaoCloud
sub-name	string	Required	Name of the subscription

Request body

Create Subscription Request Body

{
    "subscription":{
        "topic": "topic-1",
        // For creating a subscription of type Push
        "pushConfig": {
            object (PushConfig)
        },
        // For creating a subscription of type Object Storage
        "objectStorageConfig": {
            object (ObjectStorageConfig)
        },
        "ackDeadlineSeconds": 30,
        "messageRetentionDuration": "604800s",
        "maxDeliveryAttempt": 1
    }
}

Request Elements

Request	Type	Required	Description
subscription.topic	string	Required	Name of the topic to associate with the subscription
subscription.pushConfig	Object (PushConfig)	Optional	PushSubscription details - Endpoint Message: Object (PushEndpointMessage) - If no endpoint is set, the subscription will default to Pull type.
subscription.objectStorageConfig	Object (ObjectStorageConfig)	Optional	ObjectStorageSubscription details - Cannot be used together with pushConfig
subscription.messageRetentionDuration	int	Optional	Message retention period - Default: Topic's messageRetentionDuration (specified in seconds)
subscription.maxDeliveryAttempt	string	Optional	Number of message retries - Default: -1 (Unlimited)
subscription.ackDeadlineSeconds	int	Optional	Time Pub/Sub waits before resending a message to the Subscriber - Default: 10s (in seconds) - If the subscriber does not acknowledge the message within the ackDeadline, it will be resent.

PushConfig

PushConfig

{
    "pushEndpoint": string
    "pushBatchSize": int
}

Field	Type	Description
pushEndpoint	string	Endpoint URL (*Applicable only for Push Subscriptions)
pushBatchSize	int	Message batch size for Push subscriptions - Default: 1 - Max: 100

ObjectStorageConfig

ObjectStorageConfig

{
    "bucket": string,
    "exportIntervalMinutes": int,
    "filePrefix": string,
    "fileSuffix": string,
    "channelCount": int,
    "maxChannelCount": int,
    "isExportEnabled": bool
}

Field	Type	Description	Output Only
bucket	string	Name of the Object Storage bucket
exportIntervalMinutes	int	Interval for saving files to Object Storage
filePrefix	string	The prefix of the file stored in Object Storage - Certain special characters (\ : * ? ” < > |) are not allowed, and the prefix cannot start with a slash ('/') - Consecutive slashes ('//') are not allowed - The combined length of the prefix and suffix must not exceed 200 bytes
fileSuffix	string	The suffix of the file stored in Object Storage - Certain special characters (\ : * ? ” < > |) are not allowed - Consecutive slashes ('//') are not allowed
channelCount	int	Number of configured export channels
maxChannelCount	int	Maximum number of channels that can be created * Only returned in Subscription Get requests (not in List requests)	O
isExportEnabled	bool	Indicates whether export is enabled	O

Response body

Create Subscription Response Body

{
    "id": string,
    "name": string,
    "domain": string,
    "project": string,
    "topicId": string,
    "topic": string,
    "ackDeadlineSeconds": string,
    "messageRetentionDuration": string,
    "maxDeliveryAttempt": int,
    "status": string,
    "subscriptionType": string,
    "pushConfig": {
        object (PushConfig)
    },
    "objectStorageConfig": {
        object (ObjectStorageConfig)
    },
    "unprocessedMessageCount": int,
    "creator": string,
    "createdAt": string
}

Response Elements

Response	Type	Description	Output Only
id	string	ID of the subscription	O
name	string	Name of the subscription
domain	string	Domain ID linked to the subscription
project	string	Project ID linked to the subscription
topicId	string	ID of the topic linked to the subscription	O
topic	string	Name of the topic linked to the subscription
ackDeadlineSeconds	int	Time Pub/Sub waits before resending a message to the Subscriber
messageRetentionDuration	string	Message retention duration for the subscription
maxDeliveryAttempt	int	Maximum number of message retry attempts - -1 (default): Unlimited - 1~100
status	string	Status of the subscription	O
subscriptionType	string	Type of subscription - PULL, PUSH, OBJECT_STORAGE	O
pushConfig	Object (PushConfig)	Endpoint settings for Push type subscriptions
objectStorageConfig	Object (ObjectStorageConfig)	Configuration settings for Object Storage type subscriptions
unprocessedMessageCount	int	Current number of unprocessed messages in the subscription	O
creator	string	Creator of the subscription	O
createdAt	timestamp	Time when the subscription was created	O

Retrieve subscription list

Fetches the list of subscriptions created in a project.

API call method

Method	URI
GET	{endpoint-url}/v1/domains/{domain-id}/projects/{project-id}/subscriptions

Path	Type	Required	Description
domain-id	string	Required	ID of the organization containing the project
project-id	string	Required	Project ID in KakaoCloud

Request header

Request	Type	Required	Description
Credential-ID	string	Required	Access key ID
Credential-Secret	string	Required	Secret access key

Query parameters

Request	Type	Description
pageSize	int	Number of items to retrieve per request
pageToken	string	Token to fetch the next page of results

Response body

Retrieve Subscription List Response Body

{
    "subscriptions": [
        {
            Object (Subscription)
        }
    ],
    "nextPageToken": string
}

//Object (Subscription) Example
{
    "id": string,
    "name": string,
    "domain": string,
    "project": string,
    "topicId": string,
    "topic": string,
    "ackDeadlineSeconds": string,
    "messageRetentionDuration": string,
    "maxDeliveryAttempt": int,
    "status": string,
    "subscriptionType": string,
    "pushConfig": {
        object (PushConfig)
    },
    "objectStorageConfig": {
        object (ObjectStorageConfig)
    },
     "unprocessedMessageCount": int,
    "creator": string,
    "createdAt": string
}

Response Elements

Field	Type	Description
subscriptions	Object Array (Subscription)	List of subscriptions created in the project
nextPageToken	string	Token to fetch the next page of subscription results

Object Array (Subscription)

Field	Type	Description	Output Only
id	string	ID of the subscription	O
name	string	Name of the subscription
domain	string	Domain ID linked to the subscription
project	string	Project ID linked to the subscription
topicId	string	ID of the topic linked to the subscription	O
topic	string	Name of the topic linked to the subscription
ackDeadlineSeconds	int	Time Pub/Sub waits before resending a message to the subscriber
messageRetentionDuration	string	Message retention period for the subscription
maxDeliveryAttempt	int	Maximum number of message retry attempts - -1 (default): Unlimited - Range: 1~100
status	string	Status of the subscription	O
subscriptionType	string	Type of the subscription - PULL, PUSH, OBJECT_STORAGE	O
pushConfig	Object (PushConfig)	Endpoint settings for Push type subscriptions
objectStorageConfig	Object (ObjectStorageConfig)	Configuration settings for Object Storage type subscriptions
creator	string	Creator of the subscription	O
createdAt	timestamp	Time when the subscription was created	O

Retrieve subscription details

Fetches the details of a specific subscription.

API call method

Method	Request URL
GET	{endpoint-url}/v1/domains/{domain-id}/projects/{project-id}/subscriptions/{sub-name}

Path	Type	Required	Description
domain-id	string	Required	ID of the organization containing the project
project-id	string	Required	Project ID in KakaoCloud
sub-name	string	Required	Name of the subscription

Request header

Request	Type	Required	Description
Credential-ID	string	Required	Access key ID
Credential-Secret	string	Required	Secret access key

Response body

Retrieve Subscription Details Object (Subscription) Response Body

{
    "id": string,
    "name": string,
    "domain": string,
    "project": string,
    "topicId": string,
    "topic": string,
    "ackDeadlineSeconds": string,
    "messageRetentionDuration": string,
    "maxDeliveryAttempt": int,
    "status": string,
    "subscriptionType": string,
    "pushConfig": {
        object (PushConfig)
    },
    "objectStorageConfig": {
        object (ObjectStorageConfig)
    },
     "unprocessedMessageCount": int,
    "creator": string,
    "createdAt": string
}

Response Elements

Field	Type	Description	Output only
id	string	The id of the subscription	O
name	string	The name of the subscription
domain	string	The domain name associated with the subscription
project	string	The project name associated with the subscription
topicId	string	The id of the topic associated with the subscription	O
topic	string	The name of the topic associated with the subscription
ackDeadlineSeconds	int	The time pub/sub waits before resending a message to the subscriber
messageRetentionDuration	string	The message retention duration for the subscription
maxDeliveryAttempt	int	The number of times a message is retried - -1(default): unlimited - configurable between 1 and 100
status	string	The status of the subscription	O
subscriptionType	string	The type of subscription - PULL, PUSH, OBJECT_STORAGE	O
pushConfig	object (PushConfig)	Endpoint configuration for push-type subscriptions
objectStorageConfig	object (ObjectStorageConfig)	Property settings for object storage subscription type
unprocessedMessageCount	int	The current number of unprocessed messages in the subscription	O
creator	string	The creator of the subscription	O
createdAt	timestamp	The timestamp of subscription creation	O

Update subscription (Patch)

Modifies the subscription's configuration.

API call method

Method	URI
PATCH	{endpoint-url}/v1/domains/{domain-id}/projects/{project-id}/subscriptions/{sub-name}

Path	Type	Required	Description
domain-id	string	required	The id of the organization the project belongs to
project-id	string	required	Project id in KakaoCloud
sub-name	string	required	The name of the subscription

Request Header

request	type	required	description
credential-id	string	required	Access key ID
credential-secret	string	required	Secret access key

Request Body

Update Subscription Object (Subscription) Request Body

{
    "subscription":{
        "pushConfig": {
            Object (PushConfig)
        },
         "objectStorageConfig": {
            Object (ObjectStorageConfig)
        },
        "ackDeadlineSeconds": 30,
        "messageRetentionDuration": "604800s",
        "maxDeliveryAttempt": 5
    },
    "updateMask": "ackDeadlineSeconds,messageRetentionDuration,pushConfig.pushEndpoint,maxDeliveryAttempt"
}

Field	Type	Required	Description
subscription.pushConfig	Object (PushConfig)	Optional	Endpoint URL (for Push subscriptions)
subscription.objectStorageConfig	Object (ObjectStorageConfig)	Optional	Bucket details (for Object Storage subscription type)
subscription.ackDeadlineSeconds	int	Optional	Time Pub/Sub waits before resending a message to the Subscriber
subscription.messageRetentionDuration	string	Optional	Message retention duration
subscription.maxDeliveryAttempt	int	Optional	Number of message retry attempts
updateMask	string	Required	List of fields to update - Separated by commas (,)

Response body

Update Subscription Object (Subscription) Response Body

{
    "id": string,
    "name": string,
    "domain": string,
    "project": string,
    "topicId": string,
    "topic": string,
    "ackDeadlineSeconds": string,
    "messageRetentionDuration": string,
    "maxDeliveryAttempt": int,
    "status": string,
    "subscriptionType": string,
    "pushConfig": {
        object (PushConfig)
    },
    "objectStorageConfig": {
        object (ObjectStorageConfig)
    },
     "unprocessedMessageCount": int,
    "creator": string,
    "createdAt": string
}

Response Elements

Field	Type	Description	Output Only
id	string	ID of the subscription	O
name	string	Name of the subscription
domain	string	Domain ID linked to the subscription
project	string	Project ID linked to the subscription
topicId	string	ID of the topic linked to the subscription	O
topic	string	Name of the topic linked to the subscription
ackDeadlineSeconds	int	Time Pub/Sub waits before resending a message to the subscriber
messageRetentionDuration	string	Message retention period for the subscription
maxDeliveryAttempt	int	Maximum number of message retry attempts - -1 (default): Unlimited - Range: 1~100
status	string	Status of the subscription	O
subscriptionType	string	Type of the subscription - PULL, PUSH, OBJECT_STORAGE	O
pushConfig	Object (PushConfig)	Endpoint settings for Push type subscriptions
objectStorageConfig	Object (ObjectStorageConfig)	Configuration settings for Object Storage type subscriptions
unprocessedMessageCount	int	Current number of unprocessed messages in the subscription	O
creator	string	Creator of the subscription	O
createdAt	timestamp	Time when the subscription was created	O

Delete subscription

Deletes a subscription with the specified name.

Method	URI
DELETE	{endpoint-url}/v1/domains/{domain}/projects/{project}/subscriptions/{sub-name}

Pull messages

Fetches messages. (*Supported only for Pull subscriptions.)

API call method

Method	URI
POST	{endpoint-url}/v1/domains/{domain-id}/projects/{project-id}/subscriptions/{sub-name}/pull

Path	Type	Required	Description
domain-id	string	Required	ID of the organization containing the project
project-id	string	Required	Project ID in KakaoCloud
sub-name	string	Required	Name of the subscription

Request header

Request	Type	Required	Description
Credential-ID	string	Required	Access key ID
Credential-Secret	string	Required	Secret access key

Request body

Pull Messages Request Body

{
  "maxMessages": 1,
  "waitTime": "100ms"
}

Request	Type	Required	Description
maxMessages	int	Required	Number of messages to fetch - Max: 100 ⚠️ If message size is large, fewer messages than requested may be received due to waitTime.
waitTime	string	Optional	Fetch wait time for messages - Default: 100ms - Max: 30s (specified in seconds)

Response body

Pull Messages Response Body

{
    "receivedMessages": [
        {
            object (ReceivedMessage)
        }
    ]
}

//object (ReceivedMessage) Example
{
    "ackId": string,
    "message": {
        object (PubsubMessage)
    },
    "deliveryAttempt": int
}

//// object (PubsubMessage) Example
{
     "data": string,
     "attributes": {
         string: string
         ...
     },
     "messageId": string,
     "publishTime": string
 }

Response Elements

Field	Type
receivedMessages	Object Array (ReceivedMessage)

ReceivedMessage

Field	Type	Description
ackId	string	ID used to perform specific actions (acknowledge, modifyAckDeadline) on the message
message	Object (PubsubMessage)	Message details
deliveryAttempt	int	Number of times the message has been redelivered

PubsubMessage

Field	Type	Description
data	string (required)	Content of the message, maximum size 1 MiB
attributes	map (key: string, value: string) (optional)	Attributes of the message, maximum of 100
messageId	string	Unique message ID, matches the ID assigned to the message in the Publish response
publishTime	string	Time the message was published ⚠️ Time: UTC format

Acknowledge message

Processes acknowledgment for a message using its ackId.

API call method

Method	URI
POST	{endpoint-url}/v1/domains/{domain-id}/projects/{project-id}/subscriptions/{sub-name}/acknowledge

Path	Type	Required	Description
domain-id	string	Required	ID of the organization containing the project
project-id	string	Required	Project ID in KakaoCloud
sub-name	string	Required	Name of the subscription

Request header

Field	Type	Required	Description
Credential-ID	string	Required	Access key ID
Credential-Secret	string	Required	Secret access key

Request body

Acknowledge Message Request Body

{
  "ackIds": ["ack-id-1"]
}

Request	Type	Required	Description
ackIds	string array	Required	List of ackIds for messages to be acknowledged

Response body

Acknowledge Message Response Body

{
    "failure": [
        {
            object (FailedAckID)
        }
    ]
}

//object (FailedAckID) Example
{
     "ackID": string,
     "error": object (Error)
}

Response Elements

Response	Type
failure	Object (FailedAckID)

FailedAckID

Field	Type	Description
ackID	string	Original ackId
error	string	Object(Error), contains error code and message

Modify message acknowledgment deadline

Extend or shorten the message acknowledgment deadline (Ack Deadline). Upon success, a new ackId is issued.

API call method

Method	URI
POST	{endpoint-url}/v1/domains/{domain-id}/projects/{project-id}/subscriptions/{sub-name}/modifyAckDeadline

Path	Type	Required	Description
domain-id	string	Required	ID of the organization containing the project
project-id	string	Required	Project ID in KakaoCloud
sub-name	string	Required	Name of the subscription

Request header

Field	Type	Required	Description
Credential-ID	string	Required	Access key ID
Credential-Secret	string	Required	Secret access key

Request body

Modify Acknowledgment Deadline Request Body

{
  "ackIds": ["ack-id-1"],
  "action": "extend"
}

Request	Type	Required	Description
ackIds	string Array	Required	List of ackIds for messages to modify the acknowledgment deadline
action	string	Required	Action to perform: - Extend: Extends the message usage time by the subscription's AckDeadline from now - Skip: Sets the message usage time to 0, allowing other clients to receive the message

Response body

Modify Acknowledgment Deadline Response Body

{
    "success": [
        {
            object (AckID)
        }
    ],
    "failure": [
        {
            object (FailedAckID)
        }
    ]
}

//object (AckID) Example
{
     "ackID": string,
     "reissuedAckID": string
 }

//object (FailedAckID) Example
{
     "ackID": string,
     "error": object (Error)
}

Response Elements

Response	Type	Description
success	Object (AckID)	List of successfully modified Ack IDs
failure	Object (FailedAckID)	List of failed Ack IDs

AckID

Field	Type	Description
ackID	string	Original acknowledgment ID
reissuedAckID	string	Newly issued acknowledgment ID

FailedAckID

Field	Type	Description
ackID	string	Original acknowledgment ID
error	string	Object (Error), including error code and description

Rewind messages (Seek)

Allows rewinding a subscription to a specific point in time, so all messages published after that point can be received again.

API call format

Method	URI
POST	{endpoint-url}/v1/domains/{domain-id}/projects/{project-id}/subscriptions/{sub-name}/seek

Path	Type	Required	Description
domain-id	string	Required	Organization ID of the project
project-id	string	Required	Project ID of KakaoCloud
sub-name	string	Required	Name of the subscription

Request Header

Header	Type	Required	Description
Credential-ID	string	Required	Access key ID
Credential-Secret	string	Required	Secret access key

Request Body

Seek Request Body

{
    "time": string
}

Request	Type	Required	Description
time	string	required	the time to rewind - Format: "2006-01-02T15:04:05+09:00", KST

Response body

No response body.