API Reference

Welcome to the Geeny API Explorer! Here you can learn about how to interact with the platform through our HTTP APIs. Each API endpoint includes a reference page with information about parameters, entities and sample requests/responses.

How to use the Geeny API

The Geeny API returns JSON objects for successful requests. Supply the following header with your requests:

Content-Type: application/json

Authorization is handled through the OAuth 2 flow implemented through the Connect API endpoint (see below).

HTTP Status Codes & Errors

We use standard HTTP status codes in our API responses, such as the following:

Code Description
200 OK The API call was successful and a JSON object is returned.
201 Created A new object was created on the Geeny platform. The API will return a JSON object.
204 No Content An object was deleted.
400 Bad Request The request was improperly formatted. Check your API request for an improper content-type header or an expired authorization token.
401 Unauthorized Your request included an invalid auth token.
403 Forbidden You don’t have permission to perform the requested operation.
404 Not Found The API couldn’t find the requested resource.
500 Internal Server Error Something went wrong on our end.

Connect API

The Connect API manages Geeny user accounts and allows users to connect Geeny with external data providers. It is a standard OAuth 2 implementation.

You must use this endpoint in order to get your authentication token, which is required for making calls to the other endpoints.

This endpoint includes operations for:

  • Authenticating and authorizing your account with Geeny.
  • Managing your user profile.
  • Completing the OAuth flow with third parties (e.g., Fitbit).
  • Retrieving and refreshing authentication tokens.
Click here to go to the Connect API reference.

Thing Manager API

The Thing Manager API is responsible for registering and modifying Things, Thing Types and Message Types. Use this API to register your IoT devices on the Geeny platform.

Click here to go to the Thing Manager API reference.

Application Broker API

The Application Broker is a pub/sub mechanism that provides Geeny applications with access to data sent by Things.

When your application needs to access Thing data, it must send a request to the Application Broker. The Application Broker captures data records from the stream in the form of a shard. Then, the application can extract the data directly from the shard.

This endpoint requires a connected application.

Click here to go to the Application Broker API reference.

Push Messages API

The Push Messages API provides an HTTP interface for pushing messages from a Thing Provider cloud to the Geeny platform. This is the API Thing Providers must implement in their cloud as part of their onboarding to the Geeny Alliance.

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. This will send test messages to a Virtual Device dynamically created on the Developers Dashboard for the owner of the Thing Type. See step 5 of the Thing Providers onboarding guide for more information.

Click here to go to the Push Messages API reference.