TON API

The TON (Twitter Object Nest) API allows implementers to upload media and various assets to Twitter. In this document we will cover authentication & authorization, usage, principles, and provide examples to get started.

Please consult with your Platform Relations representative or Ads API Partner Engineer on details specific to your integration; the below information may not be true for your integration. This document covers upload only. The TON API supports other operations but they are not covered in this document, as they are not needed for the upload API.

Authentication & Authorization

The TON API requires 3-legged authorization

Usage

The TON API supports non-resumable and resumable upload methods based on the size of the file. For files less than 64MB, non-resumable may be used. For files greater than or equal to 64MB, resumable must be used. Resumable uploads require chunk sizes of less than 64MB. Calculation of 64MB is based on 1024 bytes (64 * 1024 * 1024).

If your dedicated upload bandwidth for the TON Upload is less than ~20 Mbit/s we recommend using resumable upload even for files less than 64MB in size.

Principles

  • The endpoint for the TON API is ton.twitter.com
  • All requests must be made over HTTPS
  • All responses are in JSON
  • The Content-Type of your request cannot be "application/x-www-form-urlencoded"
  • The Content-Type of your request will be a valid media type as defined by IANA: http://www.iana.org/assignments/media-types/media-types.xhtml
  • Chunks should be in integer multiples of X-TON-Min-Chunk-Size (except the last).
  • The Location header after upload should be saved to be used in subsequent Twitter APIs, such as the Video API.

Buckets

For Tailored Audiences, please use the bucket name ta_partner.

Note that the ta_partner bucket also requires the X-TON-Expires header to be set with an expiration date up to 7 days from the current date (see the ton-upload example script for more detail). For all other TON API buckets, this header is optional however it’s safe and a good practice to pass this header all the time and buckets that do not require it will simply ignore it.

Each bucket can be configured to support additional requirements. To confirm requirements for other features using the TON API, please refer to the documentation of that feature.

Examples

Included below are several examples on how to get started using the TON API. Please note that your Application ID must be whitelisted for the bucket that you are attempting to use.

Twurl

Twurl is a Ruby gem that is like curl, but tailored specifically for the Twitter API. Once configured, it can be used to make requests similar to curl.

An example non-resumable request:

twurl -t -H ton.twitter.com /1.1/ton/bucket/product_bucket_name -X POST -A "Content-Type: image/jpeg" -A "Content-Length: 136" --data "MY PRECIOUS BYTES"

You can find a sample Ruby TON upload script that depends on Twurl here.