API Documentation

API homepage

Introduction

The most important things you first need to know about our API:

  1. Our API is based on OAuth2 (see below).
  2. You need to register your app before the API can be used.
  3. We currently only return data as JSON.
  4. The returned JSON can be very large. Especially when syncing you'd better use a streaming JSON parser (might also be called event-driven or incremental), for example gson in Java, ijson in Python, JSONParser in PHP, or YAJL in C (which has Objective-C bindings).

Methods

  • sync (Offline capable) clients use this method to sync their things with the server.
  • tags/get get all tags of the authenticated user
  • thing/add add a new thing for the authenticated user
  • thing/change change an already existing thing of the authenticated user
  • thing/delete delete a thing of the authenticated user
  • things/get get all things of the authenticated user
  • user/get get information about the authenticated user
  • webhook/register register for a webhook when something has changed
  • webhook/unregister unregister a previously registered webhook

OAuth2 Endpoints

You request a token at https://api.thinkery.me/v1/token

The Base URI for every API call is https://api.thinkery.me/v1/

OAuth2 Explained

OAuth2 is described in the OAuth2 specification. You can find a list of implementations on the OAuth2 Page.

To put it short, you need an access token to access the API which can be retrieved:

  1. with a username and password combination (grant_type=password),
  2. by redirecting the user to our OAuth2 webflow endpoint https://thinkery.me/api/authorize.php, or
  3. by using a refresh token (grant_type=refresh_token).

This access_token is only valid for a certain period of time, typically 1 hour. You will be informed about the validity through the expires_in variable.

With each grant you will also receive a refresh_token that can be used to receive a new access_token.

When accessing the API you either have to specify the access token as an HTTP header Authorization: or as a GET or POST parameter access_token.

Example Implementations

We have example implementations in PHP, Ruby and Python

Examples

You might present the user with a username and password box and then submit this data to the API:

POST /v1/token HTTP/1.1
Host: api.thinkery.me
Content-Type: application/x-www-form-urlencoded
Content-Length: 384

client_id=as-received-when-registering-with-the-api&client_secret=also-given-at-registering&grant_type=password&username=given-by-the-user&password=also-given-by-the-user (this would be urlencoded)

{
  "access_token": "alphanumeric-key",
  "expires_in": 3600,
  "request_token": "another-alphanumeric-key",
  "token_type": "bearer",
  "scope": null
}

As soon as you have received these two tokens, you don't need the username and password anymore to access the API later again.

Refreshing with a refresh_token:

POST /v1/token HTTP/1.1
Host: api.thinkery.me
Content-Type: application/x-www-form-urlencoded
Content-Length: 327

client_id=as-received-when-registering-with-the-api&client_secret=also-given-at-registering&grant_type=refresh_token&refresh_token=as-received-earlier (this would be urlencoded)

{
  "access_token": "alphanumeric-key",
  "expires_in": 3600,
  "request_token": "another-alphanumeric-key",
  "token_type": "bearer",
  "scope": null
}

The three ways to access the api using an access_token (in each case with an expired token):

Using the HTTP header Authorization:

GET /v1/sync HTTP/1.1
Host: api.thinkery.me
Authorization: an-expired-key=the-token-you-received

{
  "error": "invalid_grant",
  "error_description": "The access token provided is invalid"
}

As a GET parameter:

GET /v1/sync?access_token=an-expired-key HTTP/1.1
Host: api.thinkery.me

{
  "error": "invalid_grant",
  "error_description": "The access token provided is invalid"
}

As a POST parameter:

POST /v1/sync HTTP/1.1
Host: api.thinkery.me
Content-Type: application/x-www-form-urlencoded
Content-Length: 27

access_token=an-expired-key (this would be urlencoded)

{
  "error": "invalid_grant",
  "error_description": "The access token provided is invalid"
}