Skip to content
Cloud
Docs

Pub/Sub API reference

Durable project-scoped publish and subscribe delivery.

Published contracts: @socra/pubsub-api@0.0.2.

Base URL

https://pubsub.socra.cloud

Topics

A project-owned feed to which messages are published.

Create topic

POST/v1/projects/{project_id}/topics

Path parameters

project_idcustomrequired

Request body

namestringrequired
min length: 1 · max length: 128 · pattern: ^[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*$
retention_secondsintegeroptional
default: 86400 · min: 600 · max: 604800

Response

8 fields

idcustomrequired
project_idcustomrequired
namestringrequired
min length: 1 · max length: 128 · pattern: ^[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*$
resource_namestringrequired
status"active" | "deleted"required
retention_secondsintegerrequired
min: -9007199254740991 · max: 9007199254740991
created_atcustomrequired
updated_atcustomrequired

List topics

GET/v1/projects/{project_id}/topics

Path parameters

project_idcustomrequired

Query parameters

limitintegeroptional
min: 1 · max: 100
afterstringoptional

Response

2 fields

dataobject[]required
idcustomrequired
project_idcustomrequired
namestringrequired
min length: 1 · max length: 128 · pattern: ^[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*$
resource_namestringrequired
status"active" | "deleted"required
retention_secondsintegerrequired
min: -9007199254740991 · max: 9007199254740991
created_atcustomrequired
updated_atcustomrequired
has_morebooleanrequired

Get topic

GET/v1/projects/{project_id}/topics/{topic}

Path parameters

project_idcustomrequired
topicstringrequired
min length: 1 · max length: 128 · pattern: ^[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*$

Query parameters

No query parameters

Response

8 fields

idcustomrequired
project_idcustomrequired
namestringrequired
min length: 1 · max length: 128 · pattern: ^[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*$
resource_namestringrequired
status"active" | "deleted"required
retention_secondsintegerrequired
min: -9007199254740991 · max: 9007199254740991
created_atcustomrequired
updated_atcustomrequired

Update topic

PATCH/v1/projects/{project_id}/topics/{topic}

Path parameters

project_idcustomrequired
topicstringrequired
min length: 1 · max length: 128 · pattern: ^[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*$

Request body

retention_secondsintegeroptional
min: 600 · max: 604800

Response

8 fields

idcustomrequired
project_idcustomrequired
namestringrequired
min length: 1 · max length: 128 · pattern: ^[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*$
resource_namestringrequired
status"active" | "deleted"required
retention_secondsintegerrequired
min: -9007199254740991 · max: 9007199254740991
created_atcustomrequired
updated_atcustomrequired

Delete topic

DELETE/v1/projects/{project_id}/topics/{topic}

Path parameters

project_idcustomrequired
topicstringrequired
min length: 1 · max length: 128 · pattern: ^[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*$

Query parameters

No query parameters

Response

No response body

Topic bindings

A project permission to publish to or subscribe to a topic.

Create topic binding

POST/v1/projects/{project_id}/topics/{topic}/bindings

Path parameters

project_idcustomrequired
topicstringrequired
min length: 1 · max length: 128 · pattern: ^[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*$

Request body

project_idcustomrequired
role"publisher" | "subscriber"required

Response

5 fields

idcustomrequired
topicstringrequired
project_idcustomrequired
role"publisher" | "subscriber"required
created_atcustomrequired

List topic bindings

GET/v1/projects/{project_id}/topics/{topic}/bindings

Path parameters

project_idcustomrequired
topicstringrequired
min length: 1 · max length: 128 · pattern: ^[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*$

Query parameters

limitintegeroptional
min: 1 · max: 100
afterstringoptional

Response

2 fields

dataobject[]required
idcustomrequired
topicstringrequired
project_idcustomrequired
role"publisher" | "subscriber"required
created_atcustomrequired
has_morebooleanrequired

Delete topic binding

DELETE/v1/projects/{project_id}/topics/{topic}/bindings/{binding_id}

Path parameters

project_idcustomrequired
topicstringrequired
min length: 1 · max length: 128 · pattern: ^[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*$
binding_idcustomrequired

Query parameters

No query parameters

Response

No response body

Subscriptions

An independently acknowledged delivery stream from one topic.

Create subscription

POST/v1/projects/{project_id}/subscriptions

Path parameters

project_idcustomrequired

Request body

namestringrequired
min length: 1 · max length: 128 · pattern: ^[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*$
topicstringrequired
pattern: ^projects\/proj_[0-9a-hjkmnp-tv-z]{26}\/topics\/[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*$
ack_deadline_secondsintegeroptional
default: 60 · min: 10 · max: 600
retention_secondsintegeroptional
default: 86400 · min: 600 · max: 604800

Response

10 fields

idcustomrequired
project_idcustomrequired
namestringrequired
min length: 1 · max length: 128 · pattern: ^[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*$
resource_namestringrequired
topicstringrequired
pattern: ^projects\/proj_[0-9a-hjkmnp-tv-z]{26}\/topics\/[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*$
status"active" | "paused" | "deleted"required
ack_deadline_secondsintegerrequired
min: -9007199254740991 · max: 9007199254740991
retention_secondsintegerrequired
min: -9007199254740991 · max: 9007199254740991
created_atcustomrequired
updated_atcustomrequired

List subscriptions

GET/v1/projects/{project_id}/subscriptions

Path parameters

project_idcustomrequired

Query parameters

limitintegeroptional
min: 1 · max: 100
afterstringoptional

Response

2 fields

dataobject[]required
idcustomrequired
project_idcustomrequired
namestringrequired
min length: 1 · max length: 128 · pattern: ^[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*$
resource_namestringrequired
topicstringrequired
pattern: ^projects\/proj_[0-9a-hjkmnp-tv-z]{26}\/topics\/[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*$
status"active" | "paused" | "deleted"required
ack_deadline_secondsintegerrequired
min: -9007199254740991 · max: 9007199254740991
retention_secondsintegerrequired
min: -9007199254740991 · max: 9007199254740991
created_atcustomrequired
updated_atcustomrequired
has_morebooleanrequired

Get subscription

GET/v1/projects/{project_id}/subscriptions/{subscription}

Path parameters

project_idcustomrequired
subscriptionstringrequired
min length: 1 · max length: 128 · pattern: ^[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*$

Query parameters

No query parameters

Response

10 fields

idcustomrequired
project_idcustomrequired
namestringrequired
min length: 1 · max length: 128 · pattern: ^[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*$
resource_namestringrequired
topicstringrequired
pattern: ^projects\/proj_[0-9a-hjkmnp-tv-z]{26}\/topics\/[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*$
status"active" | "paused" | "deleted"required
ack_deadline_secondsintegerrequired
min: -9007199254740991 · max: 9007199254740991
retention_secondsintegerrequired
min: -9007199254740991 · max: 9007199254740991
created_atcustomrequired
updated_atcustomrequired

Update subscription

PATCH/v1/projects/{project_id}/subscriptions/{subscription}

Path parameters

project_idcustomrequired
subscriptionstringrequired
min length: 1 · max length: 128 · pattern: ^[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*$

Request body

status"active" | "paused"optional
ack_deadline_secondsintegeroptional
min: 10 · max: 600
retention_secondsintegeroptional
min: 600 · max: 604800

Response

10 fields

idcustomrequired
project_idcustomrequired
namestringrequired
min length: 1 · max length: 128 · pattern: ^[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*$
resource_namestringrequired
topicstringrequired
pattern: ^projects\/proj_[0-9a-hjkmnp-tv-z]{26}\/topics\/[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*$
status"active" | "paused" | "deleted"required
ack_deadline_secondsintegerrequired
min: -9007199254740991 · max: 9007199254740991
retention_secondsintegerrequired
min: -9007199254740991 · max: 9007199254740991
created_atcustomrequired
updated_atcustomrequired

Delete subscription

DELETE/v1/projects/{project_id}/subscriptions/{subscription}

Path parameters

project_idcustomrequired
subscriptionstringrequired
min length: 1 · max length: 128 · pattern: ^[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*$

Query parameters

No query parameters

Response

No response body

Publishers

Message publication operations.

Publish messages

POST/v1/projects/{project_id}/topics/{topic}/publish

Path parameters

project_idcustomrequired
topicstringrequired
min length: 1 · max length: 128 · pattern: ^[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*$

Request body

publisher_project_idcustomoptional
messagesobject[]required
min items: 1 · max items: 100
datastringrequired
max length: 10000000
attributesobjectoptional
default: {}
ordering_keystringoptional
max length: 1024

Response

1 field

message_idscustom[]required

Subscribers

Subscription delivery operations.

Pull messages

POST/v1/projects/{project_id}/subscriptions/{subscription}/pull

Path parameters

project_idcustomrequired
subscriptionstringrequired
min length: 1 · max length: 128 · pattern: ^[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*$

Request body

max_messagesintegeroptional
default: 10 · min: 1 · max: 100

Response

1 field

received_messagesobject[]required
ack_tokenstringrequired
delivery_attemptintegerrequired
min: 1 · max: 9007199254740991
messageobjectrequired
datastringrequired
max length: 10000000
attributesobjectrequired
default: {}
ordering_keystringoptional
max length: 1024
idcustomrequired
published_atcustomrequired

Acknowledge messages

POST/v1/projects/{project_id}/subscriptions/{subscription}/acknowledge

Path parameters

project_idcustomrequired
subscriptionstringrequired
min length: 1 · max length: 128 · pattern: ^[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*$

Request body

ack_tokensstring[]required
min items: 1 · max items: 1000

Response

1 field

acknowledged_countintegerrequired
min: -9007199254740991 · max: 9007199254740991