SECTIONS

General Information

To enable remote management of Geenio installations, we provide a comprehensive suite of API methods. To start using Geenio API, first you need to generate the API key.

To generate the API key, log in to Geenio, open your site, click Settings, go to the API tab, and click Regenerate. The generated API key will be displayed.

You will use this key to authenticate when sending API requests. If you believe that your API key may have been compromised, we recommend you to regenerate it by following these instructions again.

To execute an API request, you need to send a specifically formed HTTP packet. This packet must contain the following data:

  • The corresponding HTTP method
  • The hostname of your Geenio instance.
  • The API version.
  • The API method you want to use with any arguments
  • Your Geenio instance IP address, and
  • Your API key

The HTTP method depends on the API method being used. GET is used to retrieve information, PATCH to edit the properties of an entity (user, group, etc.), POST to add new entities, and DELETE to remove them.

The API version and the API method in use are passed as a part of the URL formed according to the following rules:

api.<your instance name>.geen.io + /<API version> + /<API method> + /<optional arguments>

For example. if your instance name is "mycompany", use the hostname: api.mycompany.geen.io. To signify the API version 1, add /v1 after the hostname. To retrieve information about the groups belonging to the instance, add /groups to the URL. The complete packet for the API request may look like this:

GET http://api.mycompany.geen.io/v1/groups

HOST: 53.155.63.56:80

X-API-KEY: f684cde3fdeb55e72e860815d4275d91

As a response, you can expect one of the following HTTP codes:

  • 200 Is returned for GET and POST requests with no errors
  • 204 Is returned for PATCH and DELETE requests with no errors
  • 400 Is returned for POST and PATCH requests if the data failed to pass validation
  • 402 Is returned for POST requests if the license limits have been exceeded on the instance
  • 403 Is returned for any request if the API KEY is invalid
  • 404 Is returned for any request if the specified resource is not found

If the API request has been executed correctly, you will also receive the corresponding JSON response packet. Otherwise, the response will contain the corresponding error message that will help you troubleshoot and resolve the issue.

Sending API requests using REST client for Google Chrome

The most user-friendly way to test Geenio API is to use Advanced REST client app for Google Chrome.

Simply install it to your browser and then set up some basic information:

This includes the request URL and additional HTTP header with name X-API-KEY and the value of your API key.

Once you click SEND it will process the request and output the results below:

It is also possible to switch request method and not only retrieve the data, but also perform modifications. For example, create a user account:

As the result you will see the newly created user data below:

Sending API requests from a command line

Here is how you would test the API call using curl console utility, which is available for most Unix-based OSes:

my-unix-box ~$ curl -H "X-API-KEY: 4aa14f6f0889d1c39d53c8293b47ab8b" -X GET http://api.example.geen.io/v1/users/
{
  "users": [
    ...
    {
      "id": "14530267329445787",
      "name": "Test User via API",
      "occupation": "",
      "location": "",
      "timezone": null,
      "email": "test@mailinator.net",
      "isBanned": false,
      "role": {
        "alias": "learner"
      },
      "image": null
    },
    {
      "id": "1452710290255882",
      "name": "user name",
      "occupation": "",
      "location": "",
      "timezone": null,
      "email": "un@tl.dr",
      "isBanned": false,
      "role": {
        "alias": "learner"
      },
      "image": null
    }
  ],
  "totalCount": 6
}