Content API

The aim of the Content API is to offer all of the functionality of our main site to API clients. Currently we support searching and 'real-time' streaming of content, collection management, notification management, and user profile management.

You can view the available enpoints and test out the API functionality in the web-based client.

The API specification is available as a Swagger document.

Authentication

OAuth2

The Content API supports OAuth2 token bearer authentication.

The examples on this page use curl and assume that you have obtained an access_token and exported it as an environment variable, as described in the OAuth2 documentation.

API Key

The Content API also supports API Key authentication. Keys are sent as HTTP Authorization headers with the authentication scheme set to ApiKey.

Example request:

curl -H "Authorization: ApiKey a0bf8f64-e674-439b-ba07-476d069ebba6" https://api.tt.se/content/v1/text/search

Searching

• GET /content/v1/{mediaType}/search?[q=...,p=...,agr=...,tr=...,trs=...,tre=...]

Example

This query will return the 10 most recent text items.

curl -H "Authorization: Bearer ${TOKEN}" https://api.tt.se/content/v1/text/search

Query Syntax

The q parameter is a query string combining free text search, boolean operators and several other features into a powerful query language.

Example: only return objects containing the words 'panda cub'

curl -H "Authorization: Bearer ${TOKEN}" https://api.tt.se/content/v1/text/search?q=panda%20cub

Filtering by customer agreement ID

By default, the search endpoint will match any object covered by any of the current user's customer agreements. You can use the agr parameter to filter to only match certain agreements.

Note that the agreement must still belong to the current user. You can get a list of applicable customer agreements using the /user/agreement endpoint (see below).

Example: only return objects covered by agreements 123 or 456

curl -H "Authorization: Bearer ${TOKEN}" https://api.tt.se/content/v1/text/search?agr=123,456

Filtering by product codes

Product codes allow for a more fine-grained way of filtering content than using agreement IDs. Every object has one or more product codes, describing what products they belong to. You can filter your search result using the p parameter.

As with customer agreements, the search result will still only return objects matching procuts that the current user has an agreement for. You can get a list of applicable product codes using the /user/agreement endpoint (see below).

Example: only return results with TTINR or TTUTR

curl -H "Authorization: Bearer ${TOKEN}" https://api.tt.se/content/v1/text/search?p=TTINR,TTUTR

Absolute time ranges

The trs (Time Range Start) and tre (Time Ranage End) parameters are used to filter search results on the _tstamp property (see Date Handling). The format is YYYY-MM-dd, and midnight is used as the time component for each date. This means that the trs parameter is inclusive, while tre is exclusive.

You're not required to supply both trs and tre; for open-ended queries one is enough.

Example: only return objects from the first half of 2018

curl -H "Authorization: Bearer ${TOKEN}" https://api.tt.se/content/v1/text/search?trs=2018-01-01&tre=2018-07-01

Relative time ranges

The tr parameter

Example: only return objects from the past 7 days

curl -H "Authorization: Bearer ${TOKEN}" https://api.tt.se/content/v1/text/search?tr=w

Streaming

While the GET /content/v1/{mediaType}/search endpoint only returns items that are already present in the database, the notification stream endpoint provides a way to get a near real-time stream of new items as they are being indexed.

Creating a Notification Stream

You first need to create a Notification Stream by calling the POST /content/v1/{mediaType}/notification/stream endpoint, which accepts roughly the same arguments as GET /content/v1/{mediaType}/search, with the exception of arguments that affect time ranges and result pagination. They don't make any sense while streaming data, as we will always return the latest items added.

Notification Streams support streaming content using the _all media type, somethihg that the now-deprecated streaming method GET /content/v1/{mediaType}/stream had problems with.

Consuming a Notification Stream

Items are read from a Notification Stream by calling GET /content/v1/{mediaType}/notification/{id}/stream, where id is the ID of the stream. This is an HTTP long-poll request which will return new items as soon as they are added to the content database, or until the the timeout specified by the wait parameter is reached, whichever comes first. Clients are expected to call this endpoint repeatedly for as long as they wish to recieve new content. If an new item is added has become available in the space between two calls it will be queued and returned in the next response.

Note that the state of the stream is kept server-side, so repeated calls to fetch items from the stream will yield different results. It is safe to make multiple simultaneous calls to read from the same stream; each new item will only be returned once.

Notification streams expire after 5 minutes of client inactivity. Calling GET /content/v1/{mediaType}/notification/{id}/stream on an expired stream will yield HTTP 404.

The Legacy Streaming API

The GET /content/v1/{mediaType}/stream endpoint provides another way to consume content in near real-time, but it has problems dealing with large quantities of items being indexed at the same time, and does not support the _all media type properly. If you are using it, consider using Notification Streams instead.

If you are on Node.js and using the ContentStream helper in the @ttab/content-api client library, all you need to do to switch to Notification Streams is upgrade to version 2.9.

API Client

For developer convenience, TT is providing a JavaScript/TypeScript API client. It supports all API operations and provides TypeScript type definitions for all arguments and return values.