API documentation

We are currently working on a Javascript SDK, meanwhile you may use the REST API. You can find the API spec here.

Thinkeo can be embedded in your app with in ways:

By API
By <iframe>

Generating a token

To use most of Thinkeo API's endpoints, you need an access token. One can be generated with the following shell scriptlet:

auth=$(echo "<email>:<password>" | base64) # needs base64

# This generates a token valid until 31 december 2024
curl --request POST --location 'https://api.thinkeo.io/v0/tokens?expiration=2024-12-31T00:00:00Z&name=my_new_token' \
     --header "Authorization: Basic $auth"

This returns a json with your fresh new token, one like:

{
  "token": "LXYFQSsK3Xij-QqV9owQfvm19OPTzhOd5OfbqBF3WapO-XIt8ca3dSnS6wgm49l9"
}

This token can be used to generate new tokens

Embedding Thinkeo

For now we recommend using our back office (in the official client) to create and organize your apps. This guide assumes that you already have a ready app.

You need to get this information from the interface:

The app's unique id, of the form: deac8787-cbce-417d-8152-f5974e3af56f.
The app's attributes unique ids.
optionally The version string of the app you want to use.

Thinkeo allows you to generate publications easily and fast. To generate a document we need to provide some context. The more refined the context, to better fit your document will be to your needs.

Quick example of a context:

{
  "60f8bec0-57a1-41ae-b9b7-5d635cfabe4c": [
    "apple",
    "banana",
    "orange"
  ],
  "368029c1-7c5f-4836-8242-f2305f736b87": [
    "car",
    "plane",
    "train"
  ]
}

By API

Overview

To generate a new publication, you must call the POST /v0/publications endpoint, like so:

Example using curl:

curl --location 'http://api.thinkeo.io/v0/publications?app=<app_id>&version=<version>' \
--header 'Authorization: Bearer <my_thinkeo_token>' \
--header 'Content-Type: application/json' \
--data '{ "attributes": {} }'

Where <app_id>, <version> and <my_thinkeo_token> are replaced by your app's unique id, the app's desired version and your valid Thinkeo access token respectively.

This typically returns a JSON object of the form:

{
  "publicationId": "93327d8c-28a6-486e-9efe-56c688756cb2",
  "rootBlockId": "84ba4a1d-b3d3-429e-bed3-733d5ed5f0bf",
  "blocks": {
    "84ba4a1d-b3d3-429e-bed3-733d5ed5f0bf": {
      "kind": "concatenation",
      "content": [
        "988e9dc5-849f-49a9-9bcb-f146b8cb1097",
        "78b55782-a14c-4e5a-a6db-5c3ce7b2fe74"
      ]
    },
    "988e9dc5-849f-49a9-9bcb-f146b8cb1097": {
      "kind": "html",
      "content": "<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>"
    },
    "78b55782-a14c-4e5a-a6db-5c3ce7b2fe74": {
      "kind": "html",
      "content": "<p>Praesent scelerisque, sem a aliquam sollicitudin, libero diam hendrerit nisi, eget posuere turpis sem sed diam.</p>"
    }
  }
}

Which, when concatenated, should give the following HTML code:

<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit.</p>
<p>Praesent scelerisque, sem a aliquam sollicitudin, libero diam hendrerit nisi, eget posuere turpis sem sed diam.</p>

The structure is that of a tree, where blocks can either be leaves ("kind": "html") or nodes ("kind": "contatenation"). Concatenation requires the client to recursively explore the tree, starting from the node with id rootBlockId, and then:

If the node is a leaf: return the "content" of the leaf.
If the node is not a leaf: recursively concatenate the contents of the ids in "content", and concatenate them.

JS snippet

The following JS snippet can be used to perform the request and return the content as an HTML string:

async function thinkeoPublication(token, appId, appVersion, context = {}) {
  const res = await fetch(`https:/api.thinkeo.io/v0/publications?app=${appId}&version=${appVersion}`, {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${token}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      attributes: context,
    })
  })

  const { blocks, rootBlockId } = await res.json()

  const concatenated = {}
  function concatenateContent(id) {
    if (concatenated[id]) return concatenated[id]
    const block = blocks[id]
    switch (block.kind) {
      case "concatenation":
        concatenated[id] = block.content.map(concatenateContent).join("")
        break
      case "html":
        concatenated[id] = block.content
        break
    }
    return concatenated[id]
  }

  return concatenateContent(rootBlockId)
}

By `<iframe>`

Thinkeo also supports embedding its official frontend client inside of an <iframe> hosted on your website. First, generate a token that is usable only once, like so:

Example using curl:

AUTH="Basic $(echo "<email>:<password>" | base64)"

# By default, tokens are only good for 1 day. Note the once parameter set to true.
curl --request POST \
--location 'https://api.thinkeo.io/v0/tokens?once=true' \
--header "Authorization: $auth"

The data between thinkeo and the parent window will transit by postMessages. We need to pass the context to the <iframe>. When the user is finished interacting with Thinkeo, the <iframe> will send back the results as a JSON object, in the same format as if using the API (See By API).

<script>
  function setupFrame() {
    const frame = window.frames['<id>']
    // Here we post the context to the iframe
    frame.contentWindow.postMessage({
      message: "context", 
      context: {
        attributes: {}
      }
    )
  }

  function handleThinkeoMessage(event) {
    if ("thinkeoResponse" === event.data.message) console.log(event.data.response.publication)
  }

  window.addEventListener("thinkeoResponse", handleThinkeoMessage);
</script>

<iframe 
  name='<id>'
  src='https://thinkeo.io/publication/new?app=<app_id>&version=<version>&token=<my_thinkeo_token>'
></iframe>

API documentation

Documentation on our REST API and Spec

Generating a token

Embedding Thinkeo

By API​

Overview​

JS snippet​

By <iframe>​

By API

Overview

JS snippet

By `<iframe>`