# put.io Developers

> Build apps, scripts and agents on the put.io API v2. Every link under Docs is a Markdown page.

## Start here

- Operate a put.io account: use [putio-cli](https://github.com/putdotio/putio-cli). Read its [agent skill](https://raw.githubusercontent.com/putdotio/putio-cli/main/skills/putio-cli/SKILL.md) first. The CLI obtains and stores the token; the person approves in their browser.
- Call the API yourself: [get an OAuth token](https://help.put.io/en/articles/5972538-how-to-get-an-oauth-token-from-put-io), then send it as a Bearer token:

  ```sh
  curl -H "Authorization: Bearer $PUTIO_TOKEN" https://api.put.io/v2/account/info
  ```

- Product, pricing and support: [put.io/llms.txt](https://put.io/llms.txt)

## Docs

- [Overview](https://devs.put.io/llms.mdx/content.md): Build apps, scripts and agents on the put.io API.

- **Guides**
- [Authentication](https://devs.put.io/llms.mdx/guides/authentication/content.md): Pick the flow that fits where your app runs.
- [House rules](https://devs.put.io/llms.mdx/guides/guidelines/content.md): What apps built on put.io should and should not do.
- [App checklist](https://devs.put.io/llms.mdx/guides/checklist/content.md): What people expect from a put.io app.
- [SDKs and tools](https://devs.put.io/llms.mdx/guides/sdks/content.md): Libraries and tools we maintain.
- [Our apps](https://devs.put.io/llms.mdx/guides/showcase/content.md): Open-source put.io apps to learn from.

- **API**
- [Introduction](https://devs.put.io/llms.mdx/api/content.md): The put.io REST API, version 2.
- Device link
  - [Check a code](https://devs.put.io/llms.mdx/api/oob/check-a-code/content.md): Poll this until `oauth_token` is not null. The token is returned once; the code is then deleted. Stop polling after that.
  - [Get a code](https://devs.put.io/llms.mdx/api/oob/get-a-code/content.md): Show the code to the user. They enter it at https://app.put.io/link, or scan the QR code at `qr_code_url`. The code expires after 60 minutes. Poll `GET /oauth2/oob/code/{code}` for the token.
  - [Get the QR code](https://devs.put.io/llms.mdx/api/oob/get-the-qr-code/content.md): Returns a PNG QR code that opens https://app.put.io/link with the code filled in. Shares the per-IP rate limit of `GET /oauth2/oob/code`.
- Files
  - [Clear watch position](https://devs.put.io/llms.mdx/api/files/clear-watch-position/content.md)
  - [Convert to MP4](https://devs.put.io/llms.mdx/api/files/convert-to-mp4/content.md)
  - [Create a folder](https://devs.put.io/llms.mdx/api/files/create-a-folder/content.md)
  - [Delete files](https://devs.put.io/llms.mdx/api/files/delete-files/content.md)
  - [Download a file](https://devs.put.io/llms.mdx/api/files/download-a-file/content.md): Also accepts HTTP Basic auth with an app-specific password.
  - [Download a subtitle](https://devs.put.io/llms.mdx/api/files/download-a-subtitle/content.md)
  - [Extract archives](https://devs.put.io/llms.mdx/api/files/extract-archives/content.md)
  - [Get a file](https://devs.put.io/llms.mdx/api/files/get-a-file/content.md)
  - [Get download URL](https://devs.put.io/llms.mdx/api/files/get-download-url/content.md): The returned URL contains an authentication token that is only valid from the IP address that this request is made.
  - [Get MP4 status](https://devs.put.io/llms.mdx/api/files/get-mp4-status/content.md)
  - [Get the HLS playlist](https://devs.put.io/llms.mdx/api/files/get-the-hls-playlist/content.md)
  - [Get watch position](https://devs.put.io/llms.mdx/api/files/get-watch-position/content.md)
  - [List extractions](https://devs.put.io/llms.mdx/api/files/list-extractions/content.md)
  - [List files](https://devs.put.io/llms.mdx/api/files/list-files/content.md)
  - [List more files](https://devs.put.io/llms.mdx/api/files/list-more-files/content.md)
  - [List subtitles](https://devs.put.io/llms.mdx/api/files/list-subtitles/content.md): Lists subtitles in the account subtitle languages, or in `languages` when given.
  - [More search results](https://devs.put.io/llms.mdx/api/files/more-search-results/content.md)
  - [Move files](https://devs.put.io/llms.mdx/api/files/move-files/content.md)
  - [Rename a file](https://devs.put.io/llms.mdx/api/files/rename-a-file/content.md)
  - [Search files, paged](https://devs.put.io/llms.mdx/api/files/search-files-paged/content.md)
  - [Search files](https://devs.put.io/llms.mdx/api/files/search-files/content.md)
  - [Set watch position](https://devs.put.io/llms.mdx/api/files/set-watch-position/content.md)
  - [Upload a file](https://devs.put.io/llms.mdx/api/files/upload-a-file/content.md): If the uploaded file is a torrent file, starts it as a transfer. Flag fields count only when set to the string `true`. **This endpoint must be used with `upload.put.io` domain.**
- Transfers
  - [Add a transfer](https://devs.put.io/llms.mdx/api/transfers/add-a-transfer/content.md): We may update some of the fields (e.g. name and type) after adding a transfer. You may use `/transfers/{id}` endpoint to get up-to-date values. If you want to upload a torrent file, use `/files/upload` endpoint. Requires an active plan; returns 402 otherwise.
  - [Add trackers](https://devs.put.io/llms.mdx/api/transfers/add-trackers/content.md): Requires an active plan.
  - [Add transfers](https://devs.put.io/llms.mdx/api/transfers/add-transfers/content.md): Adds each URL as a separate transfer. Duplicate and empty URLs are skipped. Failed URLs are listed in `errors`. Requires an active plan; returns 402 otherwise.
  - [Cancel transfers](https://devs.put.io/llms.mdx/api/transfers/cancel-transfers/content.md): For each transfer: a live recording stops recording (or is removed if it is already stopping), a `SEEDING` transfer stops seeding and becomes `COMPLETED`, and any other transfer entry is removed. Files are not removed. Unknown IDs are ignored.
  - [Check URLs](https://devs.put.io/llms.mdx/api/transfers/check-urls/content.md): Returns the name, size and type of each URL without adding a transfer.
  - [Clear finished](https://devs.put.io/llms.mdx/api/transfers/clear-finished/content.md): Only removes transfer entries, does not remove files.
  - [Count transfers](https://devs.put.io/llms.mdx/api/transfers/count-transfers/content.md)
  - [Download the torrent](https://devs.put.io/llms.mdx/api/transfers/download-the-torrent/content.md): Needs `transfers:read`. The download token from `GET /account/info?download_token=1` also works.
  - [Get a transfer](https://devs.put.io/llms.mdx/api/transfers/get-a-transfer/content.md)
  - [List more transfers](https://devs.put.io/llms.mdx/api/transfers/list-more-transfers/content.md)
  - [List transfers](https://devs.put.io/llms.mdx/api/transfers/list-transfers/content.md): Without `per_page`, returns your 1000 oldest transfers, oldest first. With `per_page`, pages run from newest to oldest and cover only your 10000 newest transfers. Order within a page is not guaranteed.
  - [Remove transfers](https://devs.put.io/llms.mdx/api/transfers/remove-transfers/content.md): Removes transfer entries without touching their files. Unlike `/transfers/cancel`, it does not stop seeding or recording first.
  - [Retry a transfer](https://devs.put.io/llms.mdx/api/transfers/retry-a-transfer/content.md): Only transfers in `ERROR` status can be retried. Requires an active plan.
  - [Stop a recording](https://devs.put.io/llms.mdx/api/transfers/stop-a-recording/content.md)
- Account
  - [Get account](https://devs.put.io/llms.mdx/api/account/get-account/content.md)
  - [Get settings](https://devs.put.io/llms.mdx/api/account/get-settings/content.md)
  - [List subtitle languages](https://devs.put.io/llms.mdx/api/account/list-subtitle-languages/content.md): Public-share tokens can also call this.
  - [Update settings](https://devs.put.io/llms.mdx/api/account/update-settings/content.md): Send only the settings you want to change. Booleans are the strings `true` or `false`. Changing `password` or `mail` also requires `current_password`. Only put.io's own apps can call this.
- RSS feeds
  - [Clear feed log](https://devs.put.io/llms.mdx/api/rss/clear-feed-log/content.md): Deletes the feed's item history. Items already in the feed are skipped from then on.
  - [Create a feed](https://devs.put.io/llms.mdx/api/rss/create-a-feed/content.md): Creates an RSS feed with the given parameters. The created feed object is returned. Requires an active plan; returns 402 otherwise.
  - [Delete a feed](https://devs.put.io/llms.mdx/api/rss/delete-a-feed/content.md)
  - [Get a feed](https://devs.put.io/llms.mdx/api/rss/get-a-feed/content.md)
  - [List feed items](https://devs.put.io/llms.mdx/api/rss/list-feed-items/content.md): Returns the feed and its 50 most recently updated items.
  - [List feeds](https://devs.put.io/llms.mdx/api/rss/list-feeds/content.md)
  - [Pause a feed](https://devs.put.io/llms.mdx/api/rss/pause-a-feed/content.md): Pauses the RSS feed. Paused feeds add no new transfers.
  - [Resume a feed](https://devs.put.io/llms.mdx/api/rss/resume-a-feed/content.md): Resumes the RSS feed and checks it for new items right away. Requires an active plan; returns 402 otherwise.
  - [Retry an item](https://devs.put.io/llms.mdx/api/rss/retry-an-item/content.md): Requires an active plan; returns 402 otherwise.
  - [Retry failed items](https://devs.put.io/llms.mdx/api/rss/retry-failed-items/content.md): Retries every failed item of the feed. Requires an active plan; returns 402 otherwise.
  - [Update a feed](https://devs.put.io/llms.mdx/api/rss/update-a-feed/content.md): Updates an RSS feed with the given parameters. `keyword`, `unwanted_keywords`, `delete_old_files` and `dont_process_whole_feed` are replaced on every call; send their current values to keep them. `title`, `rss_source_url` and `parent_dir_id` are kept when omitted. Requires an active plan; returns 402 otherwise.
- Shares
  - [List shared with you](https://devs.put.io/llms.mdx/api/shares/list-shared-with-you/content.md): Lists the folder of files your friends share with you. Takes the same query parameters as `/files/list`.
  - [List who has access](https://devs.put.io/llms.mdx/api/shares/list-who-has-access/content.md): Each result item contains a share id which can be used for unsharing.
  - [List your shares](https://devs.put.io/llms.mdx/api/shares/list-your-shares/content.md)
  - [Share files](https://devs.put.io/llms.mdx/api/shares/share-files/content.md): Requires an active plan; returns 402 otherwise.
  - [Unshare a file](https://devs.put.io/llms.mdx/api/shares/unshare-a-file/content.md)
- Friends
  - [Approve a request](https://devs.put.io/llms.mdx/api/friends/approve-a-request/content.md): Files each of you shares with everyone are shared with the new friend.
  - [Count requests received](https://devs.put.io/llms.mdx/api/friends/count-requests-received/content.md)
  - [Deny a request](https://devs.put.io/llms.mdx/api/friends/deny-a-request/content.md)
  - [Get a friend's folder](https://devs.put.io/llms.mdx/api/friends/get-a-friend-s-folder/content.md): Returns the virtual folder of files the friend shares with you. `file` is `null` when the friend shares nothing with you.
  - [List friends](https://devs.put.io/llms.mdx/api/friends/list-friends/content.md)
  - [List requests received](https://devs.put.io/llms.mdx/api/friends/list-requests-received/content.md)
  - [List requests sent](https://devs.put.io/llms.mdx/api/friends/list-requests-sent/content.md)
  - [Remove a friend](https://devs.put.io/llms.mdx/api/friends/remove-a-friend/content.md): Removes the friendship and every file share between you and the old friend, in both directions.
  - [Send a request](https://devs.put.io/llms.mdx/api/friends/send-a-request/content.md)
- Zips
  - [Cancel a ZIP](https://devs.put.io/llms.mdx/api/zips/cancel-a-zip/content.md): Deletes the zipping job.
  - [Create a ZIP](https://devs.put.io/llms.mdx/api/zips/create-a-zip/content.md): Starts a zipping job for up to 1000 files or folders. Send `file_ids`, `file_id` or `cursor`. Poll `/zips/{id}` with the returned `zip_id` until `zip_status` is DONE.
  - [Download as ZIP](https://devs.put.io/llms.mdx/api/zips/download-as-zip/content.md): Creates or reuses a zip of one file or folder and waits up to 8 seconds for it. Redirects to the zip URL when ready. Otherwise returns 503; retry after the `Retry-After` delay. The download token from `GET /account/info?download_token=1` also works.
  - [Get a ZIP](https://devs.put.io/llms.mdx/api/zips/get-a-zip/content.md): Returns the status of a zip job. Poll until `zip_status` is DONE, then use `url`. WAITING means you have too many active zip jobs; the job waits its turn. `missing_files` lists files left out of the zip.
  - [List ZIPs](https://devs.put.io/llms.mdx/api/zips/list-zips/content.md): Returns your unfinished zip jobs (NEW, PROCESSING or WAITING) created in the last 10 minutes.
- Events
  - [Clear events](https://devs.put.io/llms.mdx/api/events/clear-events/content.md): Deletes all of your events. Only put.io's own apps can call this.
  - [Delete an event](https://devs.put.io/llms.mdx/api/events/delete-an-event/content.md): Only put.io's own apps can call this. An `id` of `0` deletes all of your events.
  - [Download the torrent](https://devs.put.io/llms.mdx/api/events/download-the-torrent/content.md): Downloads the .torrent file of a transfer event. Needs `account:read`. The download token from `GET /account/info?download_token=1` also works.
  - [List events](https://devs.put.io/llms.mdx/api/events/list-events/content.md): Returns events newest first.
- Config
  - [Delete a value](https://devs.put.io/llms.mdx/api/config/delete-a-value/content.md): Removes the key. Returns 200 even when the key does not exist.
  - [Get a value](https://devs.put.io/llms.mdx/api/config/get-a-value/content.md): Returns `{"value": null}` when the key is not set. Returns 404 only when this app has never stored config for the user; any `PUT` or `DELETE` on a key creates it.
  - [Get config](https://devs.put.io/llms.mdx/api/config/get-config/content.md): Returns an empty object when nothing is stored.
  - [Replace config](https://devs.put.io/llms.mdx/api/config/replace-config/content.md): Replaces the whole config object. Send the complete object. Keep it under 2 KB; the server does not enforce this yet. For larger data, use `PUT /config/{key}`.
  - [Set a value](https://devs.put.io/llms.mdx/api/config/set-a-value/content.md): Sets one key. The value can be any JSON value. Form-encoded bodies store `value` as a string. Keep it under 2 KB; the server does not enforce this yet.

## Optional

- [All pages in one file](https://devs.put.io/llms-full.txt)