Developer API

This page provides information for developers wishing to access News Curator via its API.

Overview

The News Curator API allows interested developers to access key services of News Curator via its RESTful API. This section provides an overview of the API, and explains fundamental concepts.

Clients

In order to use the API, developers must first create an API client. API clients are created on the Settings page (requires to be signed in).

Tokens

Using the client ID and secret, developers can acquire an access token from the token endpoint. This token is then used to access the API. The token endpoint is compliant with the OAuth 2.0 RFC, and returns access tokens compliant with the Bearer Token RFC.

Users

Because the services provided by News Curator are personal by nature, many APIs allow to specify a user ID with each request. This allows clients to use a single token to perform actions on multiple users. If the client does not specify an explicit user ID with a request, the owner user of the client is implied.

A client can both create and delete users, and typcally creates a user on the News Curator platform for each of its internal users. News Curator assigns an ID to each user which must be stored by the client. By default, API clients are limited to 100 users. Please contact us to discuss terms for larger deployments.

Stories and Audiences

News Curator provides personalized content recommendations for stories. Stories are imported from URLs. Clients can submit stories for import into News Curator. Newscuratorbot will then retrieve the story.

News Curator tracks the audience of each story. Stories that are publicly linked from RSS feeds and the like are with the public audience. Stories imported by clients are with a client-specific audience. A story can have multiple audiences. When querying stories via the API, clients can specify the audiences they are interested in. The public News Curator web site only shows stories that are with the public audience.

Signals

User-specific signals are an important factor for personalized content recommendations. News Curator distinguishes the like, dislike, click, and post signals. The like and dislike signals are explicit signals, and are set by clients when a user provides relevance feedback. The click and post signal are implicit signals, and are set by clients when a users clicks or shares a story.

Clients are not required to support all signal types. However, News Curator requires a minimum number of signals to personalize content recommendations for a particular user. Until that threshold is met, recommendations are determined globally. Clients can request the user resource to determine the current personalization status.

Languages

News Curator currently supports these languages:

Please contact us if you require additional language support.

Terms of Service

Using the News Curator API is subject to the Terms of Service.

Endpoints

This section describes the endpoints of the News Curator API. The prefix of each endpoint is https://newscurator.com.

This is an OAuth 2.0 compliant token endpoint.

Request Parameters
Parameter Optional Description
grant_type No Must be client_credentials.
client_id No The ID of the API client. Found with the client on the Settings page.
client_secret No The secret of the API client. Found with the client on the Settings page.

Following the OAuth 2.0 standard, the client ID and secret can also be passed as a basic authentication header.

Response Parameters
Parameter Optional Description
access_token No The access token.
token_type No The type of access token. Always Bearer.
expires_in No The number of seconds until the access token expires.

Clients must cache an access token for a reasonable duration, such as 60 seconds before its expiry time.

Example
Request
POST /api/oauth/token HTTP/1.1
Host: newscurator.com
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=<client_id>&client_secret=<client_secret>
Response
200 OK
Content-Type: application/json; charset=UTF-8
Cache-Control: no-store

{
    "access_token": "YKZ4sVOnZdUWcT4tr9qrf3lUHkTAXp56r7NDpmGg",
    "token_type": "Bearer",
    "expires_in": 28800
}

Retrieves stories.

Request Parameters
Parameter Optional Description
userId Yes The ID of a user. If omitted, defaults to the owner user of the client.
languages Yes A space-separated list of ISO 639-1 language codes. Restricts returned stories to the specified languages. If omitted, defaults to the languages of the owner user of the client.
audiences Yes Any combination of public, client, specified as a space-separated list. Restricts returned stories to the specified audiences. If omitted, defaults to client.
query Yes Enables the text query mode, and returns stories sorted by relevance to the query, descending.
signal Yes One of like, dislike, click, post. Enables the signal query mode, and returns stories for which the specified signal has been applied, sorted by the time the signal has been applied, descending. The language and audiences query parameters are ignored with this query mode.
storyId Yes Enables the similarity query mode, and returns stories similar to the story with the given ID, sorted by similarity, descending.
count Yes Controls the number of stories returned. Constrained to 1–250. If omitted, defaults to the story count of the owner user of the client.

The API supports four query modes: personalized, text, signal, and similarity. The default personalized mode (based on the user signals) is used if none of the other three modes is enabled, i.e. if neither the query, signal, or storyId parameter is specified.

Response Parameters
Parameter Optional Description
id No The ID of this story.
language No The language of this story specified as an ISO 639-1 language code.
url No The URL of this story at the news site.
title No The title of this story.
description No The description of this story.
site No The site of this story.
time Yes The publication time of this story, in seconds since January 1, 1970 00:00:00 UTC.
thumbnailUrl Yes The URL of a thumbnail image of this story.
score No The relevance score of this story with regard to the user.
signal Yes The signal applied to this story with regard to the user. One of like, dislike, click, post.
Example
Request
GET /api/stories?audiences=client HTTP/1.1
Host: newscurator.com
Authorization: Bearer YKZ4sVOnZdUWcT4tr9qrf3lUHkTAXp56r7NDpmGg
Response
200 OK
Content-Type: application/json; charset=UTF-8

[
    {
	"id": "01234567890123456789abcd",
	"language": "en",
	"url": "https://newscurator.com/about",
	"title": "About News Curator",
	"description": "Stop searching. Start reading what interests you with News Curator. This document explains how the service works, how it uses sophisticated machine learning algorithms to automatically find relevant content for you, and how it maintains security.",
	"site": "News Curator",
	"time": 1501961162,
        "thumbnailUrl": "https://newscurator.com/thumbnails/0123456789abcdef01234567",
        "score": 1.000,
        "signal": "like"
    },
    ...
]

Imports a story. The story is imported with the client-specific audience. If the story already exists, the client-specific audience is added to the set of audiences of the story.

Request Parameters
Parameter Optional Description
id Yes The external ID of the story. The value is used for duplicate detection. If provided, it should correspond to the unique ID, cannonical URL, or GUID used with RSS feeds and the like.
url No The URL of the story.
time Yes The publication time of the story, in seconds since January 1, 1970 00:00:00 UTC.

Clients must only import a story once and store the News Curator assigned story ID internally.

Response Parameters

See story response above.

If the story has not been imported before, the response status is 201 Created, otherwise it is 200 OK. News Curator performs extensive duplicate checking to prevent multiple additions of the same story to its index. While an ID match will always return the existing story, additional matching on URLs and content is also performed.

Example
Request
POST /api/stories HTTP/1.1
Host: newscurator.com
Authorization: Bearer YKZ4sVOnZdUWcT4tr9qrf3lUHkTAXp56r7NDpmGg
Content-Type: application/x-www-form-urlencoded

url=https%3A%2F%2Fnewscurator.com%2Fabout&time=1508457060
Response
201 Created
Content-Type: application/json; charset=UTF-8

{
	"id": "01234567890123456789abcd",
	"language": "en",
	"url": "https://newscurator.com/about",
	"title": "About News Curator",
	"description": "Stop searching. Start reading what interests you with News Curator. This document explains how the service works, how it uses sophisticated machine learning algorithms to automatically find relevant content for you, and how it maintains security.",
	"site": "News Curator",
	"time": 1501961162,
	"thumbnailUrl": "https://newscurator.com/thumbnails/0123456789abcdef01234567",
	"score": 1.000,
	"signal": "like"
}

Sets (or clears) the signal on a story.

Request Parameters
Parameter Optional Description
storyId No The ID of a story.
userId Yes The ID of a user. If omitted, defaults to the owner user of the client.
signal No One of like, dislike, click, post, none.
mode Yes One of create. Sets the signal only if no signal is currently set.

Only one signal is stored per user and story. We recommend that clients use the create mode with the implicit click and post signals to avoid overwriting an explicit like or dislike signal.

Response Parameters

See story response above.

Example
Request
POST /api/stories/01234567890123456789abcd HTTP/1.1
Host: newscurator.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer YKZ4sVOnZdUWcT4tr9qrf3lUHkTAXp56r7NDpmGg

userId=012345678901234567890123&signal=like
Response
200 OK
Content-Type: application/json; charset=UTF-8

{
    "id": "01234567890123456789abcd",
    "language": "en",
    "url": "https://newscurator.com/about",
    "title": "About News Curator",
    "description": "Stop searching. Start reading what interests you with News Curator. This document explains how the service works, how it uses sophisticated machine learning algorithms to automatically find relevant content for you, and how it maintains security.",
    "site": "News Curator",
    "time": 1501961162,
    "thumbnailUrl": "https://newscurator.com/thumbnails/0123456789abcdef01234567",
    "score": 1.000,
    "signal": "like"
}

Creates a user.

Request Parameters

None.

Response Parameters
Parameter Optional Description
id No The ID of this user.
signalCount No The current number of signals of this user.
signalMin No The minimum number of signals required to personalize content recommendations.

Clients must store the News Curator assigned user ID internally.

Example
Request
POST /api/users HTTP/1.1
Host: newscurator.com
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer YKZ4sVOnZdUWcT4tr9qrf3lUHkTAXp56r7NDpmGg
Response
201 Created
Content-Type: application/json; charset=UTF-8

{
    "id": "012345678901234567890123",
    "signalCount": 0,
    "signalMin": 10
}

Retrieves a user.

Request Parameters
Parameter Optional Description
userId No The ID of a user. Can be specified as - to retrieve the owner user of the client.
Response Parameters

See user response above.

Example
Request
GET /api/users/012345678901234567890123 HTTP/1.1
Host: newscurator.com
Authorization: Bearer YKZ4sVOnZdUWcT4tr9qrf3lUHkTAXp56r7NDpmGg
Response
200 OK
Content-Type: application/json; charset=UTF-8

{
    "id": "012345678901234567890123",
    "signalCount": 0,
    "signalMin": 10
}

Deletes a user.

Request Parameters
Parameter Optional Description
userId No The ID of a user.

The API does not allow to delete the owner user of the client.

Response Parameters

None.

Example
Request
DELETE /api/users/012345678901234567890123 HTTP/1.1
Host: newscurator.com
Authorization: Bearer YKZ4sVOnZdUWcT4tr9qrf3lUHkTAXp56r7NDpmGg
Response
204 No Content