API v1 Reference

This version of the API is deprecated and should not be used for new projects. We are expecting to remove access to these endpoints at the end of June 2017.

This API reference is organized by resource type. Each resource type has one or more data representations and one or more methods.

Content Items

For Content Items resource details, see Content Items

ResourceDescription
GET /content/items/v1/{itemId} Get an item of content.
POST /content/search/v1 Search all items of content. This will return a list of content items. Some item properties are not available using this method. Full details can be retrieved using the get method for a particular item of content.

Content Items Notification

For Content Items Notification resource details, see Content Items Notification Resource Representation.

ResourceDescription
GET /content/notifications/v1/items Get a list of content items that have been created, changed or deleted.

Pages

For Pages resource details, see Page Resource Representation.

ResourceDescription
GET /site/v1/pages List all pages available on www.ft.com. For full details of a specific page, use the Get method for a page.
GET /site/v1/pages/{pageId} Get a page available on www.ft.com.

Page Items

For Page Items resource details, see Page Item Resource Representation.

ResourceDescription
GET /site/v1/pages/{pageId}/main-content List the main items available on a page on www.ft.com.
GET /site/v1/pages/{pageId}/skyline-content List the skyline items available on a page on www.ft.com.

* URIs are relative to the base URI: http://api.ft.com

Quick Start

The Quick Start examples make use of curl. Other tools are available.

Search for content

1. Search

curl -d "{ \"queryString\": \"banks\" }" http://api.ft.com/content/search/v1?apiKey=yourKey

This will return a list of content items. For further details see the Search Tutorial.

2. Retrieve full details for an item of content

Some item properties are not available using the Search method. Full details can be retrieved using the Get method.

curl http://api.ft.com/content/items/v1/82f33b7a-9272-11e1-abdf-00144feab49a?apiKey=yourKey

Browse for content

1. Retrieve all published pages

curl http://api.ft.com/site/v1/pages?apiKey=yourKey

This will return the list of all published pages on www.ft.com. To retrieve further details about any page, follow the url specified in property "apiUrl".

2. Retrieve the UK Front Page

curl http://api.ft.com/site/v1/pages/4c499f12-4e94-11de-8d4c-00144feabdc0?apiKey=yourKey

The link with property "rel" equal to "main-content" can be followed to retrieve the main content on the UK Front Page. The link with property "rel" equal to "skyline-content" can be followed to retrieve the skyline content on the UK Front Page.

3. Retrieve main content on the UK Front Page

curl http://api.ft.com/site/v1/pages/4c499f12-4e94-11de-8d4c-00144feabdc0/main-content?apiKey=yourKey

This request will return the list of page items as they appear on the UK Front Page (including Editorial overrides) with links (rel="content-item") to the underlying item of content.

4. Retrieve skyline content on the UK Front Page

curl http://api.ft.com/site/v1/pages/4c499f12-4e94-11de-8d4c-00144feabdc0/skyline-content?apiKey=yourKey

This request will return the list of page items as they appear in the skyline of the UK Front Page (including Editorial overrides) with links (rel="content-item") to the underlying item of content.

5. Retrieve item of content

curl http://api.ft.com/content/items/v1/82f33b7a-9272-11e1-abdf-00144feab49a?apiKey=yourKey

Property Values

Each property described within the API reference documentation has a value which may be one of the following:

ValueDescription
string A sequence of zero or more Unicode characters, wrapped in double quotes, using backslash escapes.
number A number is very much like a C or Java number, except the octal and hexadecimal formats are not used.
datetime The date time formatted as an ISO8601 style string, wrapped in double quotes. For example: 2012-01-11T03:24:00Z.
boolean Either true or false.
object An unordered set of name/value pairs. Begins with { and ends with }. Each name is followed by : (colon). Name/value pairs are separated by , (comma).
list An ordered collection of values. Begins with [ and ends with ]. Values are separated by , (comma).

Typical HTTP Status Codes

Http StatusDescription
200 OK The resource exists and has been returned
400 Bad Request The request could not be understood by the server due to malformed syntax
401 Unauthorised The request requires user authentication. The client does not have the necessary credentials
403 Forbidden The request was valid, but the content won't be returned. This could be because the content is restricted or not supported
404 Not Found

The resource could not be found, but may be available in the future

410 Gone The resource no longer exists
429 Too Many Requests The request has been throttled before being processed
500 Internal Server Error An error occurred on the server
503 Service Unavailable The server is currently unable to handle the request, due to temporary overloading or maintenance of the server

JSONP

JSONP is supported for all GET based methods by supplying the parameter "callback" with the request. E.g.

GET /site/v1/pages/pageId?callback=myFunction&apiKey=yourApiKey

Versioning

Clients should be aware of the versioning policy for the API. Clients that ignore the policy may find that their client may break unexpectedly.