send
Pocket API: Modifying a User's Pocket Data
Pocket’s /v3/send endpoint allows you to make a change or batch several
changes to a user’s list or Pocket data.
Required Permissions
In order to use the /v3/send endpoint, your consumer key must have the
"Modify" permission.
Modifying a User's Pocket Data
The /v3/send endpoint allows your application to send a single event or multiple events and actions that will modify the user's data in one call.
Method URL
https://getpocket.com/v3/send
Parameters
| Name | Type | Description |
|---|---|---|
| consumer_key | string | Your application's Consumer Key |
| access_token | string | The user's Pocket access token |
| actions | array | JSON array of actions. See below for details. |
JSON Array Format
You can send one action or you can send dozens. The list of actions should be sent as a JSON array.
Here's an example of a JSON array calling the "archive" action:
[
{
"action" : "archive",
"item_id" : "229279689",
"time" : "1348853312"
}
]
Here's how you send the encoded JSON array as part of the /v3/send call:
https://getpocket.com/v3/send?actions=%5B%7B%22action%22%3A%22archive%22%2C%22time%22%3A1348853312%2C%22item_id%22%3A229279689%7D%5D&access_token=[ACCESS_TOKEN]&consumer_key=[CONSUMER_KEY]
The response you receive back contains a status variable and an action_results array that indicates which action had an issue if the status is 0 (indicating failure):
HTTP/1.1 200 OK
Content-Type: application/json
Status: 200 OK
{"action_results":[true],"status":1}
Error Handling
View the Error and Response Headers Documentation for detailed information on how to respond to errors.
List of Actions
Basic Actions
- add - Add a new item to the user's list
- archive - Move an item to the user's archive
- readd - Re-add (unarchive) an item to the user's list
- favorite - Mark an item as a favorite
- unfavorite - Remove an item from the user's favorites
- delete - Permanently remove an item from the user's account
Tagging Actions
- tags_add - Add one or more tags to an item
- tags_remove - Remove one or more tags from an item
- tags_replace - Replace all of the tags for an item with one or more provided tags
- tags_clear - Remove all tags from an item
- tag_rename - Rename a tag; this affects all items with this tag
- tag_delete - Delete a tag; this affects all items with this tag
Action: add
Add a new item to the user's list.
Note: If you are only adding a single item, the /v3/add endpoint should be used.
JSON Array Parameters
| Name | Type | Optional | Description |
|---|---|---|---|
| item_id | integer | The id of the item to perform the action on. | |
| ref_id | integer | optional | A Twitter status id; this is used to show tweet attribution. |
| tags | string | optional | A comma-delimited list of one or more tags. |
| time | timestamp | optional | The time the action occurred. |
| title | string | optional | The title of the item. |
| url | string | optional | The url of the item; provide this only if you do not have an item_id. |
Action: archive
Move an item to the user's archive.
JSON Array Parameters
| Name | Type | Optional | Description |
|---|---|---|---|
| item_id | integer | The id of the item to perform the action on. | |
| time | timestamp | optional | The time the action occurred. |
Action: readd
Move an item from the user's archive back into their unread list.
JSON Array Parameters
| Name | Type | Optional | Description |
|---|---|---|---|
| item_id | integer | The id of the item to perform the action on. | |
| time | timestamp | optional | The time the action occurred. |
Action: favorite
Mark an item as a favorite.
JSON Array Parameters
| Name | Type | Optional | Description |
|---|---|---|---|
| item_id | integer | The id of the item to perform the action on. | |
| time | timestamp | optional | The time the action occurred. |
Action: unfavorite
Remove an item from the user's favorites.
JSON Array Parameters
| Name | Type | Optional | Description |
|---|---|---|---|
| item_id | integer | The id of the item to perform the action on. | |
| time | timestamp | optional | The time the action occurred. |
Action: delete
Permanently remove an item from the user's account.
JSON Array Parameters
| Name | Type | Optional | Description |
|---|---|---|---|
| item_id | integer | The id of the item to perform the action on. | |
| time | timestamp | optional | The time the action occurred. |
Action: tags_add
Add one or more tags to an item.
JSON Array Parameters
| Name | Type | Optional | Description |
|---|---|---|---|
| item_id | integer | The id of the item to perform the action on. | |
| tags | string | A comma-delimited list of one or more tags. | |
| time | timestamp | optional | The time the action occurred. |
Action: tags_remove
Remove one or more tags from an item.
JSON Array Parameters
| Name | Type | Optional | Description |
|---|---|---|---|
| item_id | integer | The id of the item to perform the action on. | |
| tags | string | A comma-delimited list of one or more tags to remove. | |
| time | timestamp | optional | The time the action occurred. |
Action: tags_replace
Replace all of the tags for an item with the one or more provided tags.
JSON Array Parameters
| Name | Type | Optional | Description |
|---|---|---|---|
| item_id | integer | The id of the item to perform the action on. | |
| tags | string | A comma-delimited list of one or more tags to add. | |
| time | timestamp | optional | The time the action occurred. |
Action: tags_clear
Remove all tags from an item.
JSON Array Parameters
| Name | Type | Optional | Description |
|---|---|---|---|
| item_id | integer | The id of the item to perform the action on. | |
| time | timestamp | optional | The time the action occurred. |
Action: tag_rename
Rename a tag. This affects all items with this tag.
JSON Array Parameters
| Name | Type | Optional | Description |
|---|---|---|---|
| old_tag | string | The tag name that will be replaced. | |
| new_tag | string | The new tag name that will be added. | |
| time | timestamp | optional | The time the action occurred. |
Action: tag_delete
Delete a tag. This affects all items with this tag.
JSON Array Parameters
| Name | Type | Optional | Description |
|---|---|---|---|
| tag | string | The tag name that will be deleted. | |
| time | timestamp | optional | The time the action occurred. |