The Shaping Tomorrow (ST) REST API is designed to allow you to interact with our database. It requires a registered ST user’s login credentials and apiKey, alternatively you can register a new user and use the new credentials to generate a deviceToken. Using the apiKey and deviceToken as authentication credentials you can add sources that will be scanned and analysed by our Athena robot. You can also search our database of future Indicators and even generate summaries based on text submitted to the API. Output is JSON only except for certain endpoints that will serve up a PDF file when the relevant argument is provided to the method.
The API is currently limited to one request per second, per deviceToken.
The first thing you need is an API Key, to get one send an email to firstname.lastname@example.org with the subject line “API Key Request”. Please include details in the email about what you would like to use the API for and what kind of app you’ll be building.
Once you have your API key, you’re ready to begin! The full and most up to date version of the API documentation is available here.
With the API key you can authenticate a user, or register and then authenticate them. Once you have a deviceToken you can begin sending requests. To authenticate a user send a request containing the user’s email, password, deviceId and your apiKey to the authentication endpoint located at:
The JSON request body should look like this (fields are not case sensitive), the values may also be posted as form fields:
The response body looks like this:
Once the authentication is successful you need store the deviceToken locally in your app.
That’s all we require for access, with the apiKey and deviceToken you can now access all the other endpoints.
To list the FORECASTS belonging to a user you would send a GET request to the following endpoint:
To search the FORECASTS you send a POST request to the same endpoint
devicetoken = stored token (REQUIRED)
apiKey = your apiKey (REQUIRED)
q = search query (REQUIRED)
ws = boolean (OPTIONAL)
pdf = boolean (OPTIONAL)
In both of the above cases you can add ws=true to the request and this will return the output via the WebSummarizer API instead of simply returning a list of FORECASTS. Both methods also allow you to return a PDF instead of JSON. Simply add an argument pdf and set the value to true
Posting data to the API can be done with form fields or a JSON string.
For full details about each endpoint please consult the API docs, this section is only intended as a high-level overview.
Allows a new user to be registered with ST, the user will receive a confirmation email and will also be subscribed to our weekly newsletter.
The main indicator listing endpoint, allows for both a list of the most recent Indicators added by the user, as well as a search interface accepting a query parameter. The GET request can include parameters to filter by sector as well as tag. In addition, the results can be sent to WebSummarizer before being returned. An additional argument can also instruct the API to respond with a simple PDF file for offline reading, sharing, etc.
Allows a block of text to be sent to the WebSummarizer API which will respond with the summary. The output for this endpoint may be a file in PDF format as well as the standard JSON response.
Add a new source to the database and Athena’s tasklist. The source may be a Twitter @username, Twitter profile URL, Twitter #hashtag, RSS feed URL or a Bing web search. A tag argument may also be included which will automatically be added to the source. Any Insights and Indicators found by Athena will also be associated with this tag. Additional methods in this endpoint also allow developers to list out all the sources added by the user, optionally filtered by tag. The GET request will also return data on the amount of content Athena is gathering. Additionally, this endpoint can be used to delete a source belonging to the authenticated user from the database
List the sectors from the database with title and ID. The ID can be used with the SECTOR argument in the list endpoint to output Indicators by sector. Post a sector ID and get back the TITLE.
List the tags belonging to sources added by the authenticated user. The tag can be used to output a list of indicators by posting the tag to the list endpoint. This endpoint also accepts a ‘typeahead’ argument which can be used to search based on initial letters, eg. dro would list drones, drown, etc. This endpoint can also be used to remove a user’s tag should that be required.
We welcome feedback on our API and documentation, and our team is also more than willing to assist you in understanding how everything works. We may even be willing to create new endpoints that are not currently included, if you feel that there is functionality you would like to include in your app. To get in touch, contact us via email, Twitter or telephone: