Push Messages API API Reference

The Push Messages API provides an HTTP interface for pushing messages from a Thing Provider cloud to the Geeny platform. See the Geeny Alliance Onboarding Guide for more information.

The Push Messages API includes a debug mode for testing data transmission to the Geeny platform. To use debug mode, append /debug to the URL in your API call. You can view these test messagees on a Virtual Device dynamically created on the Developers Dashboard by the debug endpoint. Only the Thing Type owner can see these messages. See step 5 of the Thing Providers onboarding guide for more information.

API Endpoint
http://developers.geeny.io/data
Request Content-Types: application/json
Response Content-Types: application/json
Version: 1.0.0

Debug mode

Onboard external device on the Geeny platform (DEBUG)

POST /devices/{thing-type-id}/debug

Register a new device on the Geeny Platform in debug mode. You must use this endpoint if the external device can only receive commands (i.e., only sub resources). Devices will be created dynamically based on the provided device_id. In debug mode, all devices will be created under the Geeny developer account that owns the Thing Type.

user_id - Ignored in debug mode.
device_id - Unique external device identifier.
device_sn - (Optional) External device serial number.
device_name - Name of the external device.

Properties of the device to be onboarded.

authorization

Bearer (you can find this on the Developers Dashboard)

type
string
in
header
thing-type-id

ID of the Thing Type that corresponds with the device to be onboarded.

type
string (uuid)
in
path
Request Example
{
  "user_id": "<user identifier>",
  "device_id": "<device identifier>",
  "device_sn": "<device serial number>",
  "device_name": "<device name>"
}

Device successfully created.

400 Bad Request

Bad request.

401 Unauthorized

Unauthorized.

500 Internal Server Error

Internal server error.

Response Example (200 OK)
{
  "status": "string"
}
Response Example (400 Bad Request)
{
  "error": "string"
}
Response Example (401 Unauthorized)
{
  "error": "string"
}
Response Example (500 Internal Server Error)
{
  "error": "string"
}

Push messages to the Geeny platform (DEBUG)

POST /push/{thing-type-id}/debug

Push data to the Geeny platform. A Virtual Device will be created dynamically based on the provided device_id. In debug mode, all devices will be created under the Geeny developer account that owns the Thing Type.

id - Unique message identifier (UUID).
user_id - Ignored in debug mode.
device_id - Unique external device identifier.
uri - Thing Type pub resource uri.
payload - Base64-encoded data payload.
device_sn - (Optional) External device serial number.
device_name - Name of the external device.

An array of messages to be pushed to the Geeny platform. See endpoint description for information about the schema.

PushMessagesBody
authorization

Bearer (you can find this on the Developers Dashboard)

type
string
in
header
thing-type-id

ID of the Thing Type that corresponds with the messages being pushed.

type
string (uuid)
in
path
Request Example
[
  {
    "id": "<generated message uuid>",
    "user_id": "<user identifier>",
    "device_id": "<device identifier>",
    "uri": "<pub thing-type resource>",
    "payload": "<base64 encoded message payload>",
    "device_sn": "<device serial number>",
    "device_name": "<device name>"
  }
]

Messages successfully pushed to the Geeny platform.

202 Accepted

Messages accepted.

400 Bad Request

Bad request.

401 Unauthorized

Unauthorized.

500 Internal Server Error

Internal server error.

Response Example (200 OK)
{
  "status": "success"
}
Response Example (202 Accepted)
{
  "status": "success"
}
Response Example (400 Bad Request)
{
  "error": "string"
}
Response Example (401 Unauthorized)
{
  "error": "string"
}
Response Example (500 Internal Server Error)
{
  "error": "string"
}

Production API

Onboard external device on the Geeny platform

POST /devices/{thing-type-id}

Register a new device on the Geeny Platform. You must use this endpoint if the external device can only receive commands (i.e., only sub resources). The user_id property must contain the ID of a user that completed the OAuth flow to get authorization from Geeny to send and receive data.

user_id - Unique external user identifier.
device_id - Unique external device identifier.
device_sn - (Optional) External device serial number.
device_name - Name of the external device.

Properties of the device to be onboarded.

authorization

Bearer (you can find this on the Developers Dashboard)

type
string
in
header
thing-type-id

ID of the Thing Type that corresponds with the device to be onboarded.

type
string (uuid)
in
path
Request Example
{
  "user_id": "<user identifier>",
  "device_id": "<device identifier>",
  "device_sn": "<device serial number>",
  "device_name": "<device name>"
}

Device successfully created.

400 Bad Request

Bad request.

401 Unauthorized

Unauthorized.

500 Internal Server Error

Internal server error.

Response Example (200 OK)
{
  "status": "string"
}
Response Example (400 Bad Request)
{
  "error": "string"
}
Response Example (401 Unauthorized)
{
  "error": "string"
}
Response Example (500 Internal Server Error)
{
  "error": "string"
}

Push messages to the Geeny platform

POST /push/{thing-type-id}

Push data to the Geeny Platform. Devices will be created dynamically based on the provided device_id. The user_id property must contain the ID of a user that completed the OAuth flow to get authorization from Geeny to send and receive data.

id - Unique message identifier (UUID).
user_id - Unique external user identifier.
device_id - Unique external device identifier.
uri - Thing Type pub resource uri.
payload - Base64-encoded data payload.
device_sn - (Optional) External device serial number.
device_name - Name of the external device.

An array of messages to be pushed to the Geeny platform. See endpoint description for information about the schema.

PushMessagesBody
authorization

Bearer (you can find this on the Developers Dashboard)

type
string
in
header
thing-type-id

ID of the Thing Type that corresponds with the messages being pushed.

type
string (uuid)
in
path
Request Example
[
  {
    "id": "<generated message uuid>",
    "user_id": "<user identifier>",
    "device_id": "<device identifier>",
    "uri": "<pub thing-type resource>",
    "payload": "<base64 encoded message payload>",
    "device_sn": "<device serial number>",
    "device_name": "<device name>"
  }
]
202 Accepted

Messages accepted.

400 Bad Request

Bad request.

401 Unauthorized

Unauthorized.

500 Internal Server Error

Internal server error.

Response Example (202 Accepted)
{
  "status": "success"
}
Response Example (400 Bad Request)
{
  "error": "string"
}
Response Example (401 Unauthorized)
{
  "error": "string"
}
Response Example (500 Internal Server Error)
{
  "error": "string"
}

Schema Definitions

OnboardDeviceBody: object

user_id: string

Unique external user identifier. Ignored in debug mode.

device_id: string

Unique external device identifier.

device_sn: string

(Optional) External device serial number.

device_name: string

Name of the external device.

Example
{
  "user_id": "<user identifier>",
  "device_id": "<device identifier>",
  "device_sn": "<device serial number>",
  "device_name": "<device name>"
}

PushMessagesBody: object

id: string (uuid)

Unique message identifier (UUID).

user_id: string

Unique external user identifier (i.e., the user identifier generated on your end). Ignored in debug mode.

device_id: string

Unique external device identifier.

uri: string

Thing Type pub resource uri.

payload: string

Base64-encoded data payload.

device_sn: string

(Optional) External device serial number.

device_name: string

Name of the external device.

Example
{
  "id": "<generated message uuid>",
  "user_id": "<user identifier>",
  "device_id": "<device identifier>",
  "uri": "<pub thing-type resource>",
  "payload": "<base64 encoded message payload>",
  "device_sn": "<device serial number>",
  "device_name": "<device name>"
}

DeviceCreatedResponse: object

status: string
Example
{
  "status": "string"
}

UnauthorizedResponse: object

error: string
Example
{
  "error": "string"
}

BadRequestResponse: object

error: string
Example
{
  "error": "string"
}

500Response: object

error: string
Example
{
  "error": "string"
}

MessageSuccessResponse: object

status: string success, partial-success
failed-messages: string[]
Example
{
  "status": "success"
}