Netflix will allow you to access catalog and subscriber data, such as queues, ratings, history, and reviews, as long as you've signed up as a developer and the subscriber has agreed to allow you to access his account. We use OAuth, which helps us achieve two important goals:

• Netflix subscribers never reveal their login credentials to anyone who isn't Netflix. Since their credentials stay here where they belong, subscribers can instantly revoke individual access permissions without having to change their passwords.
• Netflix resources are used only by approved developers, maximizing availability for everyone.

Before You Go Any Further

If you have not done so already, you'll need to register with the Netflix Developer Network. Please visit http://developer.netflix.com/member/register and fill out our handy form. It's pretty painless; we'd like to know a few things about you and your plans, and we need you to agree to our Terms of Service. After you register, we will provide you with your consumer key and shared secret, which you will need before anything else on this page will make sense.

Once you've registered, please go try out the Netflix Authentication Walk-Through. The Walk-Through will step you from your first token request all the way through adding, changing, and deleting the Netflix queue items listed on this page, without having to write any code. It may also be useful later if you have trouble understanding how to sign calls or make requests.

API Requests

• Non-Authenticated Calls (Consumer Key Only)

  Here we just need to be sure that you're a registered developer. Your consumer key will be assigned to you when you sign up as a Netflix developer. (Here the confusing term consumer refers to your application, not its eventual user, the paying Netflix subscriber. Your application is the OAuth consumer, so it needs the consumer key.) You'll need your consumer key to use our autocomplete search and JavaScript API.

• Signed Requests (Consumer Key plus Signature)

  Here we make sure that only registered developers are using Netflix data. To create a signature, you'll sign your request using your shared secret, another pre-assigned value. Most of our catalog resources--search, title, and people look-ups--require a signed request.

• Protected Requests (Consumer Key, Signature, and Access Token)

  Here we have to be extra-careful, because someone who isn't Netflix is trying to tell us that he has permission to act on behalf of a Netflix subscriber. Once you've successfully authenticated your application on behalf of a subscriber, we will carry out your requests until he revokes your access permission. Any request for subscriber data require your consumer key and an access token, and must be signed with your shared secret and a token secret.

API Request Limits

Calls to the Netflix APIs will be limited, as follows:

• Requests of any sort per second: 4
• Signed requests (consumer key plus signature, no access token required) per day: 5,000
• Protected requests (consumer key, signature, and access token) per unique Netflix user per day: 5,000

What's the difference between signed and protected requests?

• Signed requests are anonymous calls to the Netflix catalog, not necessarily on behalf of any particular subscriber. These are limited to 5000 per day.
• Protected requests are made on behalf of a signed-in Netflix subscriber. Each signed-in subscriber gets 5000 requests per day, so it makes a lot of sense to try to get your subscribers to sign in before letting them search the catalog.

Making Non-Authenticated Calls

As of this writing, the JavaScript API and the autocomplete catalog search are the only two developer resources at Netflix that can be queried without signing. As a warmup exercise, let's try out the typeahead search:

http://api.netflix.com/catalog/titles/autocomplete
?oauth_consumer_key=YourConsumerKey
&term=frances%20mc

Copy the line above, paste it into any browser, and substitute your consumer key for the bit that says YourConsumerKey. If it's is working, you should get back something substantially similar to this:

<?xml version="1.0" standalone="yes"?>
<autocomplete>
  <url_template>http://api.netflix.com/catalog/titles/autocomplete?{-join|&|term}</url_template>
  <autocomplete_item>
    <title short="Frances McDormand">
  </autocomplete_item>
</autocomplete>

If your consumer key is not working, you'll get this:

Missing Required Consumer Key

Please go back to the My Account page and make sure you've copied it correctly.

Things to Do and Notice

• We asked the API to look for a specific term, frances mc. The space between frances and mc was percent-encoded, which we will explain in just a bit.
• The response came back with a helpful url_template, telling us what request parameters will work. In this case, it's just term; the -join|& business will show up in all API returns, and means you should feel free to send multiple parameters as long as you join them together with an ampersand.

Making Signed Calls

Please keep in mind that OAuth is complicated, especially for beginners. For best results, take it a step at a time, and don't skip steps. If you get all the way through this section and it's not working, please don't go on and try to authenticate on behalf of a subscriber. If you can't hit the catalog, you won't be able to authenticate.

If you're looking for a walk-through for catalog requests only, try out Kent Brewster's Netflix Catalog API Explorer, which will sign your request with your key and secret and show you exactly what the catalog has to say.

Creating Signatures

Throughout your OAuth experience, you'll be "signing" various requests. Each request has four major components:

• The Base String:

  your HTTP verb--almost always GET or POST--plus the base URL, plus all of your request and OAuth parameters.

• The Public Key:

  one of two pieces of information given to you by Netflix. This key will be shown in plain text within the signed URL.

• The Secret:

  the other bit of information given to you by us. Not to be revealed in public to anyone, ever. You'll feed your request, your key, and your secret to a cryptographic function in order to get your signature.

• The Signature:

  a mix of your request, public key, and secret, produced by the magic crypto function referenced above. You make this and send it to us, along with your request and your public key.

Because we're in charge of things, we have your secret on file. If we can run your request, key, and signature backwards through the same cryptographic function you used and the result matches your secret, we will assume that the request is really coming from you and has not been tampered with. There are several cryptographic methods that allow this; we are using HMAC-SHA1.

Percent Encoding

Much trouble with OAuth centers around percent-encoding, also called URL-encoding. Here's the deal: when included in unexpected locations within URLs, certain characters will cause Web servers to behave unpredictably. In order for OAuth to work, these reserved characters must be converted into their hexadecimal values and preceded by a % character. The rest of the character set is unreserved or forbidden, and must not be percent-encoded in either case.

Reserved characters include:

 !   *   '   (   )   ;   :   @   &   =   +   $   ,   /   ?   %   #   [   ]

After percent-encoding, they look like this:

%21 %2A %27 %28 %29 %3B %3A %40 %26 %3D %2B %24 %2C %2F %3F %25 %23 %5B %5D

Unreserved characters must not be percent-encoded. They include the upper- and lower-case letters A through Z, the numbers 0 through 9, and the dash, underscore, period, and tilde characters.

Other characters not mentioned above--carats and pipe-signs and backslashes, for example--are forbidden, and must not be used in URLs, percent-encoded or otherwise, whether or not you're using OAuth.

Percent-encoded characters must appear in upper case. Caution, some .NET libraries don't get this right.

JavaScript's encodeURIComponent() function won't catch them all. You'll need to write a custom function that replaces exclamation marks, asterisks, single-quotes, and parentheses. (Hint: if you were to view the source of the Netflix Authentication Walk-Through, you'd find a complete set of JavaScript OAuth signing functions.)

Constructing the Base String

Your base string must include exactly three elements, separated by exactly two ampersands:

• The HTTP Method Must:

  • Be GET, POST, or DELETE. (DELETE almost never shows up; if you are building a browser-based app, you will use POST to do your deletes, and will overload the HTTP method.)
  • Always be sent in uppercase, and must be percent-encoded. This is already done, since there are no reserved characters in GET, POST, or DELETE.

• The URL Must:

  • Include the scheme, authority, and path, and must exclude the query and fragment, if these exist.
  • Include the port number if it is other than 80 for HTTP or 443 for HTTPS.
  • Be percent-encoded.

• The HTTP Request Parameter String Must:

  • Include all requests you want to pass with the request. This means everything in the body for POSTs and everything after the question-mark for GETs.
  • Include all of those pesky OAuth parameters, to be listed later.
  • Be in alphabetical order, including all the OAuth parameters.
  • Be concatenated together as a single string with ampersand separators.
  • Not begin with a question mark. You're going to sign this string, not send it to a server.
  • Be percent-encoded as a whole, including all the ampersands and equals-signs.

Those Pesky OAuth Parameters

At a minimum, your base string must contain:

• oauth_consumer_key : your application's public key, listed simply as "key" on your developer profile. Throughout this page we will use YourConsumerKey, which will not work if you try it.
• oauth_nonce : a randomly-generated string of characters that helps to prevent replay attacks. Please be sure to make these characters legal to percent-encode or include in URLs, and to regenerate a fresh random string for every OAuth call. Throughout this page we will use abcdefghijk, which would work the first time you tried it--assuming everything else was legit--but not a second time for the same call.
• oauth_signature_method : the cryptographic method you're going to use to sign your call. Always send HMAC-SHA1, in upper-case letters.
• oauth_timestamp : the number of seconds elapsed since midnight, 1 January 1970. Please be sure this is within ten minutes of real time, and also please understand that client-side apps will be at the mercy of their system clocks, and will fail with bad timestamp errors if they're too far off. Throughout this page we will use 1234567890, which will not work if you try it because it came and went on February 13th, 2009.
• oauth_version : optional value for OAuth version. If included, this must be set to 1.0. We will be including it throughout this page and think you should too, to help you keep in mind that the OAuth spec is a living document, and will undoubtedly be updated in the future.

Request Parameters

You'll also need to include your request parameters, which brings us to our first working example, a catalog query. If you wanted the first ten results from /catalog/people for query string frances, you would need to send two request parameters:

• term=frances
• max_results=10

Because max_results comes before oauth_consumer_key and term=frances comes after oauth_timestamp, your OAuth parameters should show up in the middle of your request parameters when sorted. Our base string--broken into several lines to fit on the screen--would look something like this:

GET&
http%3A%2F%2Fapi.netflix.com2Fcatalog2Fpeople&
max_results%3010
%26oauth_consumer_key%3DYourConsumerKey
%26oauth_nonce%3Dabcdefghijk
%26oauth_signature_method%3DHMAC-SHA1
%26oauth_timestamp%3D1234567890
%26oauth_version%3D1.0
%26term%3Dfrances

Things to Do and Notice

• There are exactly two non-encoded ampersands in here, one after the GET and one after the request URL. All the other ampersands in the request string are percent-encoded.
• All parts of the request string are in alphabetical order.
• See the %26 and %3E characters in the request string? They are the percent-encoded ampersands and equals signs, separating the query keys and values.

Signing the Base String

This is the easy part, since you're using a library. You are using a library for this, right? If not, please take a look at the OAuth Code Page. Attempting to engineer an OAuth library before sending your first successful OAuth call is a very hard problem and should be avoided, especially if it's the first time you're using a particular API.

Important: many OAuth requests must be signed with two secrets, your shared secret and the authorized token secret. (We'll show you some in a little while.) If you're signing with two secrets, you must separate them with an ampersand, like this:

YourSharedSecret&AuthorizedTokenSecret

The gotcha? If you are only using one secret, you must include the ampersand at the end, like this:

YourSharedSecret&

Also Very Important: be sure you don't percent-encode your secret, or the ampersand dividing the halves. Your secret never leaves your control, so it doesn't need to be encoded. If you do encode it, your OAuth call is guaranteed not to work, and you'll go blind trying to figure out why.

Why Your Signature Isn't Always the Same Length

The HMAC-SHA1 function should produce a binary string containing exactly 20 ASCII characters, like this:

ËÛe~yì}¸Há|xÐ!vqhíew

Many of these characters cannot be sent as part of an URL, since they are reserved or forbidden. The binary string will probably emerge from your HMAC-SHA1 library in base-64 format, like this:

y9tlfnnsfbhI4Xx40CF2cWjtZXc=

Unfortunately, some of these characters can't be sent as part of an URL, so they need to be percent-encoded, like this:

y9tlfnnsfbhI4Xx40CF2cWjtZXc%3D

Making the Request

All of the percent-encoded stuff must be thrown away after you sign your request. Generate a fresh URL, like so:

http://api.netflix.com/catalog/people
?term=Frances%20McDormand
&max_results=10
&oauth_consumer_key=YourConsumerKey
&oauth_nonce=abcdefghijk
&oauth_signature_method=HMAC-SHA1
&oauth_timestamp=1234567890
&oauth_version=1.0

... and add your signature:

&oauth_signature=YourSignature

Construct this URL using your own developer key, sign it with your own shared secret, fire it off, and you ought to get back search results.

Things to Do and Notice

• Alphabetical order is not important when you send the final query.
• Be careful to percent-encode your query values, especially whatever you're sending for oauth_signature. As noted above in Why Your Signature Isn't Always the Same Length, if it comes back from your HMAC-SHA1 function in base-64 format, chances are pretty good that it contains reserved characters. This, for instance:
  tR3+Ty81lMeYAr/Fid0kMTYa/WM=
  ...contains three reserved characters that need to be percent-encoded, like this:
  tR3%2BTy81lMeYAr%2FFid0kMTYa%2FWM%3D

Having Trouble?

If you're seeing 400 or 401 errors, something's wrong at your end. Here are some possibilities:

Error code 400, "Bad Request."

• You're sending a parameter name that the API doesn't like.
• You're trying to use a parameter that we don't support.
• You're using an unsupported signature method, like plaintext.
• You're missing a required parameter, like oauth_signature.
• You're sending two values for the same OAuth parameter, and we're not sure which one to use.

Error code 401, "Unauthorized."

• Your key is missing or invalid.
• You're re-using a nonce, or sending a nonce containing invalid characters.
• Everything else is fine, but your signature is invalid. (This is the one that means you're almost there.)

If you're seeing a bunch of invalid signatures and are positive you're using the right key and secret, something's up with your percent-encoding. Please go back to Constructing the Base String and check that you are encoding everything properly, separating it with non-encoded ampersands, and sorting all your parameters into alphabetical order before signing.

If after this you are still having trouble, and are stubbornly refusing all advice to use a pre-existing OAuth library, please read True OAuth Confessions, or Why My Hand-Rolled Calls All Blew Chunks, by Kent Brewster.

Other Things That Might Help

• The Netflix Authentication Walk-Through, which you should have already looked at.
• JR Conlin's OAuthTest Page, also on the Netflix Developer Network.
• Mashery's OAuth Signature Validation Tool.
• Term.ie's OAuth Test Client, which also has a OAuth Test Server right next door to play with.
• Google's OAuth Playground, which looks very Google-centric but will let you input your own OAuth server, in the Choose your Scope box.

Making Protected Calls

Once you're getting requests back from the catalog, you're ready to try authenticating on behalf of a Netflix subscriber. Here are the steps in the Three-Legged OAuth Dance:

1. You'll send us a request with your consumer key, signed with your shared secret, just as if you were asking for something in the catalog. This request will tell us "Heads up, gang. I'm about to send over a Netflix subscriber who wants to give me permission to mess around with his account."
2. Once we check that your consumer key and shared secret match up, we'll send you back a request token and a token secret.
3. You'll create a special one-of-a-kind link for your subscriber to click, including the request token, your consumer key, your application's name, and where you want us to send your subscriber once he's signed in.
4. If the subscriber clicks this link, we will send him over to a secure login page on our domain, so he never has to give you his login or password. The login page will contain ominous warnings that the subscriber is about to grant you access to his Netflix account, list some of the things that might happen if you turn out to be a bad guy, and give instructions for revoking access. If the subscriber signs in and you've told us where to send him, we will send him to the callback page you specified in step 3. (If you haven't given us a callback, the subscriber will need to find his way back to your page himself.)
5. When the subscriber lands on your callback page, you'll make one last request, using your consumer key and consumer secret, the request token we sent you in step 2, and the token secret we sent you in step 1.
6. If everything checks out, we will send you an authorization token, an authorization token secret, and a user id. These, along with your existing consumer key and shared secret, are the keys to your subscriber's account. They will remain valid until the subscriber revokes your access, so you won't have to go through the process too often.

Get Your Request Token

Here you're going to ask us to send you a special link for your subscriber to click. The OAuth parameters are exactly the same as the ones you used to query the catalog, so--assuming you got that working--this should work the first time you try it. Form your base string the same way you did with the catalog:

GET&http%3A%2F%2Fapi.netflix.com%2Foauth%2Frequest_token&
oauth_consumer_key%3DYourConsumerKey
%26oauth_nonce%3Dabcdefghijk
%26oauth_signature_method%3DHMAC-SHA1
%26oauth_timestamp%3D1234567890
%26oauth_version%3D1.0

... and sign it with your HMAC-SHA1 library. Percent-encode your signature and make the request, like so:

http://api.netflix.com/oauth/request_token
?oauth_consumer_key=YourConsumerKey
&oauth_signature_method=HMAC-SHA1
&oauth_timestamp=1234567890
&oauth_nonce=abcdefghijk
&oauth_version=1.0
&oauth_signature=YourSignature

If successful, the response you get will include:

oauth_token=YourToken
&oauth_token_secret=YourTokenSecret
&application_name=Your+Application+Name

This is your unauthorized request token, token secret, and the application name you specified when you signed up. If you ever need to change this name, you may do so by clicking the link to your application on the same page where you found your key and secret.

Important: some application names will have spaces in them. These will come back from the initial call to oauth/request_token with plus-signs instead of spaces. Please send your application name exactly the way it came back from the initial call, or your request will fail!

Ask the Subscriber to Sign In

Next, you're going to send the subscriber to our login page to sign in, using your existing application_name and consumer_key, plus the oauth_token you received in the previous step. You are also going to give us the callback URL you want us to send your subscriber back to, as oauth_callback.

Here's a sample URL:

https://api-user.netflix.com/oauth/login
?application_name=Your+Application+Name
&oauth_callback=http%3A%2F%2Fyourserver.com%2Fyourpage
&oauth_consumer_key=YourConsumerKey
&oauth_token=YourToken

This request was not signed with anything. It's being made via https, so signing isn't necessary.

When the subscriber signs in successfully, he'll be redirected back to the callback you specified. It will look like this:

http://yourserver.com/yourpage?oauth_token=yourAuthorizedToken

Send Us the Subscriber's Authorized Request Token

When your callback page receives the subscriber's authorized request token, you'll be able to use it to tell us that he's actually signed in to your application. You'll need to sign your request, so here's your signature base:

GET&
http%3A%2F%2Fapi.netflix.com%2Foauth%2Faccess_token&
oauth_consumer_key%3DYourConsumerKey
%26oauth_nonce%3Dabcdefghijk
%26oauth_signature_method%3DHMAC-SHA1
%26oauth_timestamp%3D1234567890
%26oauth_token%3DYourAuthorizedToken
%26oauth_version%3D1.0

You're going to sign this request with a slightly different secret, consisting of your consumer secret and the token secret that you received in Get Your Request Token, above. the login page sent back to your callback page, separated by an ampersand. To be painfully clear: if your shared secret is 1234567890 and the token secret is YourTokenSecret, you would need to sign your request with 1234567890&YourTokenSecret.

Here's what a signed request looks like:

http://api.netflix.com/oauth/access_token
?oauth_consumer_key=YourConsumerKey
&oauth_signature_method=HMAC-SHA1
&oauth_timestamp=1234567890
&oauth_token=YourAuthorizedToken
&oauth_nonce=abcdefghijk
&oauth_version=1.0
&oauth_signature=YourSignature

Netflix Checks Things Over

Before we hand you the keys to a paying customer's account we're going to double-check a few things:

• The request signature has been successfully verified.
• The request token has never been exchanged for an access token before.
• The consumer key you sent makes sense with the secrets you're using to sign it.

If all of these conditions are true, we'll send you back a new oauth_token, a new oauth_token_secret, and a user_id:

oauth_token=YourAuthorizedOauthToken
&user_id=YourSubscriberId
&oauth_token_secret=YourAuthorizedTokenSecret

Store these in a safe place; they are good until the subscriber revokes your access to his account.

Your First Subscriber Request

To make a request on behalf of a Netflix subscriber, you'll need:

• His encrypted user_id to form the base URL, which is going to look like this:
  http://api.netflix.com/user/YourSubscriberId/
• The authorized oauth_token and oauth_token_secret, returned from the call you just made to /oauth/access_token.
• Your own consumer key and shared secret, which you've been using all along.

Each request must be signed with a combination of your secret and the oauth_token_secret. As above when you sent us the subscriber's authorized request token, you must separate the two secrets with an ampersand.

Even though you already know your subscriber's user_id, let's back up a half-step and start with the resource that gives the shortest possible return, users/current. This resource is necessary for OAuth libraries that don't support standard response extensions, so you may wind up using it quite a bit.

If you send us your subscriber's access permissions, users/current will return the user id. Here's a base string:

GET&
http%3A%2F%2Fapi.netflix.com%2Fusers%2Fcurrent&
oauth_consumer_key%3DYourConsumerKey
%26oauth_nonce%3Dabcdefghijk
%26oauth_signature_method%3DHMAC-SHA1
%26oauth_timestamp%3D1234567890
%26oauth_token%3DYourAuthorizedOauthToken
%26oauth_version%3D1.0

Sign this with your shared secret, an ampersand, and the oauth_token_secret we sent you in the step above. Send us a request, like this this:

http://api.netflix.com/users/YourSubscriberId
?oauth_consumer_key=YourConsumerKey
&oauth_nonce=abcdefghijk
&oauth_signature_method=HMAC-SHA1
&oauth_timestamp=1234567890
&oauth_token=YourAuthorizedOauthToken
&oauth_version=1.0
&oauth_signature=YourSignature

... and we'll send you back something like this:

<resource>
   <link
      href="http://api.netflix.com/users/YourSubscriberId"
      rel="http://schemas.netflix.com/user.current"
      title="current user"></link>
</resource>

Your Basic User Dump

The href contents above are the base URL that you'll need to query all other resources on behalf of this Netflix subscriber. You can also create this without doing the user-dump request if your OAuth library is smart enough to accept the user_id parameter you received when your user signed in.

Here--after it's been signed, which we'll skip from now on since you're doing so well--is how to run a basic user dump:

http://api.netflix.com/users/YourSubscriberId
?oauth_consumer_key=YourConsumerKey
&oauth_nonce=abcdefghijk
&oauth_signature_method=HMAC-SHA1
&oauth_timestamp=1234567890
&oauth_token=YourAuthorizedOauthToken
&oauth_version=1.0
&oauth_signature=YourSignature

Here's what your return should look like:

<?xml version="1.0" standalone="yes"?>
<user>
  <user_id>YourSubscriberId</user_id>
  <first_name>Bob</first_name>
  <last_name>Dobbs</last_name>
  <can_instant_watch>true</can_instant_watch>
  <preferred_formats>
    <category scheme="http://api.netflix.com/categories/title_formats" label="DVD" term="DVD">
    </category>
  </preferred_formats>
  <link href="http://api.netflix.com/users/YourSubscriberId/queues"
  rel="http://schemas.netflix.com/queues" title="queues"></link>
  <link href="http://api.netflix.com/users/YourSubscriberId/rental_history"
  rel="http://schemas.netflix.com/rental_history" title="rental history"></link>
  <link href="http://api.netflix.com/users/YourSubscriberId/recommendations"
  rel="http://schemas.netflix.com/recommendations" title="recommendations"></link>
  <link href="http://api.netflix.com/users/YourSubscriberId/title_states"
  rel="http://schemas.netflix.com/title_states" title="title states"></link>
  <link href="http://api.netflix.com/users/YourSubscriberId/ratings"
  rel="http://schemas.netflix.com/ratings" title="ratings"></link>
  <link href="http://api.netflix.com/users/YourSubscriberId/reviews"
  rel="http://schemas.netflix.com/reviews" title="reviews"></link>
  <link href="http://api.netflix.com/users/YourSubscriberId/at_home"
  rel="http://schemas.netflix.com/at_home" title="at home"></link>
  <link href="http://api.netflix.com/users/YourSubscriberId/feeds"
  rel="http://schemas.netflix.com/feeds" title="feeds"></link>
</user>

Other Queries

Any of the link href values can be plugged right back into the API and queried. Here, without any of the OAuth parameters, is how to view movies recommended by Netflix to our fictional subscriber:

http://api.netflix.com/users/YourSubscriberId/recommendations

Many more calls are documented in the User Resources section of the REST API Reference.

Creating, Updating, and Deleting Queued Items and Ratings

These calls are also thoroughly documented in Managing Queues and User Title Ratings, the only difference between reading and writing or deleting is the HTTP verb. You'll use POST to create new queue items and ratings, and will overload method with delete to remove them.

Get the Latest Etag

For each call that updates subscriber data, you will need his most recent etag. You'll need to submit this along with all write or delete requests, to minimize collisions.

http://api.netflix.com/users/YourSubscriberId/queues/disc/available
?oauth_consumer_key=YourConsumerKey
&oauth_nonce=abcdefghijk
&oauth_signature_method=HMAC-SHA1
&oauth_timestamp=1234567890
&oauth_token=YourAuthorizedOauthToken
&oauth_version=1.0
&oauth_signature=YourSignature

The top of the return should look something like this:

<?xml version="1.0" standalone="yes"?>
<queue>
<etag>YourEtag</etag>

We'll need a fresh etag for every write, update, or delete request. Fortunately, each write, update, or delete request will return a fresh etag with its result, so you won't have to make repeated calls.

Add an Item to a Subscriber's Queue

http://api.netflix.com/users/YourSubscriberId/queues/disc
?etag=FreshEtag
&oauth_consumer_key=YourConsumerKey
&oauth_nonce=abcdefghijk
&oauth_signature_method=HMAC-SHA1
&oauth_timestamp=1234567890
&oauth_token=YourAuthorizedOauthToken
&oauth_version=1.0
&title_ref=http://api.netflix.com/catalog/titles/movies/60029761
&oauth_signature=YourSignature

The tricky part? You'll need to use POST as your HTTP verb when signing this call, and send it to the server via POST, not GET. If you run it with GET, you'll see the user's queue as your response.

If your add was successful, you'll see something like this:

<?xml version="1.0" standalone="yes"?>
<status>
<etag>FreshEtag</etag>
<message>success</message>
<status_code>201</status_code>
<resources_created>
<queue_item>
<id>http://api.netflix.com/users/YourSubscriberId/queues/disc/available/25/60029761
</id>
<position>25</position>
...

Move a Queue Item

In this case, "A Night at the Opera" wound up in queue position 25. Using FreshEtag from the previous return, sign and POST this to move it up to #3:

http://api.netflix.com/users/YourSubscriberId/queues/disc
?etag=FreshEtag
&oauth_consumer_key=YourConsumerKey
&oauth_nonce=abcdefghijk
&oauth_signature_method=HMAC-SHA1
&oauth_timestamp=1234567890
&oauth_token=YourAuthorizedOauthToken
&oauth_version=1.0
&position=3
&title_ref=http://api.netflix.com/catalog/titles/movies/60029761
&oauth_signature=YourSignature

Here's what comes back when we move "A Night at the Opera" to position #3:

<?xml version="1.0" standalone="yes"?>
<status>
<etag>AnotherFreshETag</etag>
<message>Move successful</message>
<status_code>201</status_code>
<resources_created>
<queue_item>
<id>
http://api.netflix.com/users/YourSubscriberId/queues/disc/available/3/60029761
</id>
<position>3</position>
...

Did you notice? We grabbed FreshETag from the last return and used it for the next etag value, so we didn't have to ask for the subscriber's queue again. The return came back with AnotherFreshEtag for our next call.

Yes, it's theoretically possible to add a movie to the top of a subscriber's queue, using position=1 with the initial add, but we strongly suggest you do not do this, since subscribers really hate it when their queues don't behave the way they're used to.

Remove a Queue Item

Copy AnotherFreshETag from the return above, sign, and POST this to remove "A Night at the Opera" from your subscriber's queue:

http://api.netflix.com/users/YourSubscriberId/queues/disc/available/60029761
?etag=AnotherFreshETag
&method=delete
&oauth_consumer_key=YourConsumerKey
&oauth_nonce=abcdefghijk
&oauth_signature_method=HMAC-SHA1
&oauth_timestamp=1234567890
&oauth_token=YourAuthorizedOauthToken
&oauth_version=1.0
&oauth_signature=YourSignature

Remember, to delete with a Web browser, you'll need to overload method by sending method=delete as part of your POST URL. (Browsers don't have access to DELETE under the HTTP spec. If you are making this call with a non-browser-based application, feel free to use the DELETE verb.)

Here's your return:

<?xml version="1.0" standalone="yes"?>
<status>
<status_code>201</status_code>
<message>Title deleted from queue</message>
</status>

What Now?

As we said above, many more calls are documented in the User Resources section of the REST API Reference. Have fun, and please let us know how we're doing, in the Forum, and show us what you're doing, in the App Gallery.