Pub/Sub API

info

The creation and deletion of topics and subscriptions can only be done through the KakaoCloud Console.

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 and Solution
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 Something must be done in the system to allow this operation. Solution: Recheck the request.
7 (PERMISSION_DENIED)	403	Permission denied The certification is invalid. Solution: Obtain permission and retry.
5 (NOT_FOUND)	404	Topic or subscription not found The topic or subscription referenced has not been found. In the case of JSON requests, it may also happen if the URL path is not a correct REST path. For publish and pull operations, the propagation of an object creation may take a few seconds. Solution: If the resource was just created, retry the request or create the topic or subscription and try again.
13 (INTERNAL)	500	Internal server error This error indicates an internal server error; it should not occur. If this error occurs, please report to cloud support. The error should be transient. Solution: Retry the request.

Topic

The following APIs are related to topics.

Retrieve topic list

Retrieves the list of topics created in the project.

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 to which the project belongs.
project-id	String	Required	Project ID of 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	Integer	Number of items to retrieve in a single request.
pageToken	String	Token to fetch the next list.

Response syntax

Response Syntax

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

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

Response Elements

Response	Type	Description
topics	Object Array (Topic)	List of topics and information
nextPageToken	String	Token to retrieve the next set of topics

Object Array (Topic)

Response	Type	Description	Output Only
id	String	Topic ID	o
name	String	Topic name
description	String	Topic description
domain	String	ID of the organization that includes the topic
project	String	Project ID that includes the topic
messageRetentionDuration	String	Message retention duration of the topic
subscriptionCount	Integer	Number of subscriptions connected to the topic	o
creator	String	Creator of the topic	o
createdAt	timestamp	Creation time	o

Retrieve topic details

Retrieves detailed information on a specific topic.

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 to which the project belongs
project-id	String	Required	Project ID of KakaoCloud
topic-name	String	Required	Topic name

Request Header

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

Response Syntax

Response Syntax

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

Response Elements

Field	Type	Description	Output Only
id	String	Topic ID	o
name	String	Topic name
description	String	Topic description
domain	String	ID of the organization that includes the topic
project	String	Project ID that includes the topic
messageRetentionDuration	String	Message retention duration of the topic
subscriptionCount	Integer	Number of subscriptions connected to the topic	o
creator	String	Creator of the topic	o
createdAt	timestamp	Creation time	o

Publish message

Sends one or more messages to the topic.

Request Syntax

Request Syntax

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

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 to which the project belongs
project-id	String	Required	Project ID of KakaoCloud
topic-name	String	Required	Topic name

Request header

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

Request elements

Request	Type	Required	Description
messages	Object Array	Required	List of messages to send to the topic - Max: 100
message.data	String	Required	Message content - Max size: 1 MiB - Either data or attributes must be included ⚠️ Note: Must be Base64 encoded
message.attributes	map [string : string]	Required	Message attributes - Max: 100 items - Key: 1~256 characters - Value: 1~1024 characters - The total size of Key and Value must not exceed 60KiB ⚠️ Note: Keys starting with kakaoc are not allowed

Response Syntax

Response Syntax

{
    "messageIds": [
        string,
        string
    ]
}

Response Elements

Response	Type	Description
messageIds	string Array	Unique ID issued for each message

Modify topic

You can modify the description, message retention duration, etc., of a topic. The message retention duration can only be extended beyond the originally set time. User-created topics can be modified up to 7 days, while default topics can be modified up to 31 days.

Request syntax

Request Syntax

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

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 to which the project belongs
project-id	String	Required	Project ID of KakaoCloud
topic-name	String	Required	Topic name

Request header

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

Request elements

Request	Type	Required	Description
topic.description	String	Required	Description of the topic
topic.messageRetentionDuration	String	Optional	Message retention duration - Can only be extended beyond the originally set time (in seconds)
updateMask	String	Required	List of fields to update - Separated by commas (,)

Response syntax

Update Topic Response Syntax

{
        object (Topic) // Topic details
}


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

Response Elements

Field	Type	Description	Output Only
id	String	Topic ID	o
name	String (required)	Topic name
description	String	Topic description
domain	String	ID of the organization that includes the topic
project	String	Project ID that includes the topic
messageRetentionDuration	String	Message retention duration of the topic
subscriptionCount	int	Number of subscriptions connected to the topic	o
creator	String	Creator of the topic	o
createdAt	timestamp	Creation time	o

Retrieve subscriptions of topic

Retrieves the list of subscriptions connected to the topic.

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 to which the project belongs
project-id	String	Required	Project ID of KakaoCloud
topic-name	String	Required	Topic name

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	Integer	Number of items to retrieve in a single request
pageToken	String	Token to fetch the next list

Response syntax

Response Syntax

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

Response Elements

Field	Type	Description
subscriptions	string Array	List of subscription names connected to the topic
nextPageToken	String	Token to fetch the next set of subscriptions

Subscription

The following APIs are related to subscriptions.

Retrieve subscription list

Retrieves the list of subscriptions created in the project.

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 to which the project belongs
project-id	String	Required	Project ID of 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	Integer	Number of items to retrieve in a single request
pageToken	String	Token to fetch the next list

Response syntax

Response Syntax

{
    "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,
    "pushConfig": {
        object (PushConfig)
    },
    "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 set of subscriptions

Object Array (Subscription)

Field	Type	Description	Output Only
id	String	Subscription ID	o
name	String	Subscription name
domain	String	Domain name to which the subscription is connected
project	String	Project name to which the subscription is connected
topicId	String	ID of the topic to which the subscription is connected	o
topic	String	Name of the topic to which the subscription is connected
ackDeadlineSeconds	int	Time that Pub/Sub waits before resending a message to the subscriber
messageRetentionDuration	String	Message retention duration of the subscription
maxDeliveryAttempt	int	Number of message resend attempts - -1 (default): Unlimited - Can be set from 1 to 100
status	String	Subscription status	o
pushConfig	Object (PushConfig)	Endpoint settings for a push-type subscription
creator	String	Creator of the subscription	o
createdAt	timestamp	Creation time of the subscription	o

PushConfig

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

Response	Type	Description
pushEndpoint	String	Endpoint URL (for Push Subscription)
pushBatchSize	int	Batch size of messages for the Push subscription - Default: 1 - Max: 100

Retrieve subscription details

Retrieves information on a specific subscription.

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 to which the project belongs
project-id	String	Required	Project ID of KakaoCloud
sub-name	String	Required	Subscription name

Request header

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

Response syntax

Response Syntax

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

Response Elements

Field	Type	Description	Output Only
id	String	Subscription ID	o
name	String	Subscription name
domain	String	Domain name to which the subscription is connected
project	String	Project name to which the subscription is connected
topicId	String	ID of the topic to which the subscription is connected	o
topic	String	Name of the topic to which the subscription is connected
ackDeadlineSeconds	int	Time that Pub/Sub waits before resending a message to the subscriber
messageRetentionDuration	String	Message retention duration of the subscription
maxDeliveryAttempt	int	Number of message resend attempts - -1 (default): Unlimited - Can be set from 1 to 100
status	String	Subscription status	o
pushConfig	Object (PushConfig)	Endpoint settings for a push-type subscription
unprocessedMessageCount	int	Number of unprocessed messages in the subscription	o
creator	String	Creator of the subscription	o
createdAt	timestamp	Creation time of the subscription	o

pushConfig

PushConfig

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

Response	Type	Description
pushEndpoint	String	Endpoint URL (for Push Subscription)
pushBatchSize	int	Batch size of messages for the Push subscription - Default: 1 - Max: 100

Update subscription (Patch)

Modifies the settings of a subscription.

Method

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

Path	Type	Required	Description
domain-id	String	Required	ID of the organization to which the project belongs
project-id	String	Required	Project ID of KakaoCloud
sub-name	String	Required	Subscription name

Request header

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

Request syntax

Request Syntax

{
  "subscription": {
    "pushConfig": {
      "pushEndpoint": "{Endpoint URL}"
    },
    "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 Subscription)
subscription.ackDeadlineSeconds	int	Optional	Time that Pub/Sub waits before resending a message to the subscriber - Default: 30
subscription.messageRetentionDuration	String	Optional	Message retention duration - Default: 7d
subscription.maxDeliveryAttempt	int	Optional	Number of message resend attempts - Default: Unlimited
updateMask	String	Required	List of fields to update - Separated by commas (,)

Response syntax

Response Syntax

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

Response Elements

Field	Type	Description	Output Only
id	String	Subscription ID	o
name	String	Subscription name
domain	String	Domain name to which the subscription is connected
project	String	Project name to which the subscription is connected
topicId	String	ID of the topic to which the subscription is connected	o
topic	String	Name of the topic to which the subscription is connected
ackDeadlineSeconds	int	Time that Pub/Sub waits before resending a message to the subscriber
messageRetentionDuration	String	Message retention duration of the subscription
maxDeliveryAttempt	int	Number of message resend attempts - -1 (default): Unlimited - Can be set from 1 to 100
status	String	Subscription status	o
pushConfig	Object (PushConfig)	Endpoint settings for a push-type subscription
unprocessedMessageCount	int	Number of unprocessed messages in the subscription	o
creator	String	Creator of the subscription	o
createdAt	timestamp	Creation time of the subscription	o

PushConfig

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

Field	Type	Description
pushEndpoint	String	Endpoint URL (for Push Subscription)
pushBatchSize	int	Batch size of messages for the Push subscription - Default: 1 - Max: 100

Pull messages

Retrieves messages.

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 to which the project belongs
project-id	String	Required	Project ID of KakaoCloud
sub-name	String	Required	Subscription name

Request header

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

Request syntax

Request Syntax

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

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

Response syntax

Response Syntax

{
    "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

Response	Type
receivedMessages	Object Array (ReceivedMessage)

ReceivedMessage

Fields	Type	Description
ackId	String	ID used to perform specific actions (acknowledge, modifyAckDeadline) on the message
message	Object (PubsubMessage)
deliveryAttempt	int	Number of times the message has been resent

Pubsub Message

Fields	Type	Description
data	String (required)	Message content, up to 1 MiB
attributes	map (key: string, value: string) (optional)	Message attributes, up to 100 items
messageId	String	Unique message ID, identical to the ID issued for each message in the Publish request response
publishTime	String	Time when the message was published

Acknowledge message

Acknowledges a message using its ackId.

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 to which the project belongs
project-id	String	Required	Project ID of KakaoCloud
sub-name	String	Required	Subscription name

Request header

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

Request syntax

Request Syntax

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

Request	Type	Required	Description
ackIds	String Array	Required	List of ackIds for the messages to be acknowledged

Response syntax

Response Syntax

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

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

Response Elements

Field	Type
failure	object (FailedAckID)

object (FailedAckID)

Fields	Type	Description
ackID	String	Original ack ID
error	String	Object(Error), error code and description

Modify message acknowledgement deadline

You can extend or shorten the message acknowledgement deadline (Ack Deadline). A new Ack ID is issued upon success.

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 to which the project belongs
project-id	String	Required	Project ID of KakaoCloud
sub-name	String	Required	Subscription name

Request Header

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

Request Syntax

Request Syntax

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

Request	Type	Required	Description
ackIds	String Array	Required	List of ackIds for the messages
action	String	Required	Action to take: either extend or skip

Response syntax

Response Syntax

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

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

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

Response Elements

Field	Type	Description
success	object (AckID)	List of successful Ack IDs
failure	object (FailedAckID)	List of failed Ack IDs

object (AckID)

Fields	Type	Description
ackID	String	Original Ack ID
reissuedAckID	String	New Ack ID

object (FailedAckID)

Fields	Type	Description
ackID	String	Original ack ID
error	String	Object(Error), error code and description

Seek messages

The seek function allows you to roll back a subscription to a specific time, enabling you to receive all messages from that point onward.

Method

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

Path	Type	Required	Description
domain-id	String	Required	ID of the organization to which the project belongs
project-id	String	Required	Project ID of KakaoCloud
sub-name	String	Required	Subscription name

Request header

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

Request syntax

Request Syntax

{
    "time": string
}

Request	Type	Required	Description
time	String	Required	Time to roll back to - Format: "2006-01-02T15:04:05+09:00", KST

Response body

No response value.