SelectPubNub REST API Documentation

Functions REST API

 
The Functions REST API is described in the Functions documentation.

Common REST Query String Parameters

The following parameters should be used on all REST calls being made to PubNub.

  • uuid – required - A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

  • auth – optional - A PAM (access control) token, to be used on PAM-enabled endpoints:

    • Publishing
    • Subscribing
    • History
    • Channel Group operations
  • signature – optional - Only to be used for PAM admin REST calls (grant, audit).

  • pnsdk – required - An identifier which uniquely identifies your client SDK. This should be of the format CompanyName-ProgrammingLanguageUsed/YourClientSDKVersion (e.g. CompanyABC-JS/1.0). Please contact support@pubnub.com for further information.

Common HTTP Request Headers

The following HTTP headers should be used across all PubNub REST requests.

  • Content-Encoding - When sending compressed, gzipped data via POST requests, set value as gzip

  • Content-Type - Always use application/json; charset=UTF-8 when sending JSON, and using UTF-8

  • Accept-Encoding - If your client supports gzip, set this value to gzip, if your client supports deflate, set this value to deflate, if it supports both, set this value to gzip, deflate and if it supports neither, omit this header altogether.

Common HTTP Status Codes

The following HTTP Status codes should be treated the same across all PubNub REST responses.

  • 200 – The REST call was successful. Refer to the detail usage by operation for more information on parsing the response.

  • 403 – The REST call was unsuccessful, due to a PAM (access control) issue. Try again, without an auth URL parameter, or with a different auth URL parameter.

Publish / Subscribe

Publish V1 via GET

Publish a message to a channel.

Publish v1 - Valid / Success Responses

Successful (HTTP Status 200) Publish() calls will always return a three-element array:

  • Array Element 0 - Integer – 1 or 0, where 1 is success, and 0 is error.

  • Array Element 1 - String – Description of the success or error, if available.

  • Array Element 2 - String – The current PubNub time expressed as a Timetoken, on success only.

A sample response from server [1,"Sent","14375189629170609"] contains the following fields:

  • The first element is an integer of value 1 representing success.

  • The second element is a string description of the success, which for 200 response codes will always be "Sent".

  • The third element is the string Timetoken value the system accepted the Publish() operation at.

Publish v1 - Invalid / Error Responses

In the event of an error, you will receive a non-200 HTTP status code. Depending on the error, you may or may not have a parseable array returned. If you do, and it has a second element, and that element is a string, you may parse it for a description of the error.

Errors specific to Publish() will occur when URL (e.g., message payload) is too large (>=32K), and invalid publish and/or subscribe keys are used.

Publish JSON to channel via GETGET/publish/{pub_key}/{sub_key}/0/{channel}/{callback}/{payload}{?store,uuid}

Example URI

GET https://ps.pndsn.com/publish/myPubKey/mySubKey/0/ch1/myCallback/%7B%22text%22%3A%22hey%22%7D?store=0&uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
URI Parameters
HideShow
pub_key
string (required) Example: myPubKey

the publish key to use

sub_key
string (required) Example: mySubKey

the subscriber key

channel
string (required) Example: ch1

the destination of the message

callback
string (required) Example: myCallback

response will be wrapped in JSONP function, 0 for no JSONP

payload
string (required) Example: %7B%22text%22%3A%22hey%22%7D

url-encoded JSON

store
number (optional) Example: 0

this parameter overrides default account configuration on message saving. 1 to Save, 0 to not save.

auth
string (optional) Example: "authKey"

If the channel is protected by PAM, auth must be passed with a key which is authorized to publish to the channel.

meta
object (optional) Example: meta={"cool":"meta"}

used to send additional information about the message which can be used on stream filtering.

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

ttl
string (required) Example: 1

Set a per message time to live in storage.

  1. If store TRUE, and ttl = 0, the message is stored with no expiry time.
  2. If store TRUE and ttl = X (X is an Integer value), the message is stored with an expiry time of X hours.
  3. If sStore FALSE, the ttl parameter is ignored.
  4. If ttl is not specified, then expiration of the message defaults back to the expiry value for the key.
Request  without JSONP
HideShow
Headers
Location: /publish/myPubKey/mySubKey/0/ch1/0/%7B%22text%22%3A%22hey%22%7D
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  1,
  "Sent",
  "14375220012064619"
]
Request  with JSONP
HideShow
Headers
Location: /publish/myPubKey/mySubKey/0/ch1/myCallback/%7B%22text%22%3A%22hey%22%7D
Response  200
HideShow
Headers
Content-Type: application/json
Body
myCallback([1,"Sent","14375220012064619"])

Publish V1 via POST

Publish a message to a channel.

Publish JSON to channel via POSTPOST/publish/{pub_key}/{sub_key}/0/{channel}/{callback}{?store,uuid}

Example URI

POST https://ps.pndsn.com/publish/myPubKey/mySubKey/0/ch1/myCallback?store=0&uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
URI Parameters
HideShow
pub_key
string (required) Example: myPubKey

the publish key to use

sub_key
string (required) Example: mySubKey

the subscriber key

channel
string (required) Example: ch1

the destination of the message

callback
string (required) Example: myCallback

response will be wrapped in JSONP function, 0 for no JSONP

store
number (optional) Example: 0

this parameter overrides default account configuration on message saving. 1 to save, 0 to not save.

auth
string (optional) Example: "authKey"

If the channel is protected by PAM, auth must be passed with a key which is authorized to write to the channel.

meta
object (optional) Example: meta={"cool":"meta"}

used to send additional information about the message which can be used on stream filtering.

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

ttl
string (required) Example: 1

Set a per message time to live in storage.

  1. If store TRUE, and ttl = 0, the message is stored with no expiry time.
  2. If store TRUE and ttl = X (X is an Integer value), the message is stored with an expiry time of X hours.
  3. If sStore FALSE, the ttl parameter is ignored.
  4. If ttl is not specified, then expiration of the message defaults back to the expiry value for the key.
Request  without JSONP
HideShow
Headers
Content-Type: application/json
Location: /publish/myPubKey/mySubKey/0/ch1/0
Body
{
  "message": "All your base are belong to us."
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  1,
  "Sent",
  "14375220012064619"
]
Request  with JSONP
HideShow
Headers
Location: /publish/myPubKey/mySubKey/0/ch1/myCallback/%7B%22text%22%3A%22hey%22%7D
Body
{
  "message": "All your base are belong to us."
}
Response  200
HideShow
Headers
Content-Type: application/json
Body
myCallback([1,"Sent","14375220012064619"])

Fire

The fire endpoint allows the client to send a message to BLOCKS Event Handlers. These messages will go directly to any Event Handlers registered on the channel that you fire to and will trigger their execution. The content of the fired request will be available for processing within the Event Handler. The message sent via fire() is not replicated, and so will not be received by any subscribers to the channel. The message is also not stored in history.

FireGET/publish/{pub_key}/{sub_key}/0/{channel}/{callback}?&norep=true&store=0

Example URI

GET https://ps.pndsn.com/publish/myPubKey/mySubKey/0/ch1/myCallback/{"text"%3A"hey"}?uuid=db9c5e39-7c95-40f5-8d71-125765b6f561&norep=true&store=0
URI Parameters
pub_key
string (required) Example: myPubKey

The publish key to use.

sub_key
string (required) Example: mySubKey

The subscriber key.

channel
string (required) Example: ch1

The destination of the message.

callback
string (required) Example: myCallback

Response will be wrapped in JSONP function, 0 for no JSONP.

store
number (required, should be 0 for Fire)

norep
boolean (required, should be true for Fire)

auth
string (optional) Example: "authKey"

If the channel is protected by PAM, auth must be passed with a key which is authorized to write to the channel.

meta
object (optional) Example: meta={"cool":"meta"}

Used to send additional information about the message which can be used on stream filtering.

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

Request without JSONP
Response 200
Request with JSONP
Response 200

Signals

Signals are very small, transient messages that represent momentary snippets of information that do not require extensive tracking and backup, as each one will be rapidly replaced by the next signal.

A signal may be part of a high-volume stream of payloads intended to inform or instruct an application, without including information that would be directly reflected in an application UI. Examples of signals include rideshare driver latitude and longitude measurements, a command to switch on a chat app typing indicator, and more.

By default, signals are limited to a message payload size of 30 bytes. This limit applies only to the request body, and not to the URI or headers. If you require a larger payload size, please contact support.

Signal a message to a channelGET/signal/{pub_key}/{sub_key}/0/{channel}/{callback}/{payload}{?uuid,auth}

This resource allows a developer to send a signal to a channel.

Example URI

GET https://ps.pndsn.com/signal/demo/demo/0/ch1/0/%22typing_on%22?uuid=user-123
Path parameters
pub_key

string (required)
Your PubNub Publish API Key

sub_key

string (required)
Your PubNub Subscribe API Key.

channel

string (required)
The channel name you wish to signal.

callback

string (required)
The JSONP callback, or 0 if no callback.

payload

string (required)
The message body to signal. This can be unstructured text or JSON, for example.

Query Parameters
uuid

string (optional)
A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

auth

string (optional)
If the channel is protected by PAM, auth must be passed with a key which is authorized to publish to the channel.

Response  200

Success

Headers
Content-Type: text/javascript
Body
[
    1,
    "Sent",
    "15614849564528142"
]
Receiving a signal message

To receive a signal message, you use a Subscribe V2 request. Signal messages are tagged with a message type (e) field value of e=1. The following example shows a signal message:

{
    "t": {
        "t": "15653761881633527",
        "r": 1
    },
    "m": [
        {
            "a": "5",
            "f": 0,
            "e": 1,
            "i": "user-123",
            "p": {
                "t": "15653761881622292",
                "r": 1
            },
            "k": "demo",
            "cv": "myChannel",
            "d": "typing_on",
            "b": "myChannelGroup"
        }
    ]
}
Response  400

There was an error with the request

Headers
Content-Type: text/javascript
Body
{
    "message": "Invalid Subscribe Key",
    "error": true,
    "status": 400
}
Response  403

Client is not authorized to perform this operation.

Headers
Content-Type: text/javascript
Body
{
    "message": "Forbidden",
    "payload": {
        "channels": [
            "channel"
        ]
    },
    "error": true,
    "service": "Access Manager",
    "status": 403
}
Response  404

Requested object was not found.

Headers
Content-Type: text/javascript
Body
[]
Response  413

The Signal POST body is larger than 30 bytes.

Headers
Content-Type: text/javascript
Body
{
    "status": 413,
    "service": "Balancer",
    "error": true,
    "message": "Request Entity Too Large"
}
Response  429

Request rate limit exceeded.

Headers
Content-Type: text/javascript
Body
{
    "status": 429,
    "error": true,
    "message": "Too many requests."
}

Subscribe

Subscribe to messages on channels and/or channel groups.

Subscribe v1 - Valid / Success Responses

Successful responses (200) return a three-element array:

  • Array Element 0 - Array - An array consisting of messages.

  • Array Element 1 - String - The next timetoken to connect with.

  • Array Element 2 - String - A CSV (not array) of the channels associated, in order, with the messages in array element 0. If the is an empty heartbeat response, or an empty initial timetoken 0 response, or you are only subscribed to a single channel or channel group, this element will not be returned.

  • Array Element 3 - String -When subscribed to one or more channel groups, array element 3 appears. It is a CSV (not array) of the "real channel" name associated with the channel group name.

If you are subscribed to a channel group named myCG, and you receive a message on myCG from a member channel named myCH, array element 2 will contain "myCG", and the corresponding entry in element 3 will be "myCH".

When subscribing to both channels and channel groups, the corresponding entry for an non-CG member channel will be identical to that of the entry for it element 2.

Subscribe v1 - Invalid / Error Responses

In the event of an error, you will receive a non-200 HTTP status code. Depending on the error, you may or may not have a parseable array returned.

Common HTTP Status Codes should be expected. In the event of a non-Common HTTP Status Code and/or unparseable JSON, assume an error, fire your error callback with as much information as possible, wait 1 second, and retry the failed request indefinitely.

It is critical to design your subscribe logic to be durable and always retry. Although it should try indefinately, since its calling the error callback on each failure, the developer will be able to unsubscribe from the channel(s) if needed.

SubscribeGET/subscribe/{sub_key}/{channel}/{callback}/{timetoken}{?state,heartbeat,uuid}

Example URI

GET https://ps.pndsn.com/subscribe/mySubKey/ch1/myFunction/1231312313123?state=%7B%22text%22%3A%22hey%22%7D&heartbeat=412&uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
URI Parameters
HideShow
sub_key
string (required) Example: mySubKey

Your PubNub Subscribe API Key

channel
string (required) Example: ch1

The channel name(s) you are subscribing to. Verify that channels are comprised of valid characters. You may subscribe to mulitple channels using a comma seperator. If subscribing to no channels (only channel groups), use a comma char (,) as a placeholder. You may subscribe to channels, channels & channel groups, or just channel groups.

callback
string (required) Example: myFunction

JSONP callback name, or 0 if none.

timetoken
string (required) Example: 1231312313123

0 (zero) for the initial subscribe, or a valid timetoken if resuming / continuing / fast-forwarding from a previous subscribe flow.

channel-group
string (optional) Example: cg1,cg2,cg3

Channel group name(s) to subscribe to. If subscribing to more than one channel group, use a comma separator between channel group names. You may subscribe to channels, channels & channel groups, or just channel groups.

state
string (optional) Example: %7B%22text%22%3A%22hey%22%7D

When state is set, this value is an object with root keys associated with each channel you are setting state for. You must be subscribed to a channel to set state for it. (Refer to the get/set state sections)

heartbeat
number (optional) Example: 412

If heartbeat is set, send this parameter with the heartbeat value. (Refer to the heartbeat section)

auth
string (optional) Example: "authKey"

If the channel / channel group is protected by PAM, auth must be passed with a key which is authorized to read from the channel.

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

Subscribe v2 - Valid / Success Responses

An Object containing 2 elements:

  • First element is an object containing 2 values: t - String - the timetoken and r - Int - the region.

  • Second element is an array of messages, each message contains.

    • a - String - Shard
    • b - String - Subscription match or the channel group
    • c - String - Channel
    • d - Object - The payload
    • e - Int - Message Type (e.g. is 1 for Signal)
    • f - Int - Flags
    • i - String - Issuing Client Id
    • k - String - Subscribe Key
    • o - Object - Originating Timetoken, containing: t - String - the timetoken and r - Int - the region.
    • p - Object - Publish Timetoken Metadata containing: t - String - the timetoken and r - Int - the region.
    • u - Object - User Metadata

If you are subscribed to a channel group named myCG, and you receive a message on myCG from a member channel named myCH, array element 2 will contain "myCG", and the corresponding entry in element 3 will be "myCH".

When subscribing to both channels and channel groups, the corresponding entry for an non-CG member channel will be identical to that of the entry for it element 2.

Subscribe v2 - Invalid / Error Responses

In the event of an error, you will receive a non-200 HTTP status code. Depending on the error, you may or may not have a parseable array returned.

Common HTTP Status Codes should be expected. In the event of a non-Common HTTP Status Code and/or unparseable JSON, assume an error, fire your error callback with as much information as possible, wait 1 second, and retry the failed request indefinitely.

It is critical to design your subscribe logic to be durable and always retry. Although it should try indefinately, since its calling the error callback on each failure, the developer will be able to unsubscribe from the channel(s) if needed.

SubscribeGET/v2/subscribe/{sub_key}/{channel}/{callback}{?uuid,tt,tr,state,filter-expr}

This resource allows a developer to Subscribe to PubNub.

Example URI

GET https://ps.pndsn.com/v2/subscribe/mySubKey/ch1/myFunction?uuid=db9c5e39-7c95-40f5-8d71-125765b6f561&tt=14586610176891624&tr=4&state=%7B%22ch1%22%3A%7B%22testkey%22%3A%22testval%22%7D%7D&filter-expr=uuid%20!%3D%20%27cvc1%27
URI Parameters
HideShow
sub_key
string (required) Example: mySubKey

Your PubNub Subscribe API Key

channel
string (required) Example: ch1

The channel name(s) you are subscribing to. Verify that channels are comprised of valid characters. You may subscribe to mulitple channels using a comma seperator. If subscribing to no channels (only channel groups), use a comma char (,) as a placeholder. You may subscribe to channels, channels & channel groups, or just channel groups.

callback
string (required) Example: myFunction

JSONP callback name, or 0 if none.

tt
string (required) Example: 1231312313123

0 (zero) for the initial subscribe, or a valid timetoken if resuming / continuing / fast-forwarding from a previous subscribe flow.

tr
string (optional)

Region as returned from the initial call with tt=0.

channel-group
string (optional) Example: cg1,cg2,cg3

Channel group name(s) to subscribe to. If subscribing to more than one channel group, use a comma separator between channel group names. You may subscribe to channels, channels & channel groups, or just channel groups.

state
string (optional) Example: %7B%22text%22%3A%22hey%22%7D

When state is set, this value is an object with root keys associated with each channel you are setting state for. You must be subscribed to a channel to set state for it. (Refer to the get/set state sections)

heartbeat
number (optional) Example: 412

If heartbeat is set, send this parameter with the heartbeat value. (Refer to the heartbeat section)

auth
string (optional) Example: "authKey"

If the channel / channel group is protected by PAM, auth must be passed with a key which is authorized to read from the channel.

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

filter-expr
string (optional) Example: uuid%20!%3D%20%27cvc1%27

Set filter expression for Subscribe message filtering.

Response  200

Success

Headers
Content-Type: text/javascript
Body
{
    "t": {
        "t": "15628652479932717",
        "r": 4
    },
    "m":[
        {
            "a": "1",
            "f": 514,
            "i": "pn-0ca50551-4bc8-446e-8829-c70b704545fd",
            "s": 1,
            "p": {
                "t": "15628652479933927",
                "r": 4
            },
            "k": "demo",
            "c": "my-channel",
            "d": "my message",
            "b": "my-channel"
        }
    ]
}
Response  400

There was an error with the request

Headers
Content-Type: text/javascript
Body
{
    "message": "Invalid Subscribe Key",
    "error": true,
    "service": "Access Manager",
    "status": 400
}
Response  403

Client is not authorized to perform this operation.

Headers
Content-Type: text/javascript
Body
{
    "message": "Forbidden",
    "payload": {
        "channels": [
            "channel"
        ]
    },
    "error": true,
    "service": "Access Manager",
    "status": 403
}
Response  429

The Signal POST body is larger than 32KB.

Headers
Content-Type: text/javascript
Body
{
    "status": 429,
    "error": true,
    "message": "Too many requests."
}

History

Fetch History

History - Valid / Success Responses

  • Array Element 0 – Array – Contains an array of JSON messages. Array will be between 0 and 100 in length, based on the count parameter (default 100) used at request time, and the number of valid messages available for the given time-slice.

  • Array Element 1 – Int – Start Timetoken of returned results,

  • Array Element 2 – Int – End Timetoken of returned results,

Successful (HTTP Status 200) History() calls will always return a three-element array similar to:

[ [MSG1, MSG2, ...], START_TIMETOKEN, END_TIMETOKEN ]

for example: [["Pub1","Pub2","Pub3"],13406746729185766,13406746780720711]

History - Invalid / Error Responses

In the event of an error, you will receive a non-200 HTTP status code. Depending on the error, you may or may not have a parseable array returned.

About Timetokens

The timetoken represents a 17-digit precision unix time (UTC). To convert PubNub’s timetoken to Unix timestamp (seconds), divide the timetoken number by 10,000,000 (10^7).

To convert back and forth between current time, A Ruby example follows as:

> now = Time.now
 => 2012-11-02 14:27:11 -0700

> timetoken = now.to_f * 10000000
 => 13518916319742640

> Time.at(timetoken / 10000000)
 => 2012-11-02 14:27:11 -0700

Paging

Page through History, traversing newest to oldest:

Perform the initial history request, without any start or end parameters (we’ll limit results to two at a time to make this example easier to grok):

curl "https://ps.pndsn.com/v2/history/sub-key/mySubKey/channel/dox?count=4"
 --> [["msg4","msg5","msg6","msg7"],14382111171320896,14382111251236844]

Using the start Timetoken provided from the last response, use as the start parameter for the next page:

curl "https://ps.pndsn.com/v2/history/sub-key/mySubKey/channel/dox?count=4&start=14382111171320896"
 --> [["msg1","msg2","msg3"],14382102111436851,14382102175496790]

Repeat, until you get 0 (zero) back as a start Timetoken. This indicates you are at the end of the list.

curl "https://ps.pndsn.com/v2/history/sub-key/mySubKey/channel/dox?count=4&start=14382102111436851"
 --> [[],0,0]`

You may also wish to page through history from oldest to newest:

Perform the initial history request, without any start or end parameters (we’ll limit results to two at a time to make this example easier to grok), but with reverse=true:

curl "https://ps.pndsn.com/v2/history/sub-key/mySubKey/channel/dox?count=4&reverse=true"
 --> [["msg1","msg2","msg3","msg4"],14382102111436851,14382111171320896]

Repeat the request, with the end Timetoken provided in the response, used as the start value in the next request:

curl "https://ps.pndsn.com/v2/history/sub-key/mySubKey/channel/dox?count=4&reverse=true&start=14382111171320896"
 --> [["msg5","msg6","msg7"],14382111201316589,14382111251236844]

Repeat, until you get 0 (zero) back as a start Timetoken. This indicates you are at the end of the list.

curl "https://ps.pndsn.com/v2/history/sub-key/mySubKey/channel/dox?count=4&reverse=true&start=14382111251236844"
 --> [[],0,0]

Fetch HistoryGET/v2/history/sub-key/{sub_key}/channel/{channel}{?stringtoken,count,reverse,start,end,include_token,auth,uuid,include_meta}

Example URI

GET https://ps.pndsn.com/v2/history/sub-key/mySubKey/channel/ch1?stringtoken=false&count=100&reverse=false&start=123323123123123&end=123323123123123&include_token=false&auth=authKey&uuid=db9c5e39-7c95-40f5-8d71-125765b6f561&include_meta=true
URI Parameters
HideShow
sub_key
string (required) Example: mySubKey

the subscriber key

channel
string (required) Example: ch1

channel for which the history is requested

stringtoken
boolean (optional) Example: false

If false, 0, or not provided, the returned start and end Timetoken values will be returned as long ints. If 1, or true, the start and end Timetoken values will be returned as strings.

count
number (optional) Example: 100

The maximum number of messages to return per response. If the count parameter is not provided, the server will default to the maximum value of 100. When the count parameter is provided, you may request between 1 and 100 messages.

reverse
boolean (optional) Example: false

Direction of time traversal. Default is false, which means timeline is traversed newest to oldest.

start
number (optional) Example: 123323123123123

If provided, lets you select a "start date", in Timetoken format. If not provided, it will default to current time. Page through results by providing a start OR end time token. Retrieve a slice of the time line by providing both a start AND end time token. start is ‘exclusive’ – that is, the first item returned will be the one immediately after the start Timetoken value.

end
number (optional) Example: 123323123123123

If provided, lets you select an "end date", in Timetoken format. If not provided, it will provide up to the number of messages defined in the "count" parameter. Page through results by providing a start OR end time token. Retrieve a slice of the time line by providing both a start AND end time token. End is ‘exclusive’ – that is, if a message is associated exactly with the end Timetoken, it will be included in the result.

include_token
boolean (optional) Example: false

pass true to recieve a timetoken with each history message. Defaults to false

auth
string (optional) Example: "authKey"

If the channel is protected by PAM, auth must be passed with a key which is authorized to read from the channel.

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

include_meta
boolean (optional) Example: true

Set to true to include metadata with returned messages. This metadata is set using the meta parameter with the publish operation. Default is false.

Batch HistoryGETv3/history/sub-key/{sub_key}/channel/{channels}?max,reverse,start,end,auth,uuid,include_meta

Example URI

GET https://ps.pndsn.com/v3/history/sub-key/mySubKey/channel/ch1,ch2?max=25&reverse=false&start=123323123123123&end=123323123123123&auth=authKey&uuid=db9c5e39-7c95-40f5-8d71-125765b6f561&include_meta=true
URI Parameters
HideShow
sub_key
string (required) Example: mySubKey

the subscriber key

channel
string (required) Example: ch1, ch2

comma separated channels for which the history is requested

max
number (optional) Example: 25

The batch history is limited to 500 channels and only the last 25 messages per channel.

reverse
boolean (optional) Example: false

Direction of time traversal. Default is false, which means timeline is traversed newest to oldest.

start
number (optional) Example: 123323123123123

If provided, lets you select a "start date", in Timetoken format. If not provided, it will default to current time. Page through results by providing a start OR end time token. Retrieve a slice of the time line by providing both a start AND end time token. start is ‘exclusive’ – that is, the first item returned will be the one immediately after the start Timetoken value.

end
number (optional) Example: 123323123123123

If provided, lets you select an "end date", in Timetoken format. If not provided, it will provide up to the number of messages defined in the "max" parameter. Page through results by providing a start OR end time token. Retrieve a slice of the time line by providing both a start AND end time token. End is ‘exclusive’ – that is, if a message is associated exactly with the end Timetoken, it will be included in the result.

auth
string (optional) Example: "authKey"

If the channel is protected by PAM, auth must be passed with a key which is authorized to read from the channel.

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

include_meta
boolean (optional) Example: true

Set to true to include metadata with returned messages. This metadata is set using the meta parameter with the publish operation. Default is false.

MessageCounts Get /v3/history/sub-key/{sub_key}/message-counts/{channels}{?uuid,timetoken,channelsTimetoken,auth}

Get message counts for channels.

Returns a list of channels with associated message counts over the given time period. Channels without messages have a count of 0. Channels with 10,000 messages or more have a count of 10000.

 For keys with unlimited message retention enabled, this method considers only messages published in the last 7 days.

Example URI

GET https://ps.pndsn.com/v3/history/sub-key/mySubKey/message-counts/myChannel1,myChannel2?channelsTimetoken=15210190573608384,15211140747622125&timetoken=&auth=akey&uuid=pn-2e4c3684-49ee-4b05-920d-36f39685e641
Path parameters
sub_key
Path Parameter (required) 

Your PubNub subscribe API key.

channels
Path Parameter (required) 

The channel name(s) you wish to pull history from. Separate multiple channel names with commas. Channel names must be comprised of valid characters. May be a single channel, or multiple channels, separated by comma.

Query parameters
auth
string (optional) Example: "authKey"

If the channel is protected by PAM, auth must be passed with a key which is authorized to read from the channel.

uuid
Query Parameter (required) 

A unique alphanumeric ID to identify the client to the PubNub Presence System, as well as for PubNub Analytics.

timetoken
Query Parameter (optional) 

A single timetoken to cover all channels passed-in on the request path. This parameter is incompatible with channelsTimetoken. Value must be greater than 0 (zero).

channelsTimetoken
Query Parameter (optional) 

A comma-delimited list of timetokens, in order of the channels list, in the request path. If the list of timetokens is not the same length as the list of channels, a 400 bad request error will result. This parameter is incompatible with timetoken. Value must be greater than 0 (zero).

Return type
Produces

This API call produces the following media types according to the Accept request header; the media type will be conveyed by the Content-Type response header.

  • application/json
Response  200

A list of channels with counts of messages in history newer than the passed-in timetoken (greater than operation).

{
    "status": 200,
    "error": false,
    "error_message": "",
    "channels": {
        "myChannel1": 33,
        "myChannel2": 0
    }
}
Response  400

Invalid Arguments. This may be due to an invalid subscribe key; missing or invalid timetoken or channelsTimetoken (values must be greater than 0); mismatched number of channels and time tokens; invalid characters in a channel name; or other invalid request data.

Response  403

Storage is not enabled for this subscribe key.

HistoryResponseV3

status
Integer  

API HTTP status code format: int32.

error
Boolean  

TRUE if an error occurred, and FALSE if the operation was successful.

error_message
String (optional) 

Error message content, if applicable.

message
String (optional) 

Error message content from another service, if applicable.

channels
Object (optional) 

Object containing key-value pairs. Each key-value pair is a channel name (string) and a message count (integer).

service
String (optional) 

The service that returned the error. This field is only present if the error is returned by another service, such as Access Manager.

Delete From History

If Auth is enabled then the Delete request is accepted only if signed with the secret-key. If not will return:

{status: 403, error: true, error_message: "Do not have permission to delete"}.

If parsing the request fails, will return:

{status: 400, error: true, error_message: "Parse error"}.

Delete API is asynchronously processed. Getting a {status: 200, error: false, error_message: ""} implies the Delete request has been received and will be processed soon.

After the delete has been processed, a webhook is called if the subkey specifies one. If multiple (say N) channels are given in the request a single 200 is returned but N webhook calls will be made.

Note: There is a setting to accept delete from history requests for a key, which you must enable by checking the Enable Delete-From-History checkbox in the key settings for your key in the Administration Portal.

Delete History DELETE /v3/history/sub-key/<sub-key>/channel/<channels>

Use a REST DELETE method in this format to make the request to the PubNub service to delete a channel or subset of a channel.

Example URI

curl -s -X DELETE -i  https://ps.pndsn.com/v3/history/sub-key/mySubKey/channel/channelfoo?start=14993928130000000&end=14992200130000000
URI Parameters
start
number  (optional)  Example:  14993928130000000

end
number  (optional)  Example:  14992200130000000

  • If neither start nor end is given, we delete all messages for that channel.
  • If start is given and no end, we delete from the start time and all messages before that time. Start time is not inclusive, as in message with timestamp start will not be deleted.
  • If end is given and no start, we delete all messages from the current time till the end time. End time is inclusive, as in message with timestamp end will be deleted.
  • If start and end are given, we delete all messages from the start time till the end time. Start time is inclusive and the end time is not included.
  • If auth is enabled for subkey, the request needs to have signature.
Response   200
Headers
response.set_header('Content-Type', 'text/javascript; charset="UTF-8"')
response.set_header('Cache-Control', 'no-cache')
response.set_header('Access-Control-Allow-Origin', '*')
response.set_header('Access-Control-Allow-Methods', 'GET')

//if message_count is not None:

response.set_header('PN-Messages', str(message_count))
if request.headers.get('SSL'):
    response.set_header('PN-SSL', 'ssl')
Body
{
    "status": 200,
    "error": false,
    "error_message": "",
}
Response   400
Headers
response.set_header('Content-Type', 'text/javascript; charset="UTF-8"')
response.set_header('Cache-Control', 'no-cache')
response.set_header('Access-Control-Allow-Origin', '*')
response.set_header('Access-Control-Allow-Methods', 'GET')

//if message_count is not None:

response.set_header('PN-Messages', str(message_count))
if request.headers.get('SSL'):
    response.set_header('PN-SSL', 'ssl')
Body
{
    "status": 400,
    "error": true,
    "error_message": "Parse error",
}
Response   403
Headers
response.set_header('Content-Type', 'text/javascript; charset="UTF-8"')
response.set_header('Cache-Control', 'no-cache')
response.set_header('Access-Control-Allow-Origin', '*')
response.set_header('Access-Control-Allow-Methods', 'GET')

//if message_count is not None:

response.set_header('PN-Messages', str(message_count))
if request.headers.get('SSL'):
    response.set_header('PN-SSL', 'ssl')
Body
{
    "status": 403,
    "error": true,
    "error_message": "Do not have permission to delete",
}

Webhook Method POST /v3/history/sub-key/<sub-key>/channel/<channels>

Once the deletion of the requested messages has been performed, PubNub will make a callback to your application to inform you that your request has been completed, and all the requested messages / channels have been completely deleted.

Example URI

curl -i  http://<balancer>/v3/history/sub-key/<sub-key>/channel/<channels>

Retry Policy: Exponential Total retries: 3

The URL that PubNub will make a web hook call to is configurable on a per key basis. You can configure this URL in the Administration Portal under the Storage & Playback settings for your key.

PubNub expects your application to respond to our webhook informing you of the completion of the delete request with an appropriate status response. This can be either 200 or 400, to indicate success or failure to receive the webhook, respectively.

PubNub will include a message in the body of the POST request to your server that indicates more detail of what happened to your deletion request.

Successful completion of the message delete request
Body
{
    "error": false,
    "error_message": "",
    "channel": channel_deleted
}
Unsuccessful completion of the message delete request
Body
{
    "error": true,
    "error_message": "Storage Error",
    "channel": ""
}

Creating a signature with JS Standalone

// Requires the request module: https://www.npmjs.com/package/request

var request = require("request");

// Set your keys (replace with your own)

var pnAPIKeys = {
    "subKey": "MySubKey",
    "pubKey": "MyPubKey",
    "secKey": "MySecretKey"
};

// In this config as it stands, it will delete all messages in the channel
// To delete from an offset or range
// Add start and/or end parameters with PN timetoken integers as values

var historyDeleteURLParams = {
    "uuid": "pn-86eec3a6-2aff-4faf-8722-71374c737f2a",
    "pnsdk": "[companyname][base_pn_sdk][branch_pn_sdk]-v.#.#",
    "auth": "myAuthToken",
    "uuid": "ec4b2732-4739-494a-b83f-094ad22be275",
    "timestamp": Math.floor(new Date().getTime() / 1000)
};

// Create the URL for History Delete

var historyDeleteUrl = "/v3/history/sub-key/" + pnAPIKeys.subKey + "/channel/myChannel"

// TODO: Cleanup temp vars (currently used to swap out for other signature-based REST calls)

var url = historyDeleteUrl;
var urlParams = historyDeleteURLParams;

// Sign the request

var signature = signRequest(url, pnAPIKeys);

// Add the signature to the URL Params obj

urlParams.signature = signature;

// Create the params string from the obj

var finalParams = (objectToParams(urlParams));

// DELETE history operation must use DELETE method

request.del("http://ps.pndsn.com" + url + "?" + finalParams, function(error, response, body){
    if(error){
        console.log(error);
    } else {
        console.log(JSON.stringify(response));
    }
});

/* *** Utility *** */

function signRequest(url, outgoingParams) {

    var hmacsha256 = require("crypto-js/hmac-sha256");
    var CryptoJS = require("crypto-js");
    var signInput = pnAPIKeys.subKey + '\n' + pnAPIKeys.pubKey + '\n' + url + '\n';

    // Add a new line containing the query parameters in urlencoded alpha order

    signInput += signPamFromParams(urlParams);

    // Create the hash

    var signature = hmacsha256(signInput, outgoingParams.secKey);
    base64Signature = signature.toString(CryptoJS.enc.Base64);

    // In the signature, Replace the plusses with -, Replace the slashes with underscores

    base64Signature = base64Signature.replace(/\+/g, '-');
    base64Signature = base64Signature.replace(/\//g, '_');

    // Done!

    //console.log(base64Signature);
    return base64Signature;
}

function objectToList(o) {
    var l = [];
    Object.keys(o).forEach(function (key) {
        return l.push(key);
    });
    return l;
}

function encodeString(input) {
    return encodeURIComponent(input).replace(/[!~*'()]/g, function (x) {
        return '%' + x.charCodeAt(0).toString(16).toUpperCase();
    });
}

function objectToListSorted(o) {
    return objectToList(o).sort();
}

function objectToParams(obj) {
    var str = "";
    for (var key in obj) {
        if (str != "") {
            str += "&";
        }
        str += key + "=" + encodeURIComponent(obj[key]);
    }

    return str;
}

function signPamFromParams(params) {
    var l = objectToListSorted(params);
    return l.map(function (paramKey) {
        return paramKey + '=' + encodeString(params[paramKey]);
    }).join('&');
}

function endsWith(searchString, suffix) {
    return searchString.indexOf(suffix, this.length - suffix.length) !== -1;
}

Encrypt Msg Using secret-key as the Encryption Key

key = "mySubKey" //Secret-key

msg = "

{subkey}

{pubkey}

{path}

{params}"

Example:
subkey= mySubKey,
pubkey= myPubKey,
path= '/v3/history/sub-key/mySubKey/channel/channel1' ,
params= '"timestamp"=1506666034'

params is REST Query parameters and the timestamp should be the current epoch timestamp when signing.

Then the URI with signature will be

    curl -s -X DELETE -i 'http://ps.pndsn.com/v3/history/sub-key/mySubKey/channel/channel1?timestamp=1506666034&signature=uVRcaYccGYlmNUAjHBOSGZ-10O9-sQm8HqYlGomNOCc%3D'

Channel Groups

Listing All Registered Channel Groups

Listing All Registered Channel GroupsGET/v1/channel-registration/sub-key/{sub_key}/channel-group{?uuid}

This endpoint is disabled on most subscribe keys, please contact support@ to confirm endpoint usability

Example URI

GET https://ps.pndsn.com/v1/channel-registration/sub-key/mySubKey/channel-group?uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
URI Parameters
HideShow
sub_key
string (required) Example: mySubKey

the subscriber key

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

Request  Get all channel groups for subscribe key
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "service": "name of the service returning the data",
  "status": "HTTP status code of the performed action",
  "error": "returns the reason an error has occoured",
  "payload": {
    "sub_key": "subKey",
    "groups": [
      "group1",
      "group2",
      "group3"
    ]
  }
}

Listing all channels for a channel group

Listing all channels for a channel groupGET/v1/channel-registration/sub-key/{sub_key}/channel-group/{group}{?uuid}

Example URI

GET https://ps.pndsn.com/v1/channel-registration/sub-key/mySubKey/channel-group/group1?uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
URI Parameters
HideShow
sub_key
string (required) Example: mySubKey

the subscriber key

group
string (required) Example: group1

the group for which we need the list of channels

auth
string (optional) Example: "authKey"

If the channel group is protected by PAM, auth must be passed with a key which is authorized to read the channel group.

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

Request  Get all channels for a channel group
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "service": "name of the service returning the data",
  "status": "HTTP status code of the performed action",
  "error": "returns the reason an error has occoured",
  "payload": {
    "group": "group_id",
    "channels": [
      "channel1",
      "channel2",
      "channel3"
    ]
  }
}

Adding channels // New Channel Group

This endpoint supports both the addition of channels to channel groups and also creating a channel group. To create a new group, pass the neme of the desired group as the group name

Adding Channels // New Channel GroupGET/v1/channel-registration/sub-key/{sub_key}/channel-group/{group}{?add,uuid}

Example URI

GET https://ps.pndsn.com/v1/channel-registration/sub-key/mySubKey/channel-group/group1?add=ch1&uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
URI Parameters
HideShow
sub_key
string (required) Example: mySubKey

The subscriber key

group
string (required) Example: group1

The channel group to which the channels will be added

add
string (required) Example: ch1

Name of a channel to be added to the channel group. You may add mulitple channels using a comma seperator (ch1,ch2,ch3).

auth
string (optional) Example: "authKey"

If the channel group is protected by PAM, auth must be passed with a key which is authorized to manage the channel group.

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

Request
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "service": "channel-registry",
  "status": "200",
  "error": false,
  "message": "OK"
}

Removing channels

Removing channelsGET/v1/channel-registration/sub-key/{sub_key}/channel-group/{group}{?remove,uuid}

Example URI

GET https://ps.pndsn.com/v1/channel-registration/sub-key/mySubKey/channel-group/group1?remove=ch1&uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
URI Parameters
HideShow
sub_key
string (required) Example: mySubKey

The subscriber key

group
string (required) Example: group1

The channel group to which the channels will be added

remove
string (required) Example: ch1

Name of a channel to be removed from the channel group. You may add mulitple channels using a comma seperator (ch1,ch2,ch3).

auth
string (optional) Example: "authKey"

If the channel group is protected by PAM, auth must be passed with a key which is authorized to manage the channel group.

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

Request
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "service": "channel-registry",
  "status": "200",
  "error": false,
  "message": "OK"
}

Deleting a Channel Group

Deleting a Channel GroupGET/v1/channel-registration/sub-key/{sub_key}/channel-group/{group_name}/remove{?uuid}

Example URI

GET https://ps.pndsn.com/v1/channel-registration/sub-key/mySubKey/channel-group/group1/remove?uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
URI Parameters
HideShow
sub_key
string (required) Example: mySubKey

the subscriber key

group_name
string (required) Example: group1

the group to be deleted

auth
string (optional) Example: "authKey"

If the channel group is protected by PAM, auth must be passed with a key which is authorized to manage the channel group.

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

Request  Deleting a Channel Groups
Response  200
HideShow
Headers
Content-Type: application/json
Body
{
  "service": "channel-registry",
  "status": "200",
  "error": false,
  "message": "OK"
}

PubNub Access Manager -- PAM v2

PubNub Access Manager v2

PubNub Access Manager (PAM v2) provides fine-grained access controls to PubNub Data Streams. It presents a minimal REST API for secure administration tasks, and transparently protects Data Stream resource access. This document divides these two responsibilities clearly into their own sections; REST API, and ACL Enforcement.

 This information applies only to PAM v2. For information PAM v3, refer to the PAM v3 documentation.

General Information

  • Global Permissions

    Do Not Provide auth nor channel in the {signed-content} query-string parameters

  • Channel Permissions

    Provide only a channel parameter, but not auth parameter, this then sets permissions on the channel itself overriding any auth-key permissions

  • AuthKey Permissions

    Provide both auth and channel parameters to set the permissions for one or more channels and one or more auth-keys

Both auth and channel accept comma-separated lists.



Access Manager v2 Request String Formatting Requirements‌

 This information applies only to PAM v2. For information PAM v3, refer to the PAM v3 documentation.
  • {access-manager-request-string} parameters must be sorted lexicographically (case-sensitive) by key.

  • Secondly, all characters in the query string parameters must be percent-encoded except alphanumeric, hyphen, underscore, and period; E.g. all characters matching the RegExp /[^0-9a-zA-Z\-_\.]/.

  • Space characters must be replaced by %20 (NOT + character).

  • Each key-value pair must be separated by ampersand characters.

  • Unicode characters must be broken up into UTF-8 encoded bytes before percent-encoding.

  • Final signed value should be Base64 encoded using the "URL safe" characters - and _ replacing + and / respectively.

Here is an example of a query string containing unicode characters (PoundsSterling is just there to demonstrate encoding/sorting):

auth={auth-key-to-be-updated}&r=1&w=1&ttl=60&timestamp=123456789&PoundsSterling=£13.37

And here is the same query string after sorting and percent-encoding (PoundsSterling is just there to demonstrate encoding/sorting):

PoundsSterling=%C2%A313.37&auth=joker&r=1&timestamp=123456789&ttl=60&w=1

Let’s imagine the demo account’s secret key is:

wMfbo9G0xVUG8yfTfYw5qIdfJkTd7A

The signature generated for this request is Base64 encoded using the "URL safe" characters - and _ replacing + and / respectively:

v2rgQQ1eFzk8omugFV9V1_eKRUvvMv9jyC9Z-L1ogdw=

This signature is then percent-encoded according to standard query parameter percent-encoding practices. E.g. the = character is transformed into %3D.

v2rgQQ1eFzk8omugFV9V1_eKRUvvMv9jyC9Z-L1ogdw%3D

Check out http://www.pubnub.com/docs/access-manager-signature-construction to know more about computing the signature for the request.


Applying PAM v2GET/v2/auth/grant/sub-key/{sub_key}{?signature,auth,uuid}

In this Request, the auth-key is the client that has permissions to modify Access Manager permissions, not the auth-key you want to modify permissions on. The one you are changing permissions for is within the parameters.

Example URI

GET https://ps.pndsn.com/v2/auth/grant/sub-key/mySubKey?signature='v2rgQQ1eFzk8omugFV9V1_eKRUvvMv9jyC9ZL1ogdw%3D'&auth=myAuthKey&uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
URI Parameters
HideShow
sub_key
string (required) Example: mySubKey

Your PubNub Subscribe API Key.

signature
string (required) Example: 'v2rgQQ1eFzk8omugFV9V1_eKRUvvMv9jyC9ZL1ogdw%3D'

A signed request as described in the section above.

auth
string (required) Example: myAuthKey

The Auth key that is being granted permissions.

uuid
string (optional) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

timestamp
int (required) Example: 123456789

The timetoken represents a 17-digit precision unix time (UTC). To convert PubNub's timetoken to Unix timestamp (seconds), divide the timetoken number by 10,000,000 (10^7).

ttl
int (optional) Example: 15

Time to live for permission to be valid

channel
string (optional) Example: ch1,ch2

Specifies the channels on which to grant permissions. Comma separated values are accepted.

channel-group
string (optional) Example: group1,group2

Specifies the channel groups on which to grant permissions. Comma separated values are accepted.

w
boolean (optional) Example: 1

Write permission

r
boolean (optional) Example: 0

Read permission

m
boolean (optional) Example: 0

Manage permission

d
boolean (optional) Example: 0

Delete permission

Request
Response  200
HideShowExample:
Body
Depending on the parameters provided (channel name, auth)

{
    "status": 200,
    "message": "Success",
    "payload": {
        "ttl": 1440,
        "auths": {
            "password": {
                "r": 1,
                "w": 0,
                "m": 0,
                "d": 0
            }
        },
        "subscribe_key": "{subscribe-key}",
        "level": "user",
        "channel": "my_channel"
    },
    "service": "Access Manager"
}

Applying PAM v3POST/v3/pam/{sub_key}/grant{?signature}

Returns a signed token that can be used to access the requested resources for a specific duration.

Path parameters
sub_key

string (required)
Your PubNub Subscribe API Key.

Query Parameters
timestamp

integer (required)
Unix epoch timestamp used as a nonce for signature computation. Must have no more than ± 60 second offset from NTP.
This is not associated with the TTL at all.

signature

string (required)
Used to verify the request was signed with the secret key associated with the PubNub subscribe key.
Signature is computed using HMAC+SHA256 with the user's secret key as the signing key, and a signing message composed of the HTTP method, publish key, request path, query string, and request body (or emtpy string) in the following format;

"{method}\n{pub_key}\n{path}\n{query_string}\n{body}"

Query string parameters must be sorted lexicographically (case-sensitive) by key; duplicate keys are not allowed. Secondly, all characters in the query string parameters must be percent-encoded except alphanumeric, hyphen, underscore, period, and tilde;
E.g. all characters matching the RegExp /[^0-9a-zA-Z\-_\.~]/ must remain unencoded. Space characters must be replaced by %20 (NOT + character). Each key-value pair must be separated by ampersand characters. Unicode characters must be broken up into UTF-8 encoded bytes before percent-encoding.

Here is an example of a query string containing unicode characters;

timestamp=123456789&PoundsSterling=£13.37

And here is the same query string after sorting and percent-encoding;

PoundsSterling=%C2%A313.37&timestamp=123456789

The request body must be appended to the message verbatim (byte-for-byte as provided in the request).
Here is a full example message for signature computation. In this example, the POST body does not have a trailing line break character, but it does have structural whitespace and is encoded with UTF-8;

POST
demo
/v3/pam/demo/grant
PoundsSterling=%C2%A313.37&timestamp=123456789
{
    "ttl": 1440,
    "permissions": {
        "resources" : {
            "channels": {
                "inbox-jay": 3
            },
            "groups": {},
            "users": {},
            "spaces": {}
        },
        "patterns" : {
            "channels": {},
            "groups": {},
            "users": {},
            "spaces": {}
        },
        "meta": {
            "user-id": "jay@example.com",
            "contains-unicode": "The Pile of Poo test."
        }
    }
}

Here's the same message as a Python repr() string:

'POST\ndemo\n/v3/pam/demo/grant\nPoundsSterling=%C2%A313.37×tamp=123456789\n{\n  "ttl": 1440,\n  "permissions": {\n    "resources" : {\n      "channels": {\n        "inbox-jay": 3\n      },\n      "groups": {},\n      "users": {},\n      "spaces": {}\n    },\n    "patterns" : {\n      "channels": {},\n      "groups": {},\n      "users": {},\n      "spaces": {}\n    },\n    "meta": {\n      "user-id": "jay@example.com",\n      "contains-unicode": "The \xf0\x9f\x92\xa9 test."\n    }\n  }\n}'

Let's imagine the demo account's secret key is;

wMfbo9G0xVUG8yfTfYw5qIdfJkTd7A

The signature generated for this request is Base64 encoded using the "URL safe" characters - and _ replacing + and / respectively. The padding = characters are stripped from the end. The final step is concatenating the version prefix v2..
Here's the expected signature for this request;

v2.k80LsDMD-sImA8rCBj-ntRKhZ8mSjHY8Ivngt9W3Yc4
Request  required

A JSON blob of resource types to permission rules.
At least one of channels, groups, users, or spaces resource types under the resources or patterns mapping is required to have a non-empty value. Others may be an empty map.

Headers
Content-Type: text/javascript
Body
{
  "ttl": 1440,
  "permissions": {
    "resources": {
      "channels": {
        "inbox-jay": 3
      },
      "groups": {},
      "users": {},
      "spaces": {}
    },
    "patterns": {
      "channels": {
        "^topic-[0-9a-f]*$": 1,
        "^topic-[0-9a-f]*-pnpres$": 3
      },
      "groups": {},
      "users": {},
      "spaces": {}
    },
    "meta": {
      "user-id": "jay@example.com"
    }
  }
}
Response  200

Grant request was successful.
The response body contains a token that can be provided to enduser devices for access to the resources contained within the token. The token can also be unwrapped by Base 64 decoding (add padding characters as necessary) and then CBOR decoding the binary.
The token schema is available here.

Headers
Content-Type: text/javascript
Body
{
    "status": 200,
    "data": {
        "message": "Success",
        "token": "p0F2AkF0Gl043rhDdHRsCkNyZXOkRGNoYW6hZnNlY3JldAFDZ3JwoEN1c3KgQ3NwY6BDcGF0pERjaGFuoENncnCgQ3VzcqBDc3BjoERtZXRhoENzaWdYIGOAeTyWGJI-blahPGD9TuKlaW1YQgiB4uR_edmfq-61"
    },
    "service": "Access Manager"
}
Response  400

Error validating inputs. (E.g. missing required params or invalid input types.)

Headers
Content-Type: text/javascript
Body
{
    "status": 400,
    "error": {
        "message": "Invalid ttl",
        "source": "authz",
        "details": [
        {
            "message": "Valid range is 1 minute to 30 days.",
            "location": "ttl",
            "locationType": "body"
        }
        ]
    },
    "service": "Access Manager"
}
Response  403

Invalid signature. (E.g. wrong secret key or character set encoding for signature computation.)

Headers
Content-Type: text/javascript
Body
{
    "status": 403,
    "error": {
        "message": "Invalid signature",
        "source": "authz",
        "details": [
        {
            "message": "Client and server produced different signatures for the same inputs.",
            "location": "signature",
            "locationType": "query"
        }
        ]
    },
    "service": "Access Manager"
}

Auth Token JSON Schema for PAM v3

The following JSON schema defines the authorization token format used by PAM v3.

{
  "definitions": {
    "bitmask": {
      "$id": "#bitmask",
      "type": "integer",
      "title": "Permission BitMask",
      "default": 0,
      "examples": [
        11
      ]
    }
  },
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://github.com/pubnub/rfcs/resources/pam-v3/schema-v2.json",
  "type": "object",
  "title": "Pam v3 Auth Token version 2",
  "$comment": "Version 2 adds support for User-Objects and Space-Objects.",
  "required": [
    "v",
    "t",
    "ttl",
    "res",
    "pat",
    "meta",
    "sig"
  ],
  "additionalProperties": false,
  "properties": {
    "v": {
      "type": "integer",
      "title": "Auth Token Version Number",
      "minimum": 2,
      "maximum": 2
    },
    "s": {
      "type": "string",
      "title": "Sub-Key that owns this token",
      "description": "NOTE: This field is implied; it does not exist in actual tokens.",
      "examples": [
        "demo"
      ]
    },
    "t": {
      "type": "integer",
      "title": "Timestamp",
      "description": "Token is not valid before Timestamp",
      "examples": [
        1563226304
      ]
    },
    "ttl": {
      "type": "integer",
      "title": "Time-To-Live in minutes",
      "description": "Token is not valid after Timestamp + TTL * 60",
      "minimum": 1,
      "maximum": 43200,
      "examples": [
        1440
      ]
    },
    "res": {
      "type": "object",
      "title": "A mapping of resource types to resource IDs",
      "required": [
        "chan",
        "grp",
        "usr",
        "spc"
      ],
      "additionalProperties": false,
      "properties": {
        "chan": {
          "type": "object",
          "title": "Channel ACLs",
          "additionalProperties": {
            "$ref": "#bitmask"
          }
        },
        "grp": {
          "type": "object",
          "title": "Channel-Group ACLs",
          "additionalProperties": {
            "$ref": "#bitmask"
          }
        },
        "usr": {
          "type": "object",
          "title": "User-Object ACLs",
          "additionalProperties": {
            "$ref": "#bitmask"
          }
        },
        "spc": {
          "type": "object",
          "title": "Space-Object ACLs",
          "additionalProperties": {
            "$ref": "#bitmask"
          }
        }
      }
    },
    "pat": {
      "type": "object",
      "title": "A mapping of resource types to reular expressions",
      "required": [
        "chan",
        "grp",
        "usr",
        "spc"
      ],
      "additionalProperties": false,
      "properties": {
        "chan": {
          "type": "object",
          "title": "Channel RegExp ACLs",
          "additionalProperties": {
            "$ref": "#bitmask"
          }
        },
        "grp": {
          "type": "object",
          "title": "Channel-Group RegExp ACLs",
          "additionalProperties": {
            "$ref": "#bitmask"
          }
        },
        "usr": {
          "type": "object",
          "title": "User-Object RegExp ACLs",
          "additionalProperties": {
            "$ref": "#bitmask"
          }
        },
        "spc": {
          "type": "object",
          "title": "Space-Object RegExp ACLs",
          "additionalProperties": {
            "$ref": "#bitmask"
          }
        }
      }
    },
    "meta": {
      "type": "object",
      "title": "Token Meta Data"
    },
    "sig": {
      "type": "array",
      "title": "Token digital signature",
      "description": "HMAC+SHA256 signed with a PubNub confidential signing key.",
      "$comment": "In the CBOR implementation, sig is a 256-bit bigint.",
      "items": {
        "type": "integer",
        "minimum": 0,
        "maximum": 255
      },
      "minItems": 32,
      "maxItems": 32
    }
  }
}

Presence

Presence is what enables us to say who (UUID) is on a where (channel), when, and how (state).

Identifying Users with UUID

Each REST call uses a URL parameter called UUID. A client's UUID is how the system differentiates one user from another. This is how the user Bob is being differentiated from the user Alice?—?by UUID.

Presence Events

If you are subscribed to a Presence channel, for any given UUID, you will see Presence events occur in real-time on that channel. Those events are named:

  • JOIN (Joined)

  • LEAVE (Explicitly Left)

  • TIMEOUT (Implicitly Left)

  • STATE-CHANGE

Presence events are idempotent – that is, the event will not be repeated (alerted) again until it transitions to another event.

Presence States

For any user, an optional "state" object may be attached to that user's UUID. This state may be set/changed at subscribe (Join) time, or anytime during the sustained Join lifecycle. Once a user transitions to TIMEOUT or LEAVE, that user's associated state (if any) is deleted from the server.

The Different Types of Presence Calls

There are three main classes of Presence methods

  1. The streaming, realtime, subscribe-based presence calls, generally implemented as presence()

  2. The ad-hoc, on-demand presence calls, such as [global_]here_now() and where_now(), get_state(), set_state(), and leave()

  3. Long running heartbeat calls, configured via subscribe initializer, and/or via set_hb() and set_hb_interval()

Streaming Presence Calls

To get realtime Presence Events as they occur, subscribe to the presence variant of a channel name. The variant name is the channel you wish to monitor events for, appended with "-pnpres". For example, to subscribe to presence for channel foo, under the hood, we subscribe to channel "foo-pnpres".

Aside from the channel name (channel-pnpres) and the structured data that one can expect from a presence call (vs the relatively random nature of the structured data from user data), there is nothing technically different from a presence call vs a subscribe call.

Ad-hoc, On-demand Presence Calls

In addition to the "fire and forget" streaming presence calls, there are a group of calls that can be called anytime to get the current presence and state information for a given UUID. These methods are:

  • here_now - Who is here, now, on this channel [on this subscribe key]?

  • global_here_now - Who is here, now, on this subscribe-key?

  • where_now - Where (which channels) is this UUID currently subscribed on [on this subscribe-key]?

  • get_state - Give me the Presence state info for a given UUID.

  • set_state - Set the Presence state info for a given UUID.

Long running heartbeat calls

By default, the server expects the client to respond to either an intentially published message, or an empty server "ping" (issued every 270s) within 290s. When this doesn't happen, the Server will transition the UUID from "Join" to "Timeout". (When this does happen as expected, there is no transition – the UUID stays in "Join".)

Some customers require a greater precision to detect a UUID's presence than 270s. To fulfill that requirement, an additional heartbeat (HB) call can be set to "ping", from the client, every n seconds. When this HB is enabled a long-running HB process is started on the client, which will connect to the server every HB-Interval (HBI) seconds.

Using this HB scheme, it's possible to inform the Presence system "if you don't hear from me within x seconds, mark me as TIMEOUT."

By default, if the client is set for a HB of x, the HBI is automatically set to x / 2 - 1. This enables, by default, that under excellent to average-bad network scenarios, the client should be able to "ping" the Presence server between 1 and 2 times before its HB timeout limit.

The user can always override the default HBI to a lower value, but it's important to keep in mind that making this chattier demands extra battery and network resources.

Heartbeat has no functional effect on the performance or integrity of the client itself. Its only provided for Presence functionality.

Heartbeat is the mechanism used to 'ping' back from the client to the server that the client is still online. The heartbeat is only germane to the Presence service.

It affects presence in the following ways:

  • Subscribe calls and Heartbeat calls count as heartbeat signals to Presence?—?but only on the server RESPONSE does the heartbeat signal register.

  • Since a subscribe call can long poll, the server RESPONSE to the subscribe REQUEST may not be immediate (could be many minutes), so it's not always beneficial to rely on only the subscribe call as the heartbeat.

  • Since the server will RESPOND immediately to the client HP REST API call REQUEST, using the heartbeat call, in concert with subscribe calls, is the perfect method to registering heartbeats with the Presence system.

Transitioning Between Presence Events

Non-Present to Present (Emitting a Join Event)

  • To be "Present", you must go from "Non-Present" to "Present" by subscribing to a channel, and/or sending heartbeats to that channel.

  • Going from "Non-Present" to "Present" emits a "JOIN" event within the Presence system.

  • If the system continues to hear Heartbeats and/or subscribe requests from this client within HEARTBEAT timeout seconds, you will remain "Present".

  • If the client is not currently "JOINED" to a channel, a client heartbeat or subscribe call will create a JOIN event.

  • If the client is currently "JOINED" to a channel, and the server hears the heartbeat or subscribe within HEARTBEAT seconds, the server resets the heartbeat timer, and keeps the client "JOINED" to the channel.

Present back to Not-Present (Emitting a Timeout or Leave Event)

  • The client issues a LEAVE REST call, and stops sending subscribe requests and heartbeat requests. This will generate a "LEAVE" Presence event.

  • The client does not issue a LEAVE REST call, but the server no longer receives subscribe or heartbeat requests from the client within HEARTBEAT timeout seconds. This will generate a "TIMEOUT" Presence event.

  • Once "Not-Present", you can always be "Present" again by repeating this process by subscribing and/or sending a heartbeat.

  • If the client is currently "JOINED" to a channel, and the server DOES NOT hear the heartbeat or subscribe within HEARTBEAT seconds, the server will issue a "LEAVE" event for that client.

Heartbeat

Inform presence server user is still active. If user has not been seen before, user will join the channel and send a "join event".

Announce HeartbeatGET/v2/presence/sub_key/{sub_key}/channel/{channel}/heartbeat{?callback,channel-group,heartbeat,state,uuid}

Example URI

GET https://ps.pndsn.com/v2/presence/sub_key/'mySubKey'/channel/'ch1,ch2'/heartbeat?callback=myFunction&heartbeat=120&state=%7B%22text%22%3A%22hey%22%7D&uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
URI Parameters
HideShow
sub_key
string (required) Example: 'mySubKey'

Your PubNub Subscribe API Key

channel
string (required) Example: 'ch1,ch2'

The channel name for which the new state will be applied. Verify that channels are comprised of valid characters. May be a single channel, or multiple channels, separated by comma.

callback
string (required) Example: myFunction

JSONP callback name, or 0 if none.

heartbeat
number (optional) Example: 120

Used to set the presence timeout period. It overrides the default value of 300 for Presence Timeout.

channel-group
string (optional) Example: cg1,cg2,cg3

Channel group name(s) to subscribe to. If subscribing to more than one channel group, use a comma separator between channel group names. You may subscribe to channels, channels & channel groups, or just channel groups.

state
string (required) Example: %7B%22text%22%3A%22hey%22%7D

When state is set, this value is an object with root keys associated with each channel you are setting state for. You must be subscribed to a channel to set state for it. (Refer to the get/set state sections)

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

Request  Heartbeat
HideShow
Headers
Location: /v2/presence/sub_key/demo/channel/ch1/heartbeat?uuid=PubNubUnityExample&auth=authKey
Response  200
HideShow
Headers
Location: /v2/presence/sub_key/demo/channel/ch1/heartbeat?uuid=PubNubUnityExample&auth=authKey
Content-Type: application/json
Body
{  
    "status": 200,
    "message": "OK",  
    "service": "Presence"
}

Setting User State

Set state for a user for a channel(s) and/or channel-group(s).

Setting User StateGET/v2/presence/sub-key/{sub_key}/channel/{channel}/uuid/{uuid}/data{?state,callback}

Example URI

GET https://ps.pndsn.com/v2/presence/sub-key/mySubKey/channel/ch1/uuid/db9c5e39-7c95-40f5-8d71-125765b6f561/data?state=%7B%22text%22%3A%22hey%22%7D&callback=myFunction
URI Parameters
HideShow
sub_key
string (required) Example: mySubKey

Your PubNub Subscribe API Key

channel
string (required) Example: ch1

The channel name(s) you are applying the state to. Verify that channels are comprised of valid characters. You may update state to mulitple channels using a comma seperator. If applying state to no channels (only channel groups), use a comma char (,) as a placeholder. You may apply state to channels, channels & channel groups, or just channel groups.

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

channel-group
string (optional) Example: cg1,cg2,cg3

Channel group name(s) to which you are applying the new state. If applying state to more than one channel group, use a comma separator between channel group names. You may apply state to channels, channels & channel groups, or just channel groups.

callback
string (optional) Example: myFunction

If provided, wraps the response in function (JSONP)

state
string (required) Example: %7B%22text%22%3A%22hey%22%7D

url-encoded json which will be associated with the UUID for the channels and/or channel groups

Request  Setting User State
HideShow
Headers
Location: /v2/presence/sub-key/mySubKey/channel/ch1/uuid/db9c5e39-7c95-40f5-8d71-125765b6f561/data?state=%7B%22text%22%3A%22hey%22%7D&callback=0
Response  200
HideShow
Headers
Location: /v2/presence/sub-key/mySubKey/channel/ch1/uuid/db9c5e39-7c95-40f5-8d71-125765b6f561/data?state=%7B%22text%22%3A%22hey%22%7D&callback=0
Content-Type: application/json
Body
{
    "service": "presence",
    "status": "200",
    "error": false,
    "message": "OK",
    "payload": "{text:hey}"
}

Getting User State

Get state for a user for a channel(s) and/or channel-group(s).

Getting User StateGET/v2/presence/sub-key/{sub_key}/channel/{channel}/uuid{?callback}

Example URI

GET https://ps.pndsn.com/v2/presence/sub-key/mySubKey/channel/ch1/uuid?callback=myFunction
URI Parameters
HideShow
sub_key
string (required) Example: mySubKey

Your PubNub Subscribe API Key

channel
string (required) Example: ch1

The channel name(s) you are fetching the state for. Verify that channels are comprised of valid characters. You may fetch state for mulitple channels using a comma seperator. If fetching state to no channels (only channel groups), use a comma char (,) as a placeholder. You may fetch state to channels, channels & channel groups, or just channel groups.

channel-group
string (optional) Example: cg1,cg2,cg3

Channel group name(s) to which you are fetching the state. If fetching state for more than one channel group, use a comma separator between channel group names. You may fetch state for channels, channels & channel groups, or just channel groups.

callback
string (optional) Example: myFunction

If provided, wraps the response in function (JSONP)

Request  Getting User State
HideShow
Headers
Location: /v2/presence/sub-key/mySubKey/channel/ch1/uuid/db9c5e39-7c95-40f5-8d71-125765b6f561?state=%7B%22text%22%3A%22hey%22%7D&callback=0
Response  200
HideShow
Headers
Location: /v2/presence/sub-key/mySubKey/channel/ch1/uuid/db9c5e39-7c95-40f5-8d71-125765b6f561?state=%7B%22text%22%3A%22hey%22%7D&callback=0
Content-Type: application/json
Body
{
    "service": "presence",
    "status": "200",
    "error": false,
    "message": "OK",
    "payload": "{text:hey}"
}

Announce Leave

Indicate to the PubNub Presence system that a device has left a channel(s).

via GETGET/v2/presence/sub_key/{sub_key}/channel/{channel}/leave{?callback,uuid}

Example URI

GET https://ps.pndsn.com/v2/presence/sub_key/mySubKey/channel/ch1/leave?callback=myFunction&uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
URI Parameters
HideShow
sub_key
string (required) Example: mySubKey

Your PubNub Subscribe API Key

channel
string (required) Example: ch1

The channel name(s), separated by comma, that you wish to send leave events for. Verify that channels are comprised of valid characters.

channel-group
string (optional) Example: cg1,cg2,cg3

The channel group name(s), separated by comma, that you wish to send leave events for. Verify that channels are comprised of valid characters. You may leave channels, channels & channel groups, or just channel groups.

callback
string (optional) Example: myFunction

If provided, wraps the response in function (JSONP)

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

Request  Announce Leave
HideShow
Headers
Location: /v2/presence/sub-key/demo/channel/ch1/leave?pnsdk=PubNub-Go/4.2.4&uuid=pn-6ee661a1-85f5-406b-b3c7-e20ca07c07ba&auth=akey&timestamp=1565094167
Response  200
HideShow
Headers
Location: /v2/presence/sub-key/demo/channel/ch1/leave?pnsdk=PubNub-Go/4.2.4&uuid=pn-6ee661a1-85f5-406b-b3c7-e20ca07c07ba&auth=akey&timestamp=1565094167
Content-Type: application/json
Body
{  
    "status": 200,
    "message": "OK",  
    "action": "leave",  
    "service": "Presence"
}

via POSTPOST/v2/presence/sub_key/{sub_key}/channel/{channel}/leave{?callback,uuid}

Example URI

POST https://ps.pndsn.com/v2/presence/sub_key/mySubKey/channel/ch1/leave?callback=myFunction&uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
URI Parameters
HideShow
sub_key
string (required) Example: mySubKey

Your PubNub Subscribe API Key

channel
string (required) Example: ch1

The channel name(s), separated by comma, that you wish to send leave events for. Verify that channels are comprised of valid characters.

channel-group
string (optional) Example: cg1,cg2,cg3

The channel group name(s), separated by comma, that you wish to send leave events for. Verify that channels are comprised of valid characters. You may leave channels, channels & channel groups, or just channel groups.

callback
string (optional) Example: myFunction

If provided, wraps the response in function (JSONP)

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

Here Now

Retrieve UUID and State Information for subscribed devices on a specific channel.

Here NowGET/v2/presence/sub-key/{sub_key}/channel/{channel}{?disable_uuids,state,callback,uuid}

Example URI

GET https://ps.pndsn.com/v2/presence/sub-key/'mySubKey'/channel/'ch1,ch2'?disable_uuids=0&state=0&callback=myFunction&uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
URI Parameters
HideShow
sub_key
string (required) Example: 'mySubKey'

Your PubNub Subscribe API Key

channel
string (required) Example: 'ch1,ch2'

The channel name you wish to pull history from. Verify that channels are comprised of valid characters. May be a single channel, or multiple channels, separated by comma.

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

callback
string (optional) Example: myFunction

If provided, returns a JSONP function-wrapped response.

disable_uuids
string (optional) Example: 0

If true or 1, or not provided, UUIDS, and accompanying state info, will not be returned, only occupancy numbers. If 0, or false, UUIDS, will be returned with occupancy numbers.

channel-group
string (optional) Example: cg1,cg2,cg3

Comma delimited list of channel groups that presence should be returned for as well. When channel-groups are included, the response format will be different than when channel-groups are not included, that is, the Global Here Now response format will be returned.

state
string (optional) Example: 0

If false or 0, state info is not returned. If true or 1, AND disable_uuids is false, accompanying state info for each UUID is provided.

Request  Here Now
HideShow
Headers
Location: /v2/subscribe/demo/ch,ch-pnpres/0?q1=v1&auth=akey&timestamp=1565093044&heartbeat=120&tt=15650930446689601&q2=v2&uuid=pn-4152c98f-0b60-404c-9719-c42dbf8fc246
Response  200
HideShow
Headers
Location: /v2/subscribe/demo/ch,ch-pnpres/0?q1=v1&auth=akey&timestamp=1565093044&heartbeat=120&tt=15650930446689601&q2=v2&uuid=pn-4152c98f-0b60-404c-9719-c42dbf8fc246
Content-Type: application/json
Body
{ 
    "status": 200,
    "message": "OK",  
    "occupancy": 1,  
    "uuids": ["pn-4152c98f-0b60-404c-9719-c42dbf8fc246"],
    "service": "Presence"
}

Global Here Now

Retrieve UUID and State Information for subscribed devices on a all channels. This is exactly like Here Now, except without a channel path / channel group query string parameter.

Global Here NowGET/v2/presence/sub-key/{sub_key}{?disable_uuids,state,callback,uuid}

Example URI

GET https://ps.pndsn.com/v2/presence/sub-key/'mySubKey'?disable_uuids=0&state=0&callback=myFunction&uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
URI Parameters
HideShow
sub_key
string (required) Example: 'mySubKey'

Your PubNub Subscribe API Key

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

callback
string (optional) Example: myFunction

If provided, returns a JSONP function-wrapped response.

disable_uuids
string (optional) Example: 0

If true or 1, or not provided, UUIDS, and accompanying state info, will not be returned, only occupancy numbers. If 0, or false, UUIDS, will be returned with occupancy numbers.

channel-group
string (optional) Example: cg1,cg2,cg3

Comma delimited list of channel groups that presence should be returned for as well. When channel-groups are included, the response format will be different than when channel-groups are not included, that is, the Global Here Now response format will be returned.

state
string (optional) Example: 0

If false or 0, state info is not returned. If true or 1, AND disable_uuids is false, accompanying state info for each UUID is provided.

Request  Global Here Now
HideShow
Headers
Location: /v2/presence/sub_key/demo?timestamp=1565093958&pnsdk=PubNub-Go/4.2.4&uuid=pn-206f7b9d-d16c-48a7-b6ef-b05b9530df86&state=1&disable-uuids=0&auth=akey
Response  200
HideShow
Headers
Location: /v2/presence/sub_key/demo?timestamp=1565093958&pnsdk=PubNub-Go/4.2.4&uuid=pn-206f7b9d-d16c-48a7-b6ef-b05b9530df86&state=1&disable-uuids=0&auth=akey
Content-Type: application/json
Body
{
    "status": 200,
    "message": "OK",
    "payload": {
        "channels": {
            "81d8d989-b95f-443c-a726-04fac323b331": {
                "uuids": [
                    "70fc1140-22b5-4abc-85b2-ff8c17b24d59"
                ],
                "occupancy": 1
            },
            "81b7a746-d153-49e2-ab70-3037a75cec7e": {
                "uuids": [
                    "91363e7f-584b-49cc-822c-52c2c01e5928"
                ],
                "occupancy": 1
            },
            "c068d15e-772a-4bcd-aa27-f920b7a4eaa8": {
                "uuids": [
                    "ccfac1dd-b3a5-4afd-9fd9-db11aeb65395"
                ],
                "occupancy": 1
            }
        },
        "total_channels": 3,
        "total_occupancy": 3
    },
    "service": "Presence"
}

Where Now

Get list of channels user is present in.

Where NowGET/v2/presence/sub-key/{sub_key}/uuid/{uuid}{?callback,uuid}

Example URI

GET https://ps.pndsn.com/v2/presence/sub-key/'mySubKey'/uuid/db9c5e39-7c95-40f5-8d71-125765b6f561?callback=myFunction&uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
URI Parameters
HideShow
sub_key
string (required) Example: 'mySubKey'

Your PubNub Subscribe API Key

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

callback
string (optional) Example: myFunction

If provided, returns a JSONP function-wrapped response.

Request  Where Now
HideShow
Headers
Location: /v2/presence/sub-key/demo/uuid/pn-4152c98f-0b60-404c-9719-c42dbf8fc246?pnsdk=PubNub-Go/4.2.4&uuid=pn-4152c98f-0b60-404c-9719-c42dbf8fc246&auth=akey&timestamp=1565093804
Response  200
HideShow
Headers
Location: /v2/presence/sub-key/demo/uuid/pn-4152c98f-0b60-404c-9719-c42dbf8fc246?pnsdk=PubNub-Go/4.2.4&uuid=pn-4152c98f-0b60-404c-9719-c42dbf8fc246&auth=akey&timestamp=1565093804
Content-Type: application/json
Body
{
    "status": 200, 
    "message": "OK", 
    "payload": {
        "channels": [
            "my-channel"
        ]
    }, 
    "service": "Presence"
}

Push Notifications || APN & GCM

Authorize and Revoke push tokens for the Apple and Google Push Notification services.

The type parameter indicates the backend which PubNub will utilize:

  • apns - apple push notification service

  • gcm - google push notification service

  • mpns - microsoft push notification service

Publishing

Given a channel ch1, and subscribed mobile clients, a server SDK must execute a publish commend by sending the following JSON payload to ch1

{
    "pn_apns": {
        "aps": {
            "alert": "hi",
            "badge": 2,
            "sound": "melody"
        },
        "pn_other": {
            "additional": "fields"
        }
    }
}
{
  "pn_gcm": {

  },
  "pn_other": {
    "additional": "fields"
  }
}
  • microsoft push notification service
{
  "pn_mpns": {

  },
  "pn_other": {
    "additional": "fields"
  }
}

Please refer to the tutorial for additional examples

Listing registrations for device

Listing registrations for deviceGET/v1/push/sub-key/{sub_key}/devices/{push_token}{?type,uuid}

Example URI

GET https://ps.pndsn.com/v1/push/sub-key/mySubKey/devices/A332C23D?type=apns&uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
URI Parameters
HideShow
sub_key
string (required) Example: mySubKey

the subscriber key

push_token
string (required) Example: A332C23D

the push token of the device

type
string (required) 
  • indicates the backend to use (apns for apple, gcm for google, mpns for microsoft)
uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

Request  show all channels for device for apple services
HideShow
Headers
Location: /v1/push/sub-key/mySubKey/devices/A332C23D?type=apns
Response  200
HideShow
Headers
Content-Type: application/json
Body
+ [1, "Modified Channels"]
Request  show all channels for device for google services
HideShow
Headers
Location: /v1/push/sub-key/mySubKey/devices/A332C23D?type=gcm
Response  200
HideShow
Headers
Content-Type: application/json
Body
+ [] <!-- TODO -->
Request  show all channels for device for microsoft services
HideShow
Headers
Location: /v1/push/sub-key/mySubKey/devices/A332C23D?type=mpns
Response  200
HideShow
Headers
Content-Type: application/json
Body
+ [] <!-- TODO -->

Removing a Device

Removing all registrations for a deviceGET/v1/push/sub-key/{sub_key}/devices/{push_token}/remove{?type,uuid}

Example URI

GET https://ps.pndsn.com/v1/push/sub-key/mySubKey/devices/A332C23D/remove?type=apns&uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
URI Parameters
HideShow
sub_key
string (required) Example: mySubKey

the subscriber key

push_token
string (required) Example: A332C23D

the push token of the device

type
string (required) 
  • indicates the backend to use (apns for apple, gcm for google, mpns for microsoft)
uuid
string (optional) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

Request  Removing an Apple device from all push notifications
HideShow
Headers
Location: /v1/push/sub-key/mySubKey/devices/A332C23D/remove?type=apns
Response  200
HideShow
Headers
Content-Type: application/json
Request  Removing an Android device from all push notifications
HideShow
Headers
Location: /v1/push/sub-key/mySubKey/devices/A332C23D/remove?type=gcm
Response  200
HideShow
Headers
Content-Type: application/json
Request  Removing a microsoft device from all push notifications
HideShow
Headers
Location: /v1/push/sub-key/mySubKey/devices/A332C23D/remove?type=mpns
Response  200
HideShow
Headers
Content-Type: application/json

Adding Registrations

Adding registrationsGET/v1/push/sub-key/{sub_key}/devices/{push_token}{?uuid,auth,type,add}

Example URI

GET https://ps.pndsn.com/v1/push/sub-key/mySubKey/devices/A332C23D?uuid=db9c5e39-7c95-40f5-8d71-125765b6f561&auth=385dfa9c-6a16-4145-aaf9-043f0060c7d3&type=apns&add=channel1
URI Parameters
HideShow
sub_key
string (required) Example: mySubKey

the subscriber key

push_token
string (required) Example: A332C23D

the push token of the device

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

UUID of the client

auth
string (required) Example: 385dfa9c-6a16-4145-aaf9-043f0060c7d3

PAM authorization key

type
string (required) 
  • indicates the backend to use (apns for apple, gcm for google, mpns for microsoft)
add
string (required) Example: channel1

name of the channel to allow the device to recieve notifiactions for (mulitple channels are also supported by commad delimited (ch1,ch2,ch3) will add three channels)

Request  Subscribe a device to channel for apple services
HideShow
Headers
Location: /v1/push/sub-key/mySubKey/devices/A332C23D?uuid=appUUID&auth=MyAuth&type=apns&add=ch1
Response  200
HideShow
Headers
Content-Type: application/json
Body
+ [1, "Modified Channels"]
Request  Subscribe a device to channel for google services
HideShow
Headers
Location: /v1/push/sub-key/mySubKey/devices/A332C23D?uuid=appUUID&auth=MyAuth&type=gcm&add=ch1
Response  200
HideShow
Headers
Content-Type: application/json
Body
+ [1, "Modified Channels"]
Request  Subscribe a device to channel for microsoft services
HideShow
Headers
Location: /v1/push/sub-key/mySubKey/devices/A332C23D?uuid=appUUID&auth=MyAuth&type=mpns&add=ch1
Response  200
HideShow
Headers
Content-Type: application/json
Body
+ [1, "Modified Channels"]

Removing Registrations

Removing registrationsGET/v1/push/sub-key/{sub_key}/devices/{push_token}{?uuid,auth,type,remove}

Example URI

GET https://ps.pndsn.com/v1/push/sub-key/mySubKey/devices/A332C23D?uuid=db9c5e39-7c95-40f5-8d71-125765b6f561&auth=385dfa9c-6a16-4145-aaf9-043f0060c7d3&type=apns&remove=channel1
URI Parameters
HideShow
sub_key
string (required) Example: mySubKey

the subscriber key

push_token
string (required) Example: A332C23D

the push token of the device

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

UUID of the client

auth
string (required) Example: 385dfa9c-6a16-4145-aaf9-043f0060c7d3

PAM authorization key

type
string (required) 
  • indicates the backend to use (apns for apple, gcm for google, mpns for microsoft)
remove
string (required) Example: channel1

name of the channel for which the device will no longer recieve push notifications (mulitple channels are also supported by commad delimited (ch1,ch2,ch3) will remove three channels)

Request  Remove a device from push notifications for channel ch1 for apple services
HideShow
Headers
Location: /v1/push/sub-key/mySubKey/devices/A332C23D?uuid=appUUID&auth=MyAuth&type=apns&remove=ch1
Response  200
HideShow
Headers
Content-Type: application/json
Body
+ [1, "Modified Channels"]
Request  Remove a device from push notifications for channel ch1 for google services
HideShow
Headers
Location: /v1/push/sub-key/mySubKey/devices/A332C23D?uuid=appUUID&auth=MyAuth&type=gcm&remove=ch1
Response  200
HideShow
Headers
Content-Type: application/json
Body
+ [1, "Modified Channels"]
Request  Remove a device from push notifications for channel ch1 for microsoft services
HideShow
Headers
Location: /v1/push/sub-key/mySubKey/devices/A332C23D?uuid=appUUID&auth=MyAuth&type=mpns&remove=ch1
Response  200
HideShow
Headers
Content-Type: application/json
Body
+ [1, "Modified Channels"]

Mixing add & remove operations

Mixing add & remove operationsGET/v1/push/sub-key/{sub_key}/devices/{push_token}{?uuid,auth,type,add,remove}

Mixing the addition and removal operations will be executed in the following order:

  1. channels passed in the remove will be removed from the registrations list for the device

  2. channels passed in the add will be added to the registrations list for the device

Example URI

GET https://ps.pndsn.com/v1/push/sub-key/mySubKey/devices/A332C23D?uuid=db9c5e39-7c95-40f5-8d71-125765b6f561&auth=385dfa9c-6a16-4145-aaf9-043f0060c7d3&type=apns&add=channel1&remove=channel1
URI Parameters
HideShow
sub_key
string (required) Example: mySubKey

the subscriber key

push_token
string (required) Example: A332C23D

the push token of the device

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

UUID of the client

auth
string (required) Example: 385dfa9c-6a16-4145-aaf9-043f0060c7d3

PAM authorization key

type
string (required) 
  • indicates the backend to use (apns for apple, gcm for google, mpns for microsoft)
add
string (required) Example: channel1

comma delimited channels to allow the device to recieve notifiactions for. Also supports comma delited list for multiple channels. ch1,ch2,ch3 will add three channels

remove
string (required) Example: channel1

commad delimited channels for which the device will no longer recieve push notifications. Also supports comma delited list for multiple channels. (ch1,ch2,ch3) will remove three channels

Request  Remove a device from push notifications for channels ch1,ch2 for apple services
HideShow
Headers
Location: /v1/push/sub-key/mySubKey/devices/A332C23D?uuid=appUUID&auth=MyAuth&type=apns&remove=ch1,ch2
Response  200
HideShow
Headers
Content-Type: application/json
Body
+ [1, "Modified Channels"]
Request  Remove a device from push notifications for channels ch1,ch2 for google services
HideShow
Headers
Location: /v1/push/sub-key/mySubKey/devices/A332C23D?uuid=appUUID&auth=MyAuth&type=gcm&remove=ch1,ch2
Response  200
HideShow
Headers
Content-Type: application/json
Body
+ [1, "Modified Channels"]
Request  Remove a device from push notifications for channels ch1,ch2 for microsoft services
HideShow
Headers
Location: /v1/push/sub-key/mySubKey/devices/A332C23D?uuid=appUUID&auth=MyAuth&type=mpns&remove=ch1,ch2
Response  200
HideShow
Headers
Content-Type: application/json
Body
+ [1, "Modified Channels"]

Objects (BETA)

 

The PubNub Objects API enables you to create and retrieve data associated with key objects in the PubNub realtime application platform.

 Objects is an optional feature, currently in a BETA release—you can use your own user management system, and simply use the usual publish and subscribe. If you'd like to use PubNub's serverless storage, Objects provides a full-featured solution.

User

Manage one or more users

Get all usersGET/v1/objects/{sub_key}/users{?include,limit,start,end,count,auth}

Returns a paginated list of users associated with the given subscription key, optionally including each user record's custom data object.

Example URI

GET https://ps.pndsn.com/v1/objects/demo/users/user-1?include=custom?limit=10&count=true
Path Parameters
sub_key

string (required) Example: mySubKey
The subscriber key.

Query Parameters
include

array[string] (optional)  Available values : custom
List of additional/complex user properties to include in response. Omit this query parameter if you don't want to retrieve additional properties.

limit

integer (optional)  Default value: 100
Number of objects to return in response. Default is 100, which is also the maximum value.

start

string (optional) 
Previously-returned cursor bookmark for fetching the next page.

end

string (optional) 
Previously-returned cursor bookmark for fetching the previous page. Ignored if you also supply the start parameter.

count

boolean (optional)  Example: true
Request totalCount to be included in paginated response. By default, totalCount is omitted.

auth

string (optional) 
Authorization key with permissions to perform the request.
If Access Manager is enabled, either a valid authorization token or a signature are required.
See Access Manager documentation for details on how to obtain an authorization token.

Response  200

Successfully returned the list of users.

Headers
Content-Type: application/json
Body
{
    "status": 200,
    "data": [
        {
            "id": "user-1",
            "name": "John Doe",
            "externalId": null,
            "profileUrl": null,
            "email": "jack@twitter.com",
            "custom": null,
            "created": "2019-02-20T23:11:20.893755",
            "updated": "2019-02-20T23:11:20.893755",
            "eTag": "MDcyQ0REOTUtNEVBOC00QkY2LTgwOUUtNDkwQzI4MjgzMTcwCg=="
        },
        {
            "id": "user-2",
            "name": "Bob Cat",
            "externalId": null,
            "profileUrl": null,
            "email": "bobc@example.com",
            "custom": {
                "phone": "999-999-9999"
            },
            "created": "2019-02-19T13:10:20.893755",
            "updated": "2019-02-21T03:29:00.173452",
            "eTag": "QkRENDA5MjItMUZCNC00REI5LUE4QTktRjJGNUMxNTc2MzE3Cg=="
        }
    ]
}
Response  304

Requested resource has not been modified since last retrieval.

Response  403

The client isn’t authorized to perform this operation. Either the authorization key you provided doesn’t have the required permissions for this operation, or the signature is invalid.

Response  429

Request rate limit exceeded.

Response  500

An internal server error ocurred.

Response  503

Request processing exceeded the maximum allowed time.

Create a userPOST/v1/objects/{sub_key}/users{?include,auth}

Creates a user with the specified properties. Returns the created user object, optionally including the user's custom data object.

Example URI

POST https://ps.pndsn.com/v1/objects/demo/users?include=custom
Path Parameters
sub_key

string (required) Example: mySubKey
The subscriber key.

Query Parameters
include

array[string] (optional) Available values: custom
List of additional/complex user properties to include in response. Omit this query parameter if you don't want to retrieve additional properties.

auth

string (optional) 
Authorization key with permissions to perform the request.
If Access Manager is enabled, either a valid authorization token or a signature are required.
See Access Manager documentation for details on how to obtain an authorization token.

Request  required

JSON object with user properties.

Headers
Content-Type: application/json
Body
{
    "id": "user-1",
    "name": "John Doe",
    "externalId": null,
    "profileUrl": null,
    "email": "jack@twitter.com"
}
Response  200

Successfully created the user.

Headers
Content-Type: application/json
Body
{
    "status": 200,
    "data": {
        "id": "user-1",
        "name": "John Doe",
        "externalId": null,
        "profileUrl": null,
        "email": "jack@twitter.com",
        "created": "2019-02-20T23:11:20.893755",
        "updated": "2019-02-20T23:11:20.893755",
        "eTag": "MDcyQ0REOTUtNEVBOC00QkY2LTgwOUUtNDkwQzI4MjgzMTcwCg=="
    }
}
Response  400

The request body contains invalid data.

Response  403

The client isn’t authorized to perform this operation. Either the authorization key you provided doesn’t have the required permissions for this operation, or the signature is invalid.

Response  409

An object with the given identifier already exists.

Response  415

The format of the request body you supplied isn't supported. The request body must be in JSON format.

Response  429

Request rate limit exceeded.

Response  500

An internal server error ocurred.

Response  503

Request processing exceeded the maximum allowed time.

Fetch a userGET/v1/objects/{sub_key}/users/{user_id}{?include,auth}

Returns the specified user object, optionally including the user's custom data object.

Example URI

GET https://ps.pndsn.com/v1/objects/demo/users/user-1?include=custom
Path Parameters
sub_key

string (required) Example: mySubKey
The subscriber key.

user_id

string (required) Example: charlie
The user identifier.

Query Parameters
include

array[string] (optional) Available values: custom
List of additional/complex user properties to include in response. Omit this query parameter if you don't want to retrieve additional properties.

auth

string (optional) 
Authorization key with permissions to perform the request.
If Access Manager is enabled, either a valid authorization token or a signature are required.
See Access Manager documentation for details on how to obtain an authorization token.

Response  200

Successfully fetched the requested user.

Headers
Content-Type: application/json
Body
{
    "status": 200,
    "data": {
        "id": "user-1",
        "name": "John Doe",
        "externalId": null,
        "profileUrl": null,
        "email": "jack@twitter.com",
        "created": "2019-02-20T23:11:20.893755",
        "updated": "2019-02-20T23:11:20.893755",
        "eTag": "MDcyQ0REOTUtNEVBOC00QkY2LTgwOUUtNDkwQzI4MjgzMTcwCg=="
    }
}
Response  304

Requested resource has not been modified since last retrieval.

Response  403

The client isn’t authorized to perform this operation. Either the authorization key you provided doesn’t have the required permissions for this operation, or the signature is invalid.

Response  404

The requested object was not found.

Response  429

Request rate limit exceeded.

Response  500

An internal server error ocurred.

Response  503

Request processing exceeded the maximum allowed time.

Update a userPATCH/v1/objects/{sub_key}/users/{user_id}{?include,auth}

Updates the specified user object with any new information you provide. Returns the updated user object, optionally including the user's custom data object.

Example URI

PATCH https://ps.pndsn.com/v1/objects/demo/users/user-1?include=custom
Path Parameters
sub_key

string (required) Example: mySubKey
The subscriber key.

user_id

string (required) Example: charlie
The user identifier.

Query Parameters
include

array[string] (optional) Available values: custom
List of additional/complex user properties to include in response. Omit this query parameter if you don't want to retrieve additional properties.

auth

string (optional) 
Authorization key with permissions to perform the request.
If Access Manager is enabled, either a valid authorization token or a signature are required.
See Access Manager documentation for details on how to obtain an authorization token.

Request  required

JSON object with user properties to update.

Headers
Content-Type: application/json
Body
{
    "id": "user-1",
    "name": "John Doe",
    "externalId": null,
    "profileUrl": null,
    "email": "jack@twitter.com"
}
Response  200

Successfully updated the user.

Headers
Content-Type: application/json
Body
{
    "status": 200,
    "data": {
        "id": "user-1",
        "name": "John Doe",
        "externalId": null,
        "profileUrl": null,
        "email": "jack@twitter.com",
        "created": "2019-02-20T23:11:20.893755",
        "updated": "2019-02-20T23:11:20.893755",
        "eTag": "MDcyQ0REOTUtNEVBOC00QkY2LTgwOUUtNDkwQzI4MjgzMTcwCg=="
    }
}
Response  400

The request body contains invalid data.

Response  403

The client isn’t authorized to perform this operation. Either the authorization key you provided doesn’t have the required permissions for this operation, or the signature is invalid.

Response  404

The requested object was not found.

Response  412

Conditional operation cannot be performed because the target object has changed since the last retrieval.

Response  415

The format of the request body you supplied isn't supported. The request body must be in JSON format.

Response  429

Request rate limit exceeded.

Response  500

An internal server error ocurred.

Response  503

Request processing exceeded the maximum allowed time.

Delete a userDELETE/v1/objects/{sub_key}/users/{user_id}{?auth}

Deletes the specified user.

Example URI

DELETE https://ps.pndsn.com/v1/objects/demo/users/user-1
Path Parameters
sub_key

string (required) Example: mySubKey
The subscriber key.

user_id

string (required) Example: charlie
The user identifier.

Query Parameters
auth

string (optional) 
Authorization key with permissions to perform the request.
If Access Manager is enabled, a valid authorization token or valid signature is required.
See Access Manager documentation for details on how to obtain an authorization token.

Response  200

Successfully deleted the user.

Headers
Content-Type: application/json
Body
{
    "status": "0",
    "data": {}
}
Response  403

The client isn’t authorized to perform this operation. Either the authorization key you provided doesn’t have the required permissions for this operation, or the signature is invalid.

Response  412

Conditional operation cannot be performed because the target object has changed since the last retrieval.

Response  429

Request rate limit exceeded.

Response  500

An internal server error ocurred.

Response  503

Request processing exceeded the maximum allowed time.


Space

Manage spaces

Get all spacesGET/v1/objects/{sub_key}/spaces{?include,limit,start,end,count,auth}

Returns the spaces associated with the given subscriber key, optionally including each space's custom data object.

Example URI

GET https://ps.pndsn.com/v1/objects/demo/spaces?include=custom?limit=10&count=true
Path Parameters
sub_key

string (required) Example: mySubKey
The subscriber key.

Query Parameters
include

array[string] (optional)  Available values : custom
List of additional/complex properties to include in response. Omit this query parameter if you don't want to retrieve additional properties.

limit

integer (optional)  Default value: 100
Number of objects to return in response. Default is 100, which is also the maximum value.

start

string (optional) 
Previously-returned cursor bookmark for fetching the next page.

end

string (optional) 
Previously-returned cursor bookmark for fetching the previous page. Ignored if you also supply the start parameter.

count

boolean (optional)  Example: true
Request totalCount to be included in paginated response. By default, totalCount is omitted.

auth

string (optional) 
Authorization key with permissions to perform the request.
If Access Manager is enabled, either a valid authorization token or a signature are required.
See Access Manager documentation for details on how to obtain an authorization token.

Response  200

Successfully returned the list of spaces.

Headers
Content-Type: application/json
Body
{
    "status": 200,
    "data": [
        {
            "id": "my-channel",
            "name": "My space",
            "description": "A space that is mine",
            "custom": null,
            "created": "2019-02-20T23:11:20.893755",
            "updated": "2019-02-20T23:11:20.893755",
            "eTag": "RTc1NUQwNUItREMyNy00Q0YxLUJCNDItMEZDMTZDMzVCN0VGCg=="
        },
        {
            "id": "main",
            "name": "Main space",
            "description": "The main space",
            "custom": {
                "public": true,
                "motd": "Always check your spelling!"
            },
            "created": "2019-02-20T23:11:20.893755",
            "updated": "2019-02-20T23:11:20.893755",
            "eTag": "RTc1NUQwNUItREMyNy00Q0YxLUJCNDItMEZDMTZDMzVCN0VGCg=="
        }
    ],
    "totalCount": 9,
    "next": "MUIwQTAwMUItQkRBRC00NDkyLTgyMEMtODg2OUU1N0REMTNBCg==",
    "prev": "M0FFODRENzMtNjY2Qy00RUExLTk4QzktNkY1Q0I2MUJFNDRCCg=="
}
Response  304

Requested resource has not been modified since last retrieval.

Response  403

The client isn’t authorized to perform this operation. Either the authorization key you provided doesn’t have the required permissions for this operation, or the signature is invalid.

Response  429

Request rate limit exceeded.

Response  500

An internal server error ocurred.

Response  503

Request processing exceeded the maximum allowed time.

Create a spacePOST/v1/objects/{sub_key}/spaces{?include,auth}

Creates a space with the specified properties. Returns the created space object, optionally including its custom data object.

Example URI

POST https://ps.pndsn.com/v1/objects/demo/spaces
Path Parameters
sub_key

string (required) Example: mySubKey
The subscriber key.

Query Parameters
include

array[string] (optional)  Available values : custom
List of additional/complex properties to include in response. Omit this query parameter if you don't want to retrieve additional properties.

auth

string (optional) 
Authorization key with permissions to perform the request.
If Access Manager is enabled, either a valid authorization token or a signature are required.
See Access Manager documentation for details on how to obtain an authorization token.

Request  required

JSON object with space properties.

Headers
Content-Type: application/json
Body
{
    "id": "my-channel",
    "name": "My space",
    "description": "A space that is mine"
}
Response  200

Successfully created the space.

Headers
Content-Type: application/json
Body
{
    "status": 200,
    "data": {
        "id": "my-channel",
        "name": "My space",
        "description": "A space that is mine",
        "created": "2019-02-20T23:11:20.893755",
        "updated": "2019-02-20T23:11:20.893755",
        "eTag": "RTc1NUQwNUItREMyNy00Q0YxLUJCNDItMEZDMTZDMzVCN0VGCg=="
    }
}
Response  400

The request body contains invalid data.

Response  403

The client isn’t authorized to perform this operation. Either the authorization key you provided doesn’t have the required permissions for this operation, or the signature is invalid.

Response  409

An object with the given identifier already exists.

Response  415

The format of the request body you supplied isn't supported. The request body must be in JSON format.

Response  429

Request rate limit exceeded.

Response  500

An internal server error ocurred.

Response  503

Request processing exceeded the maximum allowed time.

Get a spaceGET/v1/objects/{sub_key}/spaces/{space_id}{?include,auth}

Returns the specified space, optionally including its custom data object.

Example URI

GET https://ps.pndsn.com/v1/objects/demo/spaces/space-1?include=custom
Path Parameters
sub_key

string (required) Example: mySubKey
The subscriber key.

space_id

string (required) Example: main
The space identifier.

Query Parameters
include

array[string] (optional)  Available values : custom
List of additional/complex properties to include in response. Omit this query parameter if you don't want to retrieve additional properties.

auth

string (optional) 
Authorization key with permissions to perform the request.
If Access Manager is enabled, either a valid authorization token or a signature are required.
See Access Manager documentation for details on how to obtain an authorization token.

Response  200

Successfully returned the requested space.

Headers
Content-Type: application/json
Body
{
    "status": 200,
    "data": {
        "id": "my-channel",
        "name": "My space",
        "description": "A space that is mine",
        "created": "2019-02-20T23:11:20.893755",
        "updated": "2019-02-20T23:11:20.893755",
        "eTag": "RTc1NUQwNUItREMyNy00Q0YxLUJCNDItMEZDMTZDMzVCN0VGCg=="
    }
}
Response  304

Requested resource has not been modified since last retrieval.

Response  403

The client isn’t authorized to perform this operation. Either the authorization key you provided doesn’t have the required permissions for this operation, or the signature is invalid.

Response  404

The requested object was not found.

Response  429

Request rate limit exceeded.

Response  500

An internal server error ocurred.

Response  503

Request processing exceeded the maximum allowed time.

Update a spacePatch/v1/objects/{sub_key}/spaces/{space_id}{?include,auth}

Updates the specified space. Returns the space object, optionally including its custom data object.

Example URI

PATCH https://ps.pndsn.com/v1/objects/demo/spaces/space-1?include=custom
Path Parameters
sub_key

string (required) Example: mySubKey
The subscriber key.

space_id

string (required) Example: main
The space identifier.

Query Parameters
include

array[string] (optional)  Available values : custom
List of additional/complex properties to include in response. Omit this query parameter if you don't want to retrieve additional properties.

auth

string (optional) 
Authorization key with permissions to perform the request.
If Access Manager is enabled, either a valid authorization token or a signature are required.
See Access Manager documentation for details on how to obtain an authorization token.

Request  required

JSON object with space properties to update.

Headers
Content-Type: application/json
Body
{
    "id": "my-channel",
    "name": "My space",
    "description": "A space that is mine"
}
Response  200

Successfully updated the space.

Headers
Content-Type: application/json
Body
{
    "status": 200,
    "data": {
        "id": "my-channel",
        "name": "My space",
        "description": "A space that is mine",
        "created": "2019-02-20T23:11:20.893755",
        "updated": "2019-02-20T23:11:20.893755",
        "eTag": "RTc1NUQwNUItREMyNy00Q0YxLUJCNDItMEZDMTZDMzVCN0VGCg=="
    }
}
Response  400

The request body contains invalid data.

Response  403

The client isn’t authorized to perform this operation. Either the authorization key you provided doesn’t have the required permissions for this operation, or the signature is invalid.

Response  404

The requested object was not found.

Response  412

Conditional operation cannot be performed because the target object has changed since the last retrieval.

Response  415

The format of the request body you supplied isn't supported. The request body must be in JSON format.

Response  429

Request rate limit exceeded.

Response  500

An internal server error ocurred.

Response  503

Request processing exceeded the maximum allowed time.

Delete a spaceDELETE/v1/objects/{sub_key}/spaces/{space_id}{?auth}

Deletes the specified space.

Example URI

DELETE https://ps.pndsn.com/v1/objects/demo/spaces/space-1
Path Parameters
sub_key

string (required) Example: mySubKey
The subscriber key.

space_id

string (required) Example: main
The space identifier.

Query Parameters
auth

string (optional) 
Authorization key with permissions to perform the request.
If Access Manager is enabled, a valid authorization token or signature is required.
See Access Manager documentation for details on how to obtain an authorization token.

Response  200

Successfully deleted the space.

Headers
Content-Type: application/json
Body
{
    "status": "0",
    "data": {}
}
Response  403

The client isn’t authorized to perform this operation. Either the authorization key you provided doesn’t have the required permissions for this operation, or the signature is invalid.

Response  412

Conditional operation cannot be performed because the target object has changed since the last retrieval.

Response  429

Request rate limit exceeded.

Response  500

An internal server error ocurred.

Response  503

Request processing exceeded the maximum allowed time.


Membership

Manage memberships, by space and by user

Get a user's list of space membershipsGET/v1/objects/{sub_key}/users/{user_id}/spaces{?include,limit,start,end,count,auth}

Returns the specified user's space memberships, optionally including the custom data objects for: the user's perspective on their membership set ("custom"), the user's perspective on the space ("space"), and the space's custom data ("space.custom").

Example URI

GET https://ps.pndsn.com/v1/objects/demo/users/user-1/spaces?include=custom?limit=10&count=true
Path Parameters
sub_key

string (required) Example: mySubKey
The subscriber key.

user_id

string (required) Example: charlie
The user identifier.

Query Parameters
include

array[string] (optional) Available values: custom, space, space.custom
List of additional/complex properties to include in response. Omit this query parameter if you don't want to retrieve additional properties.

limit

integer (optional) Default value: 100
Number of objects to return in response. Default is 100, which is also the maximum value.

start

string (optional)
Previously-returned cursor bookmark for fetching the next page.

end

string (optional)
Previously-returned cursor bookmark for fetching the previous page. Ignored if you also supply the start parameter.

count

boolean (optional) Example: true
Request totalCount to be included in paginated response. By default, totalCount is omitted.

auth

string (optional) 
Authorization key with permissions to perform the request.
If Access Manager is enabled, either a valid authorization token or a signature are required.
See Access Manager documentation for details on how to obtain an authorization token.

Response  200

Successfully returned the user's membership list.

Headers
Content-Type: application/json
Body
{
    "status": 200,
    "data": [
        {
            "id": "my-channel",
            "custom": {
                "starred": false
            },
            "space": {
                "id": "my-channel",
                "name": "My space",
                "description": "A space that is mine",
                "created": "2019-02-20T23:11:20.893755",
                "updated": "2019-02-20T23:11:20.893755",
                "eTag": "RTc1NUQwNUItREMyNy00Q0YxLUJCNDItMEZDMTZDMzVCN0VGCg=="
            },
            "created": "2019-02-20T23:11:20.893755",
            "updated": "2019-02-20T23:11:20.893755",
            "eTag": "RUNDMDUwNjktNUYwRC00RTI0LUI1M0QtNUUzNkE2NkU0MEVFCg=="
        },
        {
            "id": "main",
            "custom": {
                "starred": true
            },
            "space": {
                "id": "main",
                "name": "Main space",
                "description": "The main space",
                "custom": {
                    "public": true,
                    "motd": "Always check your spelling!"
                },
                "created": "2019-02-20T23:11:20.893755",
                "updated": "2019-02-20T23:11:20.893755",
                "eTag": "RTc1NUQwNUItREMyNy00Q0YxLUJCNDItMEZDMTZDMzVCN0VGCg=="
            },
            "created": "2019-02-20T23:11:20.893755",
            "updated": "2019-02-20T23:11:20.893755",
            "eTag": "RUNDMDUwNjktNUYwRC00RTI0LUI1M0QtNUUzNkE2NkU0MEVFCg=="
        }
    ],
    "totalCount": 7,
    "next": "RDIwQUIwM0MtNUM2Ni00ODQ5LUFGRjMtNDk1MzNDQzE3MUVCCg==",
    "prev": "MzY5RjkzQUQtNTM0NS00QjM0LUI0M0MtNjNBQUFGODQ5MTk2Cg=="
}
Response  304

Requested resource has not been modified since last retrieval.

Response  403

The client isn’t authorized to perform this operation. Either the authorization key you provided doesn’t have the required permissions for this operation, or the signature is invalid.

Response  404

The requested object was not found.

Response  429

Request rate limit exceeded.

Response  500

An internal server error ocurred.

Response  503

Request processing exceeded the maximum allowed time.

Update a user's space membershipsPATCH/v1/objects/{sub_key}/users/{user_id}/spaces{?include,limit,start,end,count,auth}

Updates the specified user's space memberships. Use the add, update, and remove properties in the request body to perform those operations on one or more memberships.

Example URI

PATCH https://ps.pndsn.com/v1/objects/demo/users/user-1/spaces?include=custom?limit=10&count=true

Returns the user's space memberships, optionally including:

  • the user's custom data object
  • the custom data objects for the user's membership in each space
  • each space's custom data object
Path Parameters
sub_key

string (required) Example: mySubKey
The subscriber key.

user_id

string (required) Example: charlie
The user identifier.

Query Parameters
include

array[string] (optional) Available values: custom, space, space.custom
List of additional/complex properties to include in response. Omit this query parameter if you don't want to retrieve additional properties.

limit

integer (optional) Default value: 100
Number of objects to return in response. Default is 100, which is also the maximum value.

start

string (optional)
Previously-returned cursor bookmark for fetching the next page.

end

string (optional)
Previously-returned cursor bookmark for fetching the previous page. Ignored if you also supply the start parameter.

count

boolean (optional) Example: true
Request totalCount to be included in paginated response. By default, totalCount is omitted.

auth

string (optional) 
Authorization key with permissions to perform the request.
If Access Manager is enabled, either a valid authorization token or a signature are required.
See Access Manager documentation for details on how to obtain an authorization token.

Request  required

JSON object with changes to the user's space memberships.

Headers
Content-Type: application/json
Body
{
    "add": [
        {
            "id": "my-channel"
        }
    ],
    "update": [
        {
            "id": "main",
            "custom": {
                "starred": true
            }
        }
    ],
    "remove": [
        {
            "id": "space-0"
        }
    ]
}
Response  200

Successfully updated the user's space memberships.

Headers
Content-Type: application/json
Body
{
    "status": 200,
    "data": [
        {
            "id": "my-channel",
            "custom": {
                "starred": false
            },
            "space": {
                "id": "my-channel",
                "name": "My space",
                "description": "A space that is mine",
                "created": "2019-02-20T23:11:20.893755",
                "updated": "2019-02-20T23:11:20.893755",
                "eTag": "RTc1NUQwNUItREMyNy00Q0YxLUJCNDItMEZDMTZDMzVCN0VGCg=="
            },
            "created": "2019-02-20T23:11:20.893755",
            "updated": "2019-02-20T23:11:20.893755",
            "eTag": "RUNDMDUwNjktNUYwRC00RTI0LUI1M0QtNUUzNkE2NkU0MEVFCg=="
        },
        {
            "id": "main",
            "custom": {
                "starred": true
        },
        "space": {
            "id": "main",
            "name": "Main space",
            "description": "The main space",
            "custom": {
                "public": true,
                "motd": "Always check your spelling!"
            },
            "created": "2019-02-20T23:11:20.893755",
            "updated": "2019-02-20T23:11:20.893755",
            "eTag": "RTc1NUQwNUItREMyNy00Q0YxLUJCNDItMEZDMTZDMzVCN0VGCg=="
        },
        "created": "2019-02-20T23:11:20.893755",
        "updated": "2019-02-20T23:11:20.893755",
        "eTag": "RUNDMDUwNjktNUYwRC00RTI0LUI1M0QtNUUzNkE2NkU0MEVFCg=="
        }
    ],
    "totalCount": 7,
    "next": "RDIwQUIwM0MtNUM2Ni00ODQ5LUFGRjMtNDk1MzNDQzE3MUVCCg==",
    "prev": "MzY5RjkzQUQtNTM0NS00QjM0LUI0M0MtNjNBQUFGODQ5MTk2Cg=="
}
Response  400

The request body contains invalid data.

Response  403

The client isn’t authorized to perform this operation. Either the authorization key you provided doesn’t have the required permissions for this operation, or the signature is invalid.

Response  404

The requested object was not found.

Response  415

The format of the request body you supplied isn't supported. The request body must be in JSON format.

Response  429

Request rate limit exceeded.

Response  500

An internal server error ocurred.

Response  503

Request processing exceeded the maximum allowed time.

Get the list of members in a spaceGET/v1/objects/{sub_key}/spaces/{space_id}/users{?include,limit,start,end,count,auth}

Returns the users in a space, optionally including:

Example URI

GET https://ps.pndsn.com/v1/objects/demo/spaces/space-1/users?include=custom?limit=10&count=true
  • each user's custom data object
  • the custom data objects for each user's membership in the space
  • the space's custom data object
Path Parameters
sub_key

string (required) Example: mySubKey
The subscriber key.

space_id

string (required) Example: main
The space identifier.

Query Parameters
include

array[string] (optional) Available values: custom, user, user.custom
List of additional/complex properties to include in response. Omit this query parameter if you don't want to retrieve additional properties.

limit

integer (optional) Default value: 100
Number of objects to return in response. Default is 100, which is also the maximum value.

start

string (optional)
Previously-returned cursor bookmark for fetching the next page.

end

string (optional)
Previously-returned cursor bookmark for fetching the previous page. Ignored if you also supply the start parameter.

count

boolean (optional) Example: true
Request totalCount to be included in paginated response. By default, totalCount is omitted.

auth

string (optional) 
Authorization key with permissions to perform the request.
If Access Manager is enabled, either a valid authorization token or a signature are required.
See Access Manager documentation for details on how to obtain an authorization token.

Response  200

Successfully returned the space's user list.

Headers
Content-Type: application/json
Body
{
    "status": 200,
    "data": [
        {
            "id": "user-1",
            "custom": {
                "role": "admin"
            },
            "user": {
                "id": "user-1",
                "name": "John Doe",
                "externalId": null,
                "profileUrl": null,
                "email": "jack@twitter.com",
                "custom": null,
                "created": "2019-02-20T23:11:20.893755",
                "updated": "2019-02-20T23:11:20.893755",
                "eTag": "MDcyQ0REOTUtNEVBOC00QkY2LTgwOUUtNDkwQzI4MjgzMTcwCg=="
            },
            "created": "2019-02-20T23:11:20.893755",
            "updated": "2019-02-20T23:11:20.893755",
            "eTag": "QkRENDA5MjItMUZCNC00REI5LUE4QTktRjJGNUMxNTc2MzE3Cg=="
        },
        {
            "id": "user-2",
            "custom": {
                "role": "moderator"
            },
            "user": {
                "id": "user-2",
                "name": "Bob Cat",
                "externalId": null,
                "profileUrl": null,
                "email": "bobc@example.com",
                "custom": {
                    "phone": "999-999-9999"
                },
                "created": "2019-02-19T13:10:20.893755",
                "updated": "2019-02-21T03:29:00.173452",
                "eTag": "QkRENDA5MjItMUZCNC00REI5LUE4QTktRjJGNUMxNTc2MzE3Cg=="
            },
            "created": "2019-02-20T23:11:20.893755",
            "updated": "2019-02-20T23:11:20.893755",
            "eTag": "QkRENDA5MjItMUZCNC00REI5LUE4QTktRjJGNUMxNTc2MzE3Cg=="
        }
    ],
    "totalCount": 37,
    "next": "RDIwQUIwM0MtNUM2Ni00ODQ5LUFGRjMtNDk1MzNDQzE3MUVCCg==",
    "prev": "MzY5RjkzQUQtNTM0NS00QjM0LUI0M0MtNjNBQUFGODQ5MTk2Cg=="
}
Response  304

Requested resource has not been modified since last retrieval.

Response  403

The client isn’t authorized to perform this operation. Either the authorization key you provided doesn’t have the required permissions for this operation, or the signature is invalid.

Response  404

The requested object was not found.

Response  429

Request rate limit exceeded.

Response  500

An internal server error ocurred.

Response  503

Request processing exceeded the maximum allowed time.

Update the members in a spacePATCH/v1/objects/{sub_key}/spaces/{space_id}/users{?include,limit,start,end,count,auth}

Updates the specified space's user list. Use the add, update, and remove properties in the request body to perform those operations on one or more memberships.

Example URI

PATCH https://ps.pndsn.com/v1/objects/demo/spaces/space-1/users?include=custom?limit=10&count=true

Returns the space's user memberships, optionally including:

  • the space's custom data object
  • the custom data objects for each user's membership in the space
  • each user's custom data object
Path Parameters
sub_key

string (required) Example: mySubKey
The subscriber key.

space_id

string (required) Example: main
The space identifier.

Query Parameters
include

array[string] (optional) Available values: custom, user, user.custom
List of additional/complex properties to include in response. Omit this query parameter if you don't want to retrieve additional properties.

limit

integer (optional) Default value: 100
Number of objects to return in response. Default is 100, which is also the maximum value.

start

string (optional)
Previously-returned cursor bookmark for fetching the next page.

end

string (optional)
Previously-returned cursor bookmark for fetching the previous page. Ignored if you also supply the start parameter.

count

boolean (optional) Example: true
Request totalCount to be included in paginated response. By default, totalCount is omitted.

auth

string (optional) 
Authorization key with permissions to perform the request.
If Access Manager is enabled, either a valid authorization token or a signature are required.
See Access Manager documentation for details on how to obtain an authorization token.

Request  required

JSON object with changes to the space's user list.

Headers
Content-Type: application/json
Body
{
    "add": [
        {
          "id": "user-1"
        }
    ],
    "update": [
        {
            "id": "user-2",
            "custom": {
                "role": "moderator"
            }
        }
    ],
    "remove": [
        {
            "id": "user-0"
        }
    ]
}
Response  200

Successfully updated the space's membership list.

Headers
Content-Type: application/json
Body
{
    "status": 200,
    "data": [
        {
            "id": "user-1",
            "custom": {
                "role": "admin"
            },
            "user": {
                "id": "user-1",
                "name": "John Doe",
                "externalId": null,
                "profileUrl": null,
                "email": "jack@twitter.com",
                "custom": null,
                "created": "2019-02-20T23:11:20.893755",
                "updated": "2019-02-20T23:11:20.893755",
                "eTag": "MDcyQ0REOTUtNEVBOC00QkY2LTgwOUUtNDkwQzI4MjgzMTcwCg=="
            },
            "created": "2019-02-20T23:11:20.893755",
            "updated": "2019-02-20T23:11:20.893755",
            "eTag": "QkRENDA5MjItMUZCNC00REI5LUE4QTktRjJGNUMxNTc2MzE3Cg=="
        },
        {
            "id": "user-2",
            "custom": {
                "role": "moderator"
            },
            "user": {
                "id": "user-2",
                "name": "Bob Cat",
                "externalId": null,
                "profileUrl": null,
                "email": "bobc@example.com",
                "custom": {
                    "phone": "999-999-9999"
                },
                "created": "2019-02-19T13:10:20.893755",
                "updated": "2019-02-21T03:29:00.173452",
                "eTag": "QkRENDA5MjItMUZCNC00REI5LUE4QTktRjJGNUMxNTc2MzE3Cg=="
            },
            "created": "2019-02-20T23:11:20.893755",
            "updated": "2019-02-20T23:11:20.893755",
            "eTag": "QkRENDA5MjItMUZCNC00REI5LUE4QTktRjJGNUMxNTc2MzE3Cg=="
        }
    ],
    "totalCount": 37,
    "next": "RDIwQUIwM0MtNUM2Ni00ODQ5LUFGRjMtNDk1MzNDQzE3MUVCCg==",
    "prev": "MzY5RjkzQUQtNTM0NS00QjM0LUI0M0MtNjNBQUFGODQ5MTk2Cg=="
}
Response  400

The request body contains invalid data.

Response  403

The client isn’t authorized to perform this operation. Either the authorization key you provided doesn’t have the required permissions for this operation, or the signature is invalid.

Response  404

The requested object was not found.

Response  415

The format of the request body you supplied isn't supported. The request body must be in JSON format.

Response  429

Request rate limit exceeded.

Response  500

An internal server error ocurred.

Response  503

Request processing exceeded the maximum allowed time.

Error responses

  • Response 304

    Requested resource has not been modified since last retrieval.

  • Response 400

    The request body contains invalid data.

    Headers
    Content-Type: application/json
    Body
    {
        "status": "400",
        "error": {
            "message": "Request payload contained invalid input.",
            "source": "objects",
            "details": [
                {
                    "message": "User email must be a valid email address.",
                    "location": "user.email",
                    "locationType": "body"
                }
            ]
        }
    }
  • Response 403

    The client isn’t authorized to perform this operation. Either the authorization key you provided doesn’t have the required permissions for this operation, or the signature is invalid.

    Headers
    Content-Type: application/json
    Body
    {
        "status": 403,
        "error": {
            "message": "Supplied authorization key does not have the permissions required to perform this operation.",
            "source": "objects"
        }
    }
  • Response 404

    The requested object was not found.

    Headers
    Content-Type: application/json
    Body
    {
        "status": 404,
        "error": {
            "message": "Requested object was not found.",
            "source": "objects"
        }
    }
  • Response 409

    An object with the given identifier already exists.

    Headers
    Content-Type: application/json
    Body
    {
        "status": 409,
        "error": {
            "message": "Object with the requested identifier already exists.",
            "source": "objects"
        }
    }
  • Response 412

    Conditional operation cannot be performed because the target object has changed since the last retrieval.

    Headers
    Content-Type: application/json
    Body
    {
        "status": 412,
        "error": {
            "message": "Object already changed by another request since last retrieval.",
            "source": "objects"
        }
    }
  • Response 415

    The format of the request body you supplied isn't supported. The request body must be in JSON format.

    Headers
    Content-Type: application/json
    Body
    {
        "status": 415,
        "error": {
            "message": "Request payload must be in JSON format.",
            "source": "objects"
        }
    }
  • Response 429

    Request rate limit exceeded.

    Headers
    Content-Type: application/json
    Body
    {
        "status": 429,
        "error": {
            "message": "You have exceeded the maximum number of requests per second allowed for your subscriber key.",
            "source": "objects"
        }
    }
  • Response 500

    An internal server error occurred.

    Headers
    Content-Type: application/json
    Body
    {
        "status": 500,
        "error": {
            "message": "An unexpected error ocurred while processing the request.",
            "source": "objects"
        }
    }
  • Response 503

    Request processing exceeded the maximum allowed time.

    Headers
    Content-Type: application/json
    Body
    {
        "status": 503,
        "error": {
            "message": "The server took longer to respond than the maximum allowed processing time.",
            "source": "objects"
        }
    }

Miscellaneous

Time

Get current PubNub Time in the form of a Timetoken.

About Timetokens

The timetoken represents a 17-digit precision unix time (UTC). To convert PubNub's timetoken to Unix timestamp (seconds), divide the timetoken number by 10,000,000 (10^7).

To convert back and forth between current time, A Ruby example follows as:

> now = Time.now
 => 2012-11-02 14:27:11 -0700

> timetoken = now.to_f * 10000000
 => 13518916319742640

> Time.at(timetoken / 10000000)
 => 2012-11-02 14:27:11 -0700

Fetch TimeGET/time/{callback}{?uuid}

Example URI

GET https://ps.pndsn.com/time/0?uuid=db9c5e39-7c95-40f5-8d71-125765b6f561
URI Parameters
HideShow
callback
string (required) Example: 0

pass function name to wrap in JSONP or 0 to disable JSONP

uuid
string (required) Example: db9c5e39-7c95-40f5-8d71-125765b6f561

A unique alphanumeric ID for identifying the client to the PubNub Presence System, as well as for PubNub Analytics.

Request  fetch time without JSONP
HideShow
Headers
Location: /time/0
Response  200
HideShow
Headers
Content-Type: application/json
Body
[
  14374273908474348
]
Request  fetch time with JSONP
HideShow
Headers
Location: /time/moose
Response  200
HideShow
Headers
Content-Type: text/javascript
Body
moose([14374273908474349])