Pocket Getting Started: Account, Keys, and First Save (2026)

Getting started overview

Integrating with Pocket programmatically involves a sequence of steps to establish secure communication and authorize actions. The core process includes creating a Pocket account, obtaining a consumer key for your application, and implementing an OAuth 2.0 authorization flow to allow users to grant your application access to their Pocket data. Once authorized, you can make API calls to save and retrieve items.

This guide focuses on the initial setup: account creation, key acquisition, and executing a foundational API request. The Pocket API is primarily designed for saving and retrieving content, making it suitable for applications that manage or enhance reading experiences.

Here is a quick reference for the initial setup:

Create an account and get keys

Before interacting with the Pocket API, you need a Pocket account and an associated consumer key for your application. The consumer key identifies your application to the Pocket API and is essential for all API requests.

1. Create a Pocket Account

If you do not already have one, create a free Pocket account. This account will serve as your developer account and allow you to manage your applications and their associated consumer keys.

• Navigate to the Pocket sign-up page.
• Follow the prompts to create your account using an email address, Google account, or Apple ID.

2. Request a Consumer Key

Once your Pocket account is active, you can request a consumer key for your application. This key is unique to your application and is used in the OAuth authorization flow.

• Log in to your Pocket account.
• Visit the Pocket Developer Applications page.
• Click on "Create a New Application."
• Provide the required details:
• Application Name: A descriptive name for your application.
• Application Description: A brief explanation of what your application does.
• Application Homepage: The URL of your application's website (if applicable).
• Permissions: Select the necessary permissions (e.g., "Add," "Modify," "Retrieve"). For a basic "add" request, select "Add."
• Redirect URI: This is a crucial URL where Pocket will redirect the user after they authorize your application. For development, you can use a placeholder like https://example.com/callback or https://localhost if testing locally. The Pocket documentation provides guidance on choosing a Redirect URI.
• Agree to the developer terms and click "Create Application."
• Your consumer key will be displayed. Keep this key secure, as it identifies your application.

Your first request

Making your first request to the Pocket API involves completing the OAuth 2.0 authorization flow to obtain an access token, which then allows you to interact with a user's Pocket account. This example demonstrates saving an item.

The OAuth flow for Pocket involves three main steps:

1. Request a Request Token: Your application requests a temporary token from Pocket.
2. Authorize User: You redirect the user to Pocket to grant your application permission.
3. Exchange for Access Token: Your application exchanges the temporary token for a permanent access token.

Step 1: Get a Request Token

Send a POST request to the /oauth/request endpoint to obtain a request token. This token is valid for 10 minutes.

POST /oauth/request
Host: getpocket.com
Content-Type: application/json; charset=UTF-8
X-Accept: application/json

{
  "consumer_key": "YOUR_CONSUMER_KEY",
  "redirect_uri": "YOUR_REDIRECT_URI"
}

A successful response will include a code, which is your request token:

{
  "code": "YOUR_REQUEST_TOKEN"
}

Step 2: Authorize the User

After obtaining the request token, you must redirect the user to a Pocket URL where they can authorize your application. This step requires user interaction in a web browser.

https://getpocket.com/auth/authorize?request_token=YOUR_REQUEST_TOKEN&redirect_uri=YOUR_REDIRECT_URI

The user will be prompted to log in to Pocket (if not already logged in) and grant access to your application. Upon successful authorization, Pocket redirects the user back to your specified redirect_uri.

Step 3: Exchange for an Access Token

Once the user has authorized your application, you exchange the request token for a permanent access token. This token allows your application to make authenticated API calls on behalf of the user.

POST /oauth/authorize
Host: getpocket.com
Content-Type: application/json; charset=UTF-8
X-Accept: application/json

{
  "consumer_key": "YOUR_CONSUMER_KEY",
  "code": "YOUR_REQUEST_TOKEN"
}

A successful response will provide the access_token and the associated username:

{
  "access_token": "YOUR_ACCESS_TOKEN",
  "username": "testuser"
}

Store the access_token securely, as it is used for all subsequent API requests for that user.

Step 4: Save an Item (First API Call)

Now, with your consumer_key and the user's access_token, you can make your first API call to save an item to their Pocket list. Use the /v3/add endpoint.

POST /v3/add
Host: getpocket.com
Content-Type: application/json; charset=UTF-8
X-Accept: application/json

{
  "url": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200",
  "title": "MDN Web Docs: 200 OK Status",
  "consumer_key": "YOUR_CONSUMER_KEY",
  "access_token": "YOUR_ACCESS_TOKEN"
}

A successful response will include details about the added item, such as its item_id:

{
  "item": {
    "item_id": "123456789",
    "normal_url": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200",
    "resolved_id": "123456789",
    "resolved_url": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200",
    "given_url": "https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/200",
    "given_title": "MDN Web Docs: 200 OK Status",
    "favorite": "0",
    "status": "0",
    "time_added": "1678886400",
    "time_updated": "1678886400",
    "time_read": "0",
    "time_favorited": "0",
    "sort_id": 0,
    "resolved_title": "200 OK - HTTP | MDN",
    "word_count": "150"
  },
  "status": 1
}

This confirms that your application has successfully authenticated and saved an item to the user's Pocket account.

Common next steps

After successfully saving your first item, consider these common next steps to expand your application's functionality:

• Retrieve Items: Implement the Retrieve API to fetch a user's saved articles. This allows you to display, filter, or process their Pocket content.
• Modify Items: Explore the Modify API to update tags, mark items as read, or delete them. This enables a full range of content management features.
• Error Handling: Implement robust error handling for API responses. The Pocket API returns specific error codes and messages that your application can use to inform users or troubleshoot issues.
• Rate Limits: Be aware of Pocket's API rate limits to prevent your application from being temporarily blocked. Design your application to respect these limits, potentially by implementing exponential backoff for retries.
• User Interface Integration: Integrate the Pocket saving functionality directly into your application's UI, providing a seamless experience for users.
• Explore Webhooks: While Pocket's primary API is request-response, consider if there are other mechanisms or partner integrations that could provide real-time updates if your use case requires them.

Troubleshooting the first call

Encountering issues during the initial API setup is common. Here are some troubleshooting tips for your first Pocket API call:

• Invalid Consumer Key: Double-check that you are using the correct consumer key obtained from your Pocket Developer Applications page. A typo will result in authentication failures.
• Incorrect Redirect URI: The redirect_uri used in your OAuth requests must exactly match the one configured for your application on the Pocket Developer Applications page. Even a trailing slash can cause a mismatch.
• Expired Request Token: The request token obtained in Step 1 is only valid for 10 minutes. If you take too long to complete the authorization, you will need to request a new one.
• Missing Permissions: Ensure that your application has been granted the necessary permissions (e.g., "Add") when you created your consumer key. If you try to perform an action without the corresponding permission, the API will reject the request.
• Invalid Access Token: Verify that the access token you are using for the /v3/add request is the one returned from the /oauth/authorize endpoint. Access tokens are user-specific.
• Content-Type Header: Ensure your requests include the Content-Type: application/json; charset=UTF-8 and X-Accept: application/json headers as specified in the Pocket API documentation for JSON requests.
• Network Issues: Confirm that your application can reach getpocket.com. Check firewalls or proxy settings if requests are not reaching the server.
• Review Pocket API Documentation: The official Pocket API documentation provides detailed explanations of endpoints, parameters, and error responses. Refer to it for specific error codes or unexpected behavior.