Curator API Overview

The Curator Broadcaster API is a private API that provides broadcasters their Curator-created streams for on-air graphics systems (or other digital displays).

The Curator Broadcaster API requires special permission to access and is only available for TV broadcast use cases. To request access please visit curator.twitter.com.

This overview page will walk you through the process of creating the necessary credentials, testing your access, reviewing the principles and resources, and provide several of the most common use case requests.

Please also checkout the FAQs page inside of the Curator product for additional information.

Getting Started

To get started with the Curator Broadcaster API, you will need to do the following:

• Create a Twitter account that you will use to access the Curator product.
• Access the Curator product and create a Stream.
• Get the ID of the stream that will be used for authentication.
• Make your first API call.

Creating Accounts

Twitter Account

To begin, go to twitter.com and create an account. We recommend creating a new account that will be used for your application. The email address is usually best set to a team alias and not to an individual account (for password reset and account management purposes). Please set a complex generated password. Once you have created your account, you may want to adjust a couple initial settings- disabling email notifications, marking the account private, disabling tagging, and requiring personal information to reset the password.

You will not be able to continue to the next section until your Twitter Account has been whitelisted to use the Curator product. Please contact your Platform Relations representative.

Create Curator Stream & Get ID of the Stream

Login to Curator and create a Stream. Once your stream is created, click on Outputs on the left. Copy either URL in the left pane and paste it so that you can see the whole thing. Save the ID of the stream which is the number following streams/ and the auth token which is the auth parameter.

Making API Calls

All API calls require an auth parameter for authentication. In addition, all API calls require the ID of the stream that you are asking about.

Resources in the Curator Broadcaster API

The Curator Broadcaster API has two main resources: /streams and /collections.

• The streams resource is the curated stream resource that is created in the Curator product.
• The collections resource is a specific collect of Tweets from a curated stream.

The following resources are currently available:

• GET collections/:id/content
• GET projects
• GET projects/:id
• GET streams/:id/content
• GET streams/:id/metrics
• GET streams/:id/trendline
• GET streams/compare
• GET streams/compare_to_target

The trendline endpoint is limited in duration based on the granularity requested:

• Requests with minute granularity are limited to less than 2 hours in length
• Requests with hour granularity are limited to less than 5 days in length
• Requests with day granularity are limited to less than 30 days in length

The metrics, compare, and compare_to_targe endpoints take a start_time parameter which will be rounded down and end_time parameter which will be rounded up to the smallest granularity allowed by the rules above.

Example Requests

The following are example requests.

To test them with curl, you can use the following: curl https://curator.twitter.com/broadcast/1/streams/<stream_id>/?auth=<auth_token>&limit=

Latest Tweet Content

The latest Tweets in the given stream.

https://curator.twitter.com/broadcast/1/streams/<stream_id>/content?auth=<auth_token>&limit=25

Latest Collection Tweets

The latest Tweets in the given collection.

https://curator.twitter.com/broadcast/1/collections/<collection_id>/content?auth=<auth_token>&limit=25