Thing Manager API API Reference

The Thing Manager API is responsible for registering and modifying Things, Thing Types and Message Types. More information about these entities can be found in the platform overview.

NOTE: You must get an authorization token from the Connect API before you can use this endpoint. Click here for instructions.

API Endpoint
https://labs.geeny.io/things/api/v1
Schemes: https, http
Version: 1.0

Authentication

jwt

description

Geeny Connect Auth Token (Format: JWT [token])

in
header
name
Authorization

Message Types

Message Types

Create new Message Type

POST /messageTypes

Registers a new Message Type on the platform and returns a JSON object with a Message Type ID and the creation date.

NewMessageType

Message Type data

Request Content-Types: application/json
Request Example
{
  "name": "Instantaneous Humidity Value",
  "description": "Instantaneous Humidity Value",
  "media_type": "application/cbor",
  "tags": [
    "humidity",
    "sensor",
    "BRAND"
  ]
}
201 Created
MessageType

New Message Type successfully created.

400 Bad Request
ClientErrorResponse

Invalid request.

401 Unauthorized
UnauthorizedResponse

Unauthorized. Check your JWT with the Connect API.

500 Internal Server Error
ServerErrorResponse

Server error..

Response Content-Types: application/json
Response Example (201 Created) 
{
  "id": "75d93472-4b81-46f1-848c-bfa8bf6de881",
  "name": "Instantaneous Temperature Value",
  "media_type": "application/json",
  "description": "Instantaneous temperature value",
  "created": "2017-07-18T09:38:16.164Z",
  "tags": [
    "temperature",
    "sensor",
    "BRAND"
  ]
}
Response Example (400 Bad Request) 
{
  "error": "'id' must be a valid GUID"
}
Response Example (401 Unauthorized) 
{
  "error": "Unauthorized."
}
Response Example (500 Internal Server Error) 
{
  "error": "Something went wrong."
}
Message Types

Get all Message Types

GET /messageTypes

Returns an array of all the Message Types on the Geeny platform.

offset

Number by which to offset the list of Message Types.

type
number
in
query
limit

Number of Message Types to be returned.

type
number
in
query
200 OK
MessageTypesResponse

Success.

401 Unauthorized
UnauthorizedResponse

Unauthorized. Check your JWT with the Connect API.

500 Internal Server Error
ServerErrorResponse

Server error.

Response Content-Types: application/json
Response Example (200 OK) 
{
  "meta": {
    "limit": "integer",
    "offset": "integer"
  },
  "data": [
    {
      "id": "75d93472-4b81-46f1-848c-bfa8bf6de881",
      "name": "Instantaneous Temperature Value",
      "media_type": "application/json",
      "description": "Instantaneous temperature value",
      "created": "2017-07-18T09:38:16.164Z",
      "tags": [
        "temperature",
        "sensor",
        "BRAND"
      ]
    }
  ]
}
Response Example (401 Unauthorized) 
{
  "error": "Unauthorized."
}
Response Example (500 Internal Server Error) 
{
  "error": "Something went wrong."
}
Message Types

Get Message Type

GET /messageTypes/{messageTypeId}

Returns a single Message Type.

messageTypeId

ID of the Message Type to be returned.

type
string
in
path
200 OK
MessageType

Success.

400 Bad Request
ClientErrorResponse

Invalid parameters.

401 Unauthorized
UnauthorizedResponse

Unauthorized.

404 Not Found
NotFoundResponse

Message Type not found.

500 Internal Server Error
ServerErrorResponse

Server error.

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "75d93472-4b81-46f1-848c-bfa8bf6de881",
  "name": "Instantaneous Temperature Value",
  "media_type": "application/json",
  "description": "Instantaneous temperature value",
  "created": "2017-07-18T09:38:16.164Z",
  "tags": [
    "temperature",
    "sensor",
    "BRAND"
  ]
}
Response Example (400 Bad Request) 
{
  "error": "'id' must be a valid GUID"
}
Response Example (401 Unauthorized) 
{
  "error": "Unauthorized."
}
Response Example (404 Not Found) 
{
  "error": "Not found."
}
Response Example (500 Internal Server Error) 
{
  "error": "Something went wrong."
}
Message Types

Publish a Message Type

PATCH /messageTypes/{messageTypeId}

Publishes a single Message Type. This allows other Geeny developers to use this Message Type in their Thing Types.

authorization

Your user JWT.

type
string
in
header
messageTypeId

ID of the Message Type to be published.

type
string
in
path
200 OK
MessageType
Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "75d93472-4b81-46f1-848c-bfa8bf6de881",
  "name": "Instantaneous Temperature Value",
  "media_type": "application/json",
  "description": "Instantaneous temperature value",
  "created": "2017-07-18T09:38:16.164Z",
  "tags": [
    "temperature",
    "sensor",
    "BRAND"
  ]
}
Message Types

Delete Message Type

DELETE /messageTypes/{messageTypeId}

Deletes a single Message Type.

messageTypeId

ID of the Message Type to be deleted.

type
string
in
path
authorization

Your user JWT.

type
string
in
header
204 No Content

Message Type deleted.

Response Content-Types: application/json

Thing Types

Thing Types

Create new Thing Type

POST /thingTypes

Registers a new Thing Type on the platform. Returns a JSON object with a unique ID for the Thing Type.

NewThingType

Thing Type data. See the schema definition below for more information about the body contents.

Request Content-Types: application/json
Request Example
{
  "name": "BRAND Humidity Sensor",
  "resources": [
    {
      "uri": "humidity/now",
      "method": "pub",
      "message_type": "e27141fa-5805-41df-94f9-4aec44150b44"
    }
  ]
}
201 Created
ThingType

New Thing Type created.

400 Bad Request
ClientErrorResponse

Invalid request.

401 Unauthorized
UnauthorizedResponse

Unauthorized.

500 Internal Server Error
ServerErrorResponse

Server error.

Response Content-Types: application/json
Response Example (201 Created) 
{
  "id": "024d804b-1267-4483-aab8-f25f22441062",
  "name": "BRAND Temperature Sensor",
  "created": "2017-07-18T09:38:16.164Z",
  "public": true
}
Response Example (400 Bad Request) 
{
  "error": "'id' must be a valid GUID"
}
Response Example (401 Unauthorized) 
{
  "error": "Unauthorized."
}
Response Example (500 Internal Server Error) 
{
  "error": "Something went wrong."
}
Thing Types

Get all Thing Types

GET /thingTypes

Returns an array of all the Thing Types on the Geeny platform.

offset

Number by which to offset the list of Thing Types.

type
number
in
query
limit

Number of Thing Types to be returned.

type
number
in
query
200 OK
ThingTypesResponse

Success.

401 Unauthorized
UnauthorizedResponse

Unauthorized

500 Internal Server Error
ServerErrorResponse

Server error.

Response Content-Types: application/json
Response Example (200 OK) 
{
  "meta": {
    "limit": "integer",
    "offset": "integer"
  },
  "data": [
    {
      "id": "024d804b-1267-4483-aab8-f25f22441062",
      "name": "BRAND Temperature Sensor",
      "created": "2017-07-18T09:38:16.164Z",
      "public": true
    }
  ]
}
Response Example (401 Unauthorized) 
{
  "error": "Unauthorized."
}
Response Example (500 Internal Server Error) 
{
  "error": "Something went wrong."
}
Thing Types

Get Thing Type

GET /thingTypes/{thingTypeId}

Returns a specific Thing Type.

thingTypeId

ID of the Thing Type to be returned.

type
string
in
path
200 OK
ThingType

Success.

400 Bad Request
ClientErrorResponse

Invalid parameters.

401 Unauthorized
UnauthorizedResponse

Unauthorized.

404 Not Found
NotFoundResponse

Thing Type not found.

500 Internal Server Error
ServerErrorResponse

Server error.

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "024d804b-1267-4483-aab8-f25f22441062",
  "name": "BRAND Temperature Sensor",
  "created": "2017-07-18T09:38:16.164Z",
  "public": true
}
Response Example (400 Bad Request) 
{
  "error": "'id' must be a valid GUID"
}
Response Example (401 Unauthorized) 
{
  "error": "Unauthorized."
}
Response Example (404 Not Found) 
{
  "error": "Not found."
}
Response Example (500 Internal Server Error) 
{
  "error": "Something went wrong."
}
Thing Types

Publish a Thing Type

PATCH /thingTypes/{thingTypeId}

Publishes a single Thing Type. This enables other Geeny developers to register Things with this Thing Type.

authorization

Your user JWT.

type
string
in
header
thingTypeId

ID of the Thing Type to be published.

type
string
in
path
200 OK
ThingType
Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "024d804b-1267-4483-aab8-f25f22441062",
  "name": "BRAND Temperature Sensor",
  "created": "2017-07-18T09:38:16.164Z",
  "public": true
}
Thing Types

Delete a Thing Type

DELETE /thingTypes/{thingTypeId}

Deletes a specific Thing Type.

thingTypeId

ID of the Thing Type to be deleted.

type
string (uuid)
in
path
authorization

Your user JWT.

type
string
in
header
200 OK

Thing Type deleted.

Response Content-Types: application/json
Thing Types

Get Resources

GET /thingTypes/{thingTypeId}/resources

Returns all of the resources (i.e., Message Types and routing information) of a given Thing Type.

thingTypeId

ID of the Thing Type to be queried.

type
string
in
path
200 OK
ResourcesResponse

Success.

400 Bad Request
ClientErrorResponse

Invalid parameters.

401 Unauthorized
UnauthorizedResponse

Unauthorized

404 Not Found
ResourcesNotFoundResponse

Invalid parameters.

500 Internal Server Error
ServerErrorResponse

Server error.

Response Content-Types: application/json
Response Example (200 OK) 
{
  "meta": {
    "limit": "50",
    "offset": "0"
  },
  "data": [
    {
      "uri": "temperature/now",
      "method": "pub",
      "message_type": "75d93472-4b81-46f1-848c-bfa8bf6de881"
    }
  ]
}
Response Example (400 Bad Request) 
{
  "error": "'id' must be a valid GUID"
}
Response Example (401 Unauthorized) 
{
  "error": "Unauthorized."
}
Response Example (404 Not Found) 
{
  "error": "Resources not found for Thing Type 024d804b-1267-4483-aab8-f25f22441061"
}
Response Example (500 Internal Server Error) 
{
  "error": "Something went wrong."
}

Things

Things

Create new Thing

POST /things

Registers a Thing and generates new certificates for it.

NewThing

The data of the new Thing. See the model definition below for more information about Thing data properties.

Request Content-Types: application/json
Request Example
{
  "name": "Humidity Sensor #1",
  "serial_number": "1L080B50260",
  "thing_type": "4f2c563b-364c-485b-b2b8-3b25d9b9a5ce"
}
201 Created
NewThingResponse

New Thing created.

400 Bad Request
ClientErrorResponse

Invalid request.

401 Unauthorized
UnauthorizedResponse

Unauthorized.

500 Internal Server Error
ServerErrorResponse

Server error.

Response Content-Types: application/json
Response Example (201 Created) 
{
  "id": "ede148c5-4eff-4f30-bb54-d41048ee5caa",
  "name": "Humidity Sensor #1",
  "serial_number": "1L080B50260",
  "certs": {
    "ca": "-----BEGIN CERTIFICATE-----...",
    "cert": "-----BEGIN CERTIFICATE-----...",
    "key": "-----BEGIN RSA PRIVATE KEY-----..."
  },
  "thing_type": "4f2c563b-364c-485b-b2b8-3b25d9b9a5ce",
  "created": "2017-07-18T11:54:34.611Z"
}
Response Example (400 Bad Request) 
{
  "error": "'id' must be a valid GUID"
}
Response Example (401 Unauthorized) 
{
  "error": "Unauthorized."
}
Response Example (500 Internal Server Error) 
{
  "error": "Something went wrong."
}
Things

Get all Things

GET /things

Returns an array of all the Things on the platform. You can supply one or more Thing Type IDs to limit the types of Things to be returned.

offset

Number by which to offset the list of Things.

type
number
in
query
limit

Number of Things to be returned.

type
number
in
query
thingType

Restrict the response to one or more Thing Types by supplying their Thing Type IDs (comma separated).

type
string
in
query
200 OK
ThingsResponse

Success.

401 Unauthorized
UnauthorizedResponse

Unauthorized.

500 Internal Server Error
ServerErrorResponse

Server error.

Response Content-Types: application/json
Response Example (200 OK) 
{
  "meta": {
    "limit": "50",
    "offset": "0"
  },
  "data": [
    {
      "id": "ab541d15-e785-4f63-9073-90b40432e72c",
      "name": "Temperature Sensor #1",
      "serial_number": "1L080B50230",
      "thing_type": "024d804b-1267-4483-aab8-f25f22441062",
      "created": "2017-07-18T09:38:16.164Z"
    }
  ]
}
Response Example (401 Unauthorized) 
{
  "error": "Unauthorized."
}
Response Example (500 Internal Server Error) 
{
  "error": "Something went wrong."
}
Things

Get Thing

GET /things/{thingId}

Returns a specific Thing.

thingId

ID of the Thing to be returned.

type
string
in
path
200 OK
Thing

Success.

400 Bad Request
ClientErrorResponse

Invalid parameters.

401 Unauthorized
UnauthorizedResponse

Unauthorized.

404 Not Found
NotFoundResponse

Not found.

500 Internal Server Error
ServerErrorResponse

Server error.

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "ab541d15-e785-4f63-9073-90b40432e72c",
  "name": "Temperature Sensor #1",
  "serial_number": "1L080B50230",
  "thing_type": "024d804b-1267-4483-aab8-f25f22441062",
  "created": "2017-07-18T09:38:16.164Z"
}
Response Example (400 Bad Request) 
{
  "error": "'id' must be a valid GUID"
}
Response Example (401 Unauthorized) 
{
  "error": "Unauthorized."
}
Response Example (404 Not Found) 
{
  "error": "Not found."
}
Response Example (500 Internal Server Error) 
{
  "error": "Something went wrong."
}
Things

Delete Thing

DELETE /things/{thingId}

Un-registers a Thing from the platform. Does not delete historical records of data sent by the Thing.

thingId

ID of the Thing to be deleted.

type
string
in
path
204 No Content

Thing deleted.

400 Bad Request
ClientErrorResponse

Invalid parameters.

401 Unauthorized
UnauthorizedResponse

Unauthorized.

404 Not Found
NotFoundResponse

Not found.

500 Internal Server Error
ServerErrorResponse

Server error.

Response Content-Types: application/json
Response Example (400 Bad Request) 
{
  "error": "'id' must be a valid GUID"
}
Response Example (401 Unauthorized) 
{
  "error": "Unauthorized."
}
Response Example (404 Not Found) 
{
  "error": "Not found."
}
Response Example (500 Internal Server Error) 
{
  "error": "Something went wrong."
}
Things

Update Thing

PATCH /things/{thingId}

Modifies one or more properties on a Thing.

ThingUpdate

New data for the Thing. Only the properties to be updated must be supplied. See the model definition below for more information.

thingId

ID of the Thing to be updated.

type
string
in
path
Request Example
{
  "name": "Updated Humidity Sensor #1"
}
200 OK
Thing

Success.

400 Bad Request
ClientErrorResponse

Invalid parameters.

401 Unauthorized
UnauthorizedResponse

Unauthorized.

404 Not Found
NotFoundResponse

Not found.

500 Internal Server Error
ServerErrorResponse

Server error.

Response Content-Types: application/json
Response Example (200 OK) 
{
  "id": "ab541d15-e785-4f63-9073-90b40432e72c",
  "name": "Temperature Sensor #1",
  "serial_number": "1L080B50230",
  "thing_type": "024d804b-1267-4483-aab8-f25f22441062",
  "created": "2017-07-18T09:38:16.164Z"
}
Response Example (400 Bad Request) 
{
  "error": "'id' must be a valid GUID"
}
Response Example (401 Unauthorized) 
{
  "error": "Unauthorized."
}
Response Example (404 Not Found) 
{
  "error": "Not found."
}
Response Example (500 Internal Server Error) 
{
  "error": "Something went wrong."
}

Schema Definitions

Thing: object

id: string (uuid)

The Thing's unique ID.

name: string

The name of the Thing.

serial_number: string

Serial number of the Thing.

thing_type: string (uuid)

ID of the Thing Type used to define the Thing.

created: string (date-time)

Date and time when the Thing was registered on Geeny.

Example
{
  "id": "ab541d15-e785-4f63-9073-90b40432e72c",
  "name": "Temperature Sensor #1",
  "serial_number": "1L080B50230",
  "thing_type": "024d804b-1267-4483-aab8-f25f22441062",
  "created": "2017-07-18T09:38:16.164Z"
}

ThingType: object

id: string (uuid)

Unique ID of the Thing Type.

name: string

Name of the Thing Type.

public: string (boolean)

Specifies whether or not other users can create Things of this Thing Type.

created: string (date-time)

Date and time when the Thing Type was created.

Example
{
  "id": "024d804b-1267-4483-aab8-f25f22441062",
  "name": "BRAND Temperature Sensor",
  "created": "2017-07-18T09:38:16.164Z",
  "public": true
}

MessageType: object

id: string (uuid)

Unique ID of the Message Type.

name: string

Name of the Message Type.

description: string

Description of the Message Type.

media_type: string (uuid)

Encoding format of the data contained in messages of this type.

tags: string[]

Optional categorization tags for the Message Type.

created: string (date-time)

Date and time when the Message Type was created.

Example
{
  "id": "75d93472-4b81-46f1-848c-bfa8bf6de881",
  "name": "Instantaneous Temperature Value",
  "media_type": "application/json",
  "description": "Instantaneous temperature value",
  "created": "2017-07-18T09:38:16.164Z",
  "tags": [
    "temperature",
    "sensor",
    "BRAND"
  ]
}

Resource: object

A schema containing a Message Type and information on how and where it will be published or received via subscription.

uri: string

URI where the Message Type is to be published or consumed via subscription.

method: string

Specifies whether this resource will be published by a Thing (pub) or whether a Thing will subscribe to receiving the message at the given URI (sub).

message_type: string (uuid)

ID of the Message Type that corresponds with the resource's payload.

Example
{
  "uri": "temperature/now",
  "method": "pub",
  "message_type": "75d93472-4b81-46f1-848c-bfa8bf6de881"
}

NewThing: object

name: string

Name of the Thing.

serial_number: string

Serial number of the Thing.

thing_type: string (uuid)

ID of the Thing Type which applies to the Thing.

Example
{
  "name": "Humidity Sensor #1",
  "serial_number": "1L080B50260",
  "thing_type": "4f2c563b-364c-485b-b2b8-3b25d9b9a5ce"
}

ThingUpdate: object

name: string
Example
{
  "name": "Updated Humidity Sensor #1"
}

NewThingType: object

name: string
resources: object[]

Array of schemas containing Message Types and information on how the Thing Type publishes or receives them via subscription.

Example
{
  "name": "BRAND Humidity Sensor",
  "resources": [
    {
      "uri": "humidity/now",
      "method": "pub",
      "message_type": "e27141fa-5805-41df-94f9-4aec44150b44"
    }
  ]
}

NewMessageType: object

name: string

Name of the Message Type.

description: string

A description of the Message Type.

media_type: string

Encoding format for the data in messages of this type.

tags: string[]

Optional tags for categorizing the Message Type.

Example
{
  "name": "Instantaneous Humidity Value",
  "description": "Instantaneous Humidity Value",
  "media_type": "application/cbor",
  "tags": [
    "humidity",
    "sensor",
    "BRAND"
  ]
}

NewThingResponse: object

id: string (uuid)
name: string
serial_number: string
certs: object
thing_type: string (uuid)
created: string (date-time)
Example
{
  "id": "ede148c5-4eff-4f30-bb54-d41048ee5caa",
  "name": "Humidity Sensor #1",
  "serial_number": "1L080B50260",
  "certs": {
    "ca": "-----BEGIN CERTIFICATE-----...",
    "cert": "-----BEGIN CERTIFICATE-----...",
    "key": "-----BEGIN RSA PRIVATE KEY-----..."
  },
  "thing_type": "4f2c563b-364c-485b-b2b8-3b25d9b9a5ce",
  "created": "2017-07-18T11:54:34.611Z"
}

ThingsResponse: object

meta: object
data: object[]
Example
{
  "meta": {
    "limit": "50",
    "offset": "0"
  },
  "data": [
    {
      "id": "ab541d15-e785-4f63-9073-90b40432e72c",
      "name": "Temperature Sensor #1",
      "serial_number": "1L080B50230",
      "thing_type": "024d804b-1267-4483-aab8-f25f22441062",
      "created": "2017-07-18T09:38:16.164Z"
    }
  ]
}

ResourcesResponse: object

meta: object
data: object[]
Example
{
  "meta": {
    "limit": "50",
    "offset": "0"
  },
  "data": [
    {
      "uri": "temperature/now",
      "method": "pub",
      "message_type": "75d93472-4b81-46f1-848c-bfa8bf6de881"
    }
  ]
}

MessageTypesResponse: object

meta: object
data: object[]
Example
{
  "meta": {
    "limit": "integer",
    "offset": "integer"
  },
  "data": [
    {
      "id": "75d93472-4b81-46f1-848c-bfa8bf6de881",
      "name": "Instantaneous Temperature Value",
      "media_type": "application/json",
      "description": "Instantaneous temperature value",
      "created": "2017-07-18T09:38:16.164Z",
      "tags": [
        "temperature",
        "sensor",
        "BRAND"
      ]
    }
  ]
}

ThingTypesResponse: object

meta: object
data: object[]
Example
{
  "meta": {
    "limit": "integer",
    "offset": "integer"
  },
  "data": [
    {
      "id": "024d804b-1267-4483-aab8-f25f22441062",
      "name": "BRAND Temperature Sensor",
      "created": "2017-07-18T09:38:16.164Z",
      "public": true
    }
  ]
}

UnauthorizedResponse: object

error: string
Example
{
  "error": "Unauthorized."
}

ClientErrorResponse: object

error: string
Example
{
  "error": "'id' must be a valid GUID"
}

ServerErrorResponse: object

error: string
Example
{
  "error": "Something went wrong."
}

ResourcesNotFoundResponse: object

error: string
Example
{
  "error": "Resources not found for Thing Type 024d804b-1267-4483-aab8-f25f22441061"
}

NotFoundResponse: object

error: string
Example
{
  "error": "Not found."
}
Documentation by Spectacle