API Documentation

You can use the OrganisedMinds API to take control over your workspaces, members, activities, etc.

Authentication

The API is operational on a per-user basis. Only with valid credentials will you be able to operate any part of the API. With the given credentials you can only unlock those resources inside OrganisedMinds which belong to the user that owns the credentials.

Currently only OAuth2 is supported as a method of authentication.

 

Obtaining credentials

Login to OrganisedMinds and go to your profile by clicking on your avatar at the top left off the screen and then selecting ‘My profile’.

Open the profile

Access your settings tab, by clicking on the cogwheels.

Go to settings

Now scroll to the bottom of the page and fold out the API credentials. If you have no API credentials yet, you can enable them here by clicking ‘Enable Api’

Enable credentials

You can now copy and paste the client-id and client-secret to your own application (or a trusted third party) and start using the API.

Client ID and secret

Please note! Your client-secret should remain a secret. If it falls into the wrongs hands someone could read your activities and those of the people you collaborate with. Don’t harm the trust of your collaborators and handle your API credentials responsibly.

(Also, the id and secret displayed above are fake)

Obtaining an access-token

The access-token can be aquired once you have the credentials. Check the repository of your favourite programming language for an OAuth2 library and carefully read it’s howto.

Access tokens expire after 3 hours. A refresh token is supplied on request.

Using an access token

The access token can be supplied as an Authorization header or as an access_token query parameter.

We prefer that you use the header method, due to the fact that the API is only accessible over TLS your access-token would at least be encrypted.

You should supply your header as follows:

Authentication: Bearer a0f6f5b5ce7227414af0ab8f91d0b61accd7d5009985012ef182708f0eed8d7f

If you insist on using the query parameter mode, you should make each request with

?access_token=a0f6f5b5ce7227414af0ab8f91d0b61accd7d5009985012ef182708f0eed8d7f

Rate limit

The usage of the API is limited. Pro users get 5.000 requests per day. Free users can test the API with 50 requests per-day.

During your free trial period, you will have 5.000 requests per day

You can check your usage by inspecting the response headers of each API request

Example header

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4996

Pagination

Large collections are returned using pagination. You can specify a page and per_page parameter. The pages of the collection are provided in the response headers of such API requests and conform to the Link header (RFC 5988).

The per_page parameter is limited to a maximum of 250 units to spare the server

Example header

Link: <https://app.organisedminds.com/api/items?page=3&per_page=50>; rel="next",
  <https://app.organisedminds.com/api/items?page=2&per_page=50>; rel="previous",
  <https://app.organisedminds.com/api/items?page=8&per_page=50>; rel="last"

Privacy

User slug To prevent discovery and guarantee privacy, users are only accessible over their ‘slug’. This is a random string which could be seen as a nick or username. The typical slug looks like 0e831e95cc54

Conventions

The way this documentation is build up, is as follows:

Name of the API

Action

GET /path
comments powered by Disqus