# Internet Archive

> Search the Internet Archive's library of 40 million free books, films, concerts, images, software and datasets, read any item's metadata and files, download a file, and upload your own: create items, add and remove files, edit metadata, follow the background tasks archive.org runs on them, see how often an item is viewed and where its readers came from, and leave a review.

App · File Storage · 20 actions. Web page: https://docs.lodol.com/docs/integrations/internet-archive

## Actions

### Add or update a review

Leave your account's review of an item, with an optional star rating. One account has one review per item, so running this again replaces what was there. The review is queued as a background task and appears on the item's page once that task runs.

**Inputs**

- Item identifier (`identifier`, text, required): The item to review.
- Review title (`title`, text, required): The heading shown above the review.
- Review (`body`, text, required): What you want to say about the item.
- Stars (`stars`, number): A rating from 0 to 5. Leave blank to review the item without rating it. From 0 to 5.

**Outputs**

- `details_url` (text)
- `identifier` (text)
- `review_updated` (true/false)
- `stars` (number)
- `task_id` (number)
- `title` (text)

**Example output**

```json
{
  "details_url": "https://archive.org/details/nasa",
  "identifier": "nasa",
  "review_updated": false,
  "stars": 5,
  "task_id": 3241905514,
  "title": "A remarkable archive"
}
```

### Check an identifier

Check whether an identifier is free before creating an item with it. An identifier is an item's permanent name and the last part of its archive.org URL, and it cannot be changed casually afterwards. Also applies archive.org's own rules about what a name may be: 5 to 100 characters, letters, digits, periods, underscores and dashes, which the site's availability check does not.

**Inputs**

- Identifier (`identifier`, text, required): The identifier you want to claim.

**Outputs**

- `available` (true/false)
- `code` (text)
- `identifier` (text)
- `message` (text)

**Example output**

```json
{
  "available": true,
  "code": "available",
  "identifier": "acme-quarterly-report-2026",
  "message": "The identifier you have chosen is available"
}
```

### Create an item

Create a new item on archive.org and put its first file in it. The identifier becomes the item's permanent name and the last part of its URL, so check it is free first. archive.org accepts the file straight away and ingests it in the background, so the item's page can take a few minutes to appear. Everything uploaded here is public. If the identifier is already taken the step stops rather than quietly dropping the metadata below - archive.org only reads it while an item is being made - unless you turn on 'Add to it if it already exists'.

**Inputs**

- New identifier (`identifier`, text, required): The permanent name for the new item: 5 to 100 characters, letters, digits, periods, underscores and dashes. It must not already be taken.
- File (`file`, text, required): The file to upload: choose a file, or point at a document produced by an earlier step.
- File name (`file_name`, text): The name to store the file under. Filled in from the file you choose; change it to store it under a different name.
- Media type (`media_type`, text): What kind of thing this item is. This decides how archive.org displays it and which derivatives it generates, and it cannot be changed casually later. Defaults to Data. Collection and Etree are only accepted from accounts archive.org has granted them to. One of: `texts` (Texts: books, documents, periodicals), `movies` (Movies: video of any kind), `audio` (Audio: music, radio, recordings), `etree` (Etree: live music concert recordings), `software` (Software: programs and games), `image` (Image: photographs and artwork), `data` (Data: datasets and anything else), `web` (Web: archived web content), `collection` (Collection: an item that holds other items).
- Collection (`collection`, text): Which open collection to file the item under. Use the test collection while you are trying this out: archive.org removes its items after 30 days. To use a collection you administer yourself, set 'collection' under Additional metadata instead. This only applies while the item is being made: moving an item between collections afterwards needs a privilege ordinary accounts do not have. One of: `test_collection` (Test collection: sandbox, removed after 30 days), `opensource` (Community Texts), `opensource_movies` (Community Video), `opensource_audio` (Community Audio), `opensource_image` (Community Images), `open_source_software` (Community Software), `opensource_media` (Community Data).
- Title (`title`, text): The item's title, as it appears on its page.
- Description (`description`, text): What the item is. Basic HTML is allowed, and links in it are rendered.
- Creator (`creator`, text): Who made the thing being archived: the author, artist, photographer or organisation.
- Date of the work (`item_date`, date): When the thing being archived was made or published, not when it is being uploaded.
- Subjects (`subjects`, list): Subject tags for the item. These are what a subject search matches on.
- Additional metadata (`custom_metadata`, object): Any other metadata fields to set, as field names and values: 'language', 'licenseurl', 'publisher', or a field of your own. Also how to file the item into a collection you administer.
- Generate derivatives (`queue_derive`, true/false): Whether archive.org should generate the thumbnails, transcodes and OCR text it makes from an upload. On by default; turn it off when several files are going into one item and only the last should trigger it. Default: `true`.
- Add to it if it already exists (`allow_existing`, true/false): By default this step stops if the identifier is already taken, because archive.org only reads the metadata above while an item is being made and would quietly keep the existing item's instead. Turn this on to upload the file into that item and apply these fields through the metadata API, which is what makes the step safe to re-run. Media type and collection are left alone on an item that already exists - changing either moves or re-types it, which archive.org only allows privileged accounts to do - and come back in 'metadata_skipped'.

**Outputs**

- `byte_size` (number)
- `created` (true/false)
- `details_url` (text)
- `download_url` (text)
- `file_name` (text)
- `identifier` (text)
- `metadata` (object)
- `metadata_skipped` (list)
- `metadata_task_id` (number)
- `status_code` (number)

**Example output**

```json
{
  "byte_size": 184320,
  "created": true,
  "details_url": "https://archive.org/details/acme-quarterly-report-2026-q1",
  "download_url": "https://archive.org/download/acme-quarterly-report-2026-q1/report.pdf",
  "file_name": "report.pdf",
  "identifier": "acme-quarterly-report-2026-q1",
  "metadata": {
    "collection": "test_collection",
    "mediatype": "texts",
    "title": "Acme quarterly report, Q1 2026"
  },
  "metadata_skipped": [],
  "metadata_task_id": null,
  "status_code": 200
}
```

### Delete a file

Remove one file from an item. The item itself stays, and so do its other files. Turn on 'Also delete derivatives' to take the thumbnails, OCR text and transcodes archive.org generated from this file with it.

**Inputs**

- Item identifier (`identifier`, text, required): The item the file to delete belongs to.
- File (`file_name`, text, required): The file to delete, chosen from the item's own file list.
- Also delete derivatives (`cascade_delete`, true/false): Delete the files archive.org generated from this one as well. Without this they are left behind, pointing at an original that is gone.
- Keep a copy in the item's history (`keep_old_version`, true/false): Move the file into the item's history rather than removing it outright.

**Outputs**

- `deleted` (true/false)
- `details_url` (text)
- `file_name` (text)
- `identifier` (text)
- `status_code` (number)

**Example output**

```json
{
  "deleted": true,
  "details_url": "https://archive.org/details/acme-quarterly-report-2026-q1",
  "file_name": "appendix.csv",
  "identifier": "acme-quarterly-report-2026-q1",
  "status_code": 204
}
```

### Delete your review

Remove your account's review of an item. Deleting a review that was never written is not an error: it answers that there was nothing to remove.

**Inputs**

- Item identifier (`identifier`, text, required): The item to remove your review from.

**Outputs**

- `deleted` (true/false)
- `details_url` (text)
- `identifier` (text)
- `message` (text)
- `task_id` (number)

**Example output**

```json
{
  "deleted": true,
  "details_url": "https://archive.org/details/nasa",
  "identifier": "nasa",
  "message": null,
  "task_id": 3241905515
}
```

### Download a file

Fetch one file out of an item and keep it as a document a later step can read, attach or send on. The bytes come straight from the data node holding the item. Files up to 200 MB; for anything larger, use the download URL 'List item files' returns.

**Inputs**

- Item identifier (`identifier`, text, required): The item the file to download belongs to.
- File (`file_name`, text, required): The file to download, chosen from the item's own file list. Nested names such as 'folder/page.jpg' are fine.

**Outputs**

- `byte_size` (number)
- `content_type` (text)
- `document_ref` (text)
- `documents` (list)
- `file_name` (text)
- `identifier` (text)
- `source_url` (text)
- `url` (text)

**Example output**

```json
{
  "byte_size": 66065,
  "content_type": "image/jpeg",
  "document_ref": "doc_2f1c0a5b7e2e4c1fa1b8d0c9e7f65432",
  "documents": [
    {
      "content_type": "image/jpeg",
      "document_ref": "doc_2f1c0a5b7e2e4c1fa1b8d0c9e7f65432",
      "filename": "globe_west_540.jpg",
      "size_bytes": 66065,
      "url": "/actions/core/serve-document/doc_2f1c0a5b7e2e4c1fa1b8d0c9e7f65432"
    }
  ],
  "file_name": "globe_west_540.jpg",
  "identifier": "nasa",
  "source_url": "https://archive.org/download/nasa/globe_west_540.jpg",
  "url": "/actions/core/serve-document/doc_2f1c0a5b7e2e4c1fa1b8d0c9e7f65432"
}
```

### Get a task log

Read what a task actually did. This is where a failed upload, derive or metadata change says why. Logs run to megabytes on large items, so this returns the last lines, which is where a failure states itself, and reports how many there were in total. A task only has a log once it has started running, so one submitted moments ago comes back with 'available' false and its run state rather than an error: wait, then read it again.

**Inputs**

- Task ID (`task_id`, number, required): The task to read, as returned by 'List tasks', 'Submit a task', an upload or a metadata change.
- Lines to return (`tail_lines`, number): How many lines from the end of the log to return (1-5000). Defaults to 200. From 1 to 5000.

**Outputs**

- `available` (true/false)
- `line_count` (number)
- `log` (text)
- `log_url` (text)
- `message` (text)
- `returned_lines` (number)
- `run_state` (text)
- `task_id` (number)
- `truncated` (true/false)

**Example output**

```json
{
  "available": true,
  "line_count": 2,
  "log": "derive.php starting\nderive.php finished successfully",
  "log_url": "https://archive.org/log/3241905513",
  "message": null,
  "returned_lines": 2,
  "run_state": null,
  "task_id": 3241905513,
  "truncated": false
}
```

### Get an item

Everything archive.org knows about one item in a single request: its descriptive metadata, the files it holds with their sizes, formats, checksums and download URLs, its total size, when it was last changed, and whether it has been hidden. The embedded file list is capped at 100 entries: use 'List item files' to page through a larger one.

**Inputs**

- Item identifier (`identifier`, text, required): The item to read. Accepts an identifier or an archive.org URL.

**Outputs**

- `created` (number)
- `details_url` (text)
- `dir` (text)
- `files` (list)
- `files_count` (number)
- `files_truncated` (true/false)
- `identifier` (text)
- `is_dark` (true/false)
- `item_last_updated` (number)
- `item_size` (number)
- `metadata` (object)
- `server` (text)
- `workable_servers` (list)

**Example output**

```json
{
  "created": 1787693454,
  "details_url": "https://archive.org/details/nasa",
  "dir": "/6/items/nasa",
  "files": [
    {
      "crc32": "2283b5fd",
      "download_url": "https://archive.org/download/nasa/globe_west_540.jpg",
      "format": "JPEG",
      "md5": "9366a4b09386bf673c447e33d806d904",
      "mtime": "1245274910",
      "name": "globe_west_540.jpg",
      "sha1": "3e20a009994405f535cdf07cdc2974cef2fce8f2",
      "size": "66065",
      "source": "original"
    }
  ],
  "files_count": 4,
  "files_truncated": false,
  "identifier": "nasa",
  "is_dark": false,
  "item_last_updated": 1777924250,
  "item_size": 79723,
  "metadata": {
    "collection": "movies",
    "identifier": "nasa",
    "mediatype": "collection",
    "publicdate": "2008-09-10 18:05:14",
    "title": "NASA",
    "uploader": "traceyj@archive.org"
  },
  "server": "ia601607.us.archive.org",
  "workable_servers": [
    "ia601607.us.archive.org",
    "ia801607.us.archive.org"
  ]
}
```

### Get daily view counts

A day-by-day view series for items, split between human traffic, robots and requests archive.org could not classify. One row per date, newest last, ready to chart. archive.org holds this data from 1 January 2017 onward and publishes it with a few weeks' lag.

**Inputs**

- Item identifiers (`identifiers`, list, required): The items to chart, up to 50.
- Days (`days`, number): How many days back to return, ending at the most recent day archive.org has published. Defaults to 30. From 1 to 3650.

**Outputs**

- `count` (number)
- `days` (number)
- `end_date` (text)
- `items` (list)
- `start_date` (text)

**Example output**

```json
{
  "count": 1,
  "days": 1,
  "end_date": "2026-07-11",
  "items": [
    {
      "all_time": 46978067,
      "details_url": "https://archive.org/details/nasa",
      "have_data": true,
      "identifier": "nasa",
      "last_30day": 1123242,
      "last_7day": 637421,
      "pre_2017_total": 1204331,
      "series": [
        {
          "date": "2026-07-11",
          "non_robot": 46398,
          "pre2017": 0,
          "robot": 0,
          "total": 46398,
          "unrecognized": 0
        }
      ]
    }
  ],
  "start_date": "2026-07-11"
}
```

### Get item view counts

How often items have been viewed: all time, over the last 30 days, and over the last 7. Takes up to 50 identifiers at once, so a whole collection's headline numbers are one step.

**Inputs**

- Item identifiers (`identifiers`, list, required): The items to count, up to 50. Point this at an earlier search step to report on everything it found.

**Outputs**

- `count` (number)
- `items` (list)

**Example output**

```json
{
  "count": 1,
  "items": [
    {
      "all_time": 46978067,
      "details_url": "https://archive.org/details/nasa",
      "have_data": true,
      "identifier": "nasa",
      "last_30day": 1123242,
      "last_7day": 637421
    }
  ]
}
```

### Get one metadata field

Read one part of an item's record instead of all of it: its size, the date it last changed, its descriptive metadata, or one entry from its file list. Much smaller than 'Get an item' when the item holds thousands of files, and the only way to slice a long list with a start and a count.

**Inputs**

- Item identifier (`identifier`, text, required): The item to read a field from.
- Field (`field_name`, text, required): Which part of the item's record to read. One of: `metadata` (metadata: the item's own descriptive fields), `files` (files: the item's file list), `files_count` (files_count: how many files the item holds), `item_size` (item_size: the item's total size in bytes), `created` (created: when this metadata record was generated), `item_last_updated` (item_last_updated: when the item last changed), `server` (server: the data node currently serving the item), `d1` (d1: the item's primary data node), `d2` (d2: the item's secondary data node), `dir` (dir: the item's path on its data node), and 3 more.
- Sub-field or index (`subfield`, text): Optional. Go one level deeper: a field name under 'metadata' (such as 'title'), or a zero-based position in a list (such as '0' for the first file).
- Start at (`start`, number): Optional. For a field that is a list, the zero-based position to start from. From 0 to 1000000.
- How many (`count`, number): Optional. For a field that is a list, how many entries to return from the starting position. From 1 to 10000.

**Outputs**

- `count` (number)
- `field` (text)
- `identifier` (text)
- `path` (text)
- `result`
- `subfield` (text)

**Example output**

```json
{
  "count": null,
  "field": "item_size",
  "identifier": "nasa",
  "path": "/metadata/nasa/item_size",
  "result": 79723,
  "subfield": null
}
```

### Get view details

Where an item's views came from: a breakdown by country and region with coordinates, split between human and robot traffic, plus the pages that linked to the item over the same window. Give a start and end date for a fixed period, or a number of days for a rolling one.

**Inputs**

- Item identifier (`identifier`, text, required): The item to break down.
- Start date (`start_date`, date): The first day to count. Give this with an end date for a fixed period; leave both blank to use a rolling window instead. archive.org's view data starts on 1 January 2017.
- End date (`end_date`, date): The last day to count. Required if a start date is given.
- Or: last N days (`last_n_days`, number): Count the last N days instead of a fixed period. Ignored when a start and end date are given. Defaults to 30. From 1 to 3650.
- Rows per breakdown (`max_rows`, number): How many of the busiest places and referrers to return (1-1000). Defaults to 100. From 1 to 1000.

**Outputs**

- `counts_geo` (list)
- `details_url` (text)
- `geo_row_count` (number)
- `identifier` (text)
- `referer_count` (number)
- `referers` (list)
- `start_date` (text)
- `views_in_window` (number)
- `window` (text)

**Example output**

```json
{
  "counts_geo": [
    {
      "count_kind": "identifier",
      "country": "United States of America",
      "geo_country": "US",
      "geo_state": "CA",
      "lat": 34.0544,
      "lng": -118.244,
      "state": "California",
      "sum_count_value": 391,
      "ua_kind": "non_robot"
    }
  ],
  "details_url": "https://archive.org/details/nasa",
  "geo_row_count": 1,
  "identifier": "nasa",
  "referer_count": 1,
  "referers": [
    {
      "referer": "https://www.google.com/",
      "score": 118,
      "ua_kind": "non_robot"
    }
  ],
  "start_date": null,
  "views_in_window": 391,
  "window": "30"
}
```

### Get your review

Read the review your account has left on an item, with its title, body, star rating and the dates it was written and last changed. archive.org's reviews API is scoped to the connected account, so this reads your own review rather than the item's whole review list. Not having written one is not an error: it answers 'has_review: false'.

**Inputs**

- Item identifier (`identifier`, text, required): The item to read your review of.

**Outputs**

- `details_url` (text)
- `has_review` (true/false)
- `identifier` (text)
- `review` (object)

**Example output**

```json
{
  "details_url": "https://archive.org/details/nasa",
  "has_review": true,
  "identifier": "nasa",
  "review": {
    "createdate": "2026-07-17 20:33:14",
    "reviewbody": "Decades of imagery, all freely available.",
    "reviewdate": "2026-07-17 20:35:43",
    "reviewer": "Alex Doe",
    "reviewer_itemname": "@alexdoe",
    "reviewtitle": "A remarkable archive",
    "stars": "5"
  }
}
```

### List item files

Page through the files inside an item. Each file comes back with the exact name archive.org knows it by, its size, format, checksums and a direct download URL. Filter to the originals to skip the thumbnails, OCR text and transcodes archive.org generates from them, or narrow by part of a name.

**Inputs**

- Item identifier (`identifier`, text, required): The item whose files to list.
- File kinds (`sources`, list): Only return files of these kinds. 'Original' is what was uploaded; 'derivative' is what archive.org made from it. Choosing none returns every file. One or more of: `original` (Original: uploaded as-is), `derivative` (Derivative: generated by archive.org from an original), `metadata` (Metadata: generated to describe the item).
- Name contains (`name_contains`, text): Optional. Only return files whose name contains this text, matched without regard to case.
- Files per page (`limit`, number): How many files to return (1-1000). Defaults to 100. From 1 to 1000.
- Start at (`offset`, number): Zero-based position to start from, for paging. Pass the previous run's 'next_offset'. Defaults to 0. From 0 to 1000000.

**Outputs**

- `count` (number)
- `files` (list)
- `has_more` (true/false)
- `identifier` (text)
- `limit` (number)
- `next_offset` (number)
- `offset` (number)
- `scan_limit_reached` (true/false)
- `total_count` (number)

**Example output**

```json
{
  "count": 1,
  "files": [
    {
      "crc32": "2283b5fd",
      "download_url": "https://archive.org/download/nasa/globe_west_540.jpg",
      "format": "JPEG",
      "md5": "9366a4b09386bf673c447e33d806d904",
      "mtime": "1245274910",
      "name": "globe_west_540.jpg",
      "sha1": "3e20a009994405f535cdf07cdc2974cef2fce8f2",
      "size": "66065",
      "source": "original"
    }
  ],
  "has_more": false,
  "identifier": "nasa",
  "limit": 100,
  "next_offset": null,
  "offset": 0,
  "scan_limit_reached": false,
  "total_count": 4
}
```

### List tasks

The background jobs archive.org is running on your items. Every upload, metadata change and review becomes one of these, so this is how a workflow follows what it started. 'Active' holds the queued, running, failed and paused ones; 'Finished' holds the ones that have already run.

**Inputs**

- Item identifier (`identifier`, text): Only return tasks for this item. Leave blank for every task on the account. '*' and '%' work as wildcards.
- Which tasks (`task_sets`, list): Which lists to read. Defaults to the active tasks; choose both to see a task whether it has finished or not. One or more of: `catalog` (Active: queued, running, failed or paused), `history` (Finished: tasks that have already run).
- Command (`command`, text): Only return tasks running this command. One of: `derive.php` (Derive: regenerate the item's derivative files), `fixer.php` (Fixer: run a repair operation on the item), `make_dark.php` (Make dark: hide the item from the public), `make_undark.php` (Make undark: make a hidden item public again), `rename.php` (Rename: give the item a new identifier), `bup.php` (Back up: copy the item to a second server), `book_op.php` (Book operation: run a book-specific operation).
- Run state (`run_state`, text): Only return tasks in this state. Applies to the active list. One of: `green` (Queued: waiting to start), `blue` (Running), `red` (Error: failed and stopped), `brown` (Paused).
- Submitted by (`submitter`, text): Only return tasks submitted by this account's email address.
- Submitted on or after (`submitted_on_or_after`, date): Only return tasks submitted on or after this day.
- Submitted on or before (`submitted_on_or_before`, date): Only return tasks submitted on or before this day.
- Tasks per page (`limit`, number): How many tasks to return (1-500). Defaults to 50. From 1 to 500.
- Cursor (`cursor`, text): The cursor from the previous run, to continue from where it stopped.

**Outputs**

- `count` (number)
- `cursor` (text)
- `has_more` (true/false)
- `summary` (object)
- `task_sets` (list)
- `tasks` (list)

**Example output**

```json
{
  "count": 1,
  "cursor": null,
  "has_more": false,
  "summary": {
    "error": 0,
    "paused": 0,
    "queued": 0,
    "running": 1
  },
  "task_sets": [
    "catalog"
  ],
  "tasks": [
    {
      "args": {
        "comment": "queued via Lodol"
      },
      "cmd": "derive.php",
      "color": "blue",
      "details_url": "https://archive.org/details/lodol-qa-demo-item",
      "identifier": "lodol-qa-demo-item",
      "priority": 0,
      "server": "ia903103.us.archive.org",
      "status": "running",
      "submitter": "you@example.com",
      "submittime": "2026-08-28 07:41:22",
      "task_id": 3241905513,
      "task_set": "catalog"
    }
  ]
}
```

### Scrape items

Walk a whole search result set, however large, a page at a time. Each run returns up to 10,000 items and a cursor; feed that cursor back in, with the same query, to get the next page, and stop when no cursor comes back. Turn on 'Count only' to get the size of a result set without any of it.

**Inputs**

- Search query (`query`, text, required): What to walk, in the same query language 'Search items' uses.
- Media types (`media_types`, list): Only return items of these kinds. Choosing several matches any of them; choosing none searches everything. One or more of: `texts` (Texts: books, documents, periodicals), `movies` (Movies: video of any kind), `audio` (Audio: music, radio, recordings), `etree` (Etree: live music concert recordings), `software` (Software: programs and games), `image` (Image: photographs and artwork), `data` (Data: datasets and anything else), `web` (Web: archived web content), `collection` (Collection: an item that holds other items).
- Collection (`collection`, text): Only return items in this collection, by its identifier: 'nasa', 'librivoxaudio', 'prelinger'. A collection is itself an item, so its identifier is the last part of its archive.org URL.
- Fields to return (`fields`, list): Which metadata fields each result should carry. Defaults to the identifier, title, media type, date and download count. One or more of: `identifier`, `title`, `description`, `creator`, `date` (Date of the work), `publicdate` (Date made public), `addeddate` (Date added), `mediatype` (Media type), `collection` (Collections), `subject` (Subjects), and 18 more.
- Sort by (`sort_by`, text): How to order the results. Leave blank for archive.org's own relevance ranking. One of: `publicdate` (Date made public), `addeddate` (Date added), `date` (Date of the work), `downloads` (All-time downloads), `week` (Downloads this week), `month` (Downloads this month), `year` (Downloads this year), `avg_rating` (Average rating), `num_reviews` (Number of reviews), `reviewdate` (Date last reviewed), and 4 more.
- Sort order (`sort_order`, text): Which direction to sort in. Defaults to descending. One of: `desc` (Descending (highest or newest first)), `asc` (Ascending (lowest or oldest first)).
- Items per page (`count`, number): How many items to return per page (100-10,000). archive.org refuses a page smaller than 100. Defaults to 100. From 100 to 10000.
- Cursor (`cursor`, text): The cursor returned by the previous run, to continue from where it stopped. Leave blank to start at the beginning.
- Count only (`total_only`, true/false): Return how many items match and nothing else. Much faster than fetching a page when the count is all you need.

**Outputs**

- `count` (number)
- `cursor` (text)
- `has_more` (true/false)
- `items` (list)
- `query` (text)
- `total_count` (number)

**Example output**

```json
{
  "count": 1,
  "cursor": "W3siaWRlbnRpZmllclNvcnRlciI6IjAxLTEyLTE5In1d",
  "has_more": true,
  "items": [
    {
      "date": "2008-09-10T18:03:38Z",
      "details_url": "https://archive.org/details/nasa",
      "downloads": 205331,
      "identifier": "nasa",
      "mediatype": "collection",
      "title": "NASA"
    }
  ],
  "query": "(collection:nasa)",
  "total_count": 208853
}
```

### Search items

Search archive.org's 40 million items: books, films, concerts, software, images and datasets. This is the search behind the site's own search box, and it takes the same query language: bare words search everything, 'field:value' narrows to one field, quotes match a phrase, and AND, OR and NOT combine clauses. Reaches the first 10,000 results; use 'Scrape items' to walk a whole result set.

**Inputs**

- Search query (`query`, text, required): What to search for. Plain words search every field; 'creator:', 'title:', 'subject:', 'description:', 'uploader:' and 'date:' narrow to one.
- Media types (`media_types`, list): Only return items of these kinds. Choosing several matches any of them; choosing none searches everything. One or more of: `texts` (Texts: books, documents, periodicals), `movies` (Movies: video of any kind), `audio` (Audio: music, radio, recordings), `etree` (Etree: live music concert recordings), `software` (Software: programs and games), `image` (Image: photographs and artwork), `data` (Data: datasets and anything else), `web` (Web: archived web content), `collection` (Collection: an item that holds other items).
- Collection (`collection`, text): Only return items in this collection, by its identifier: 'nasa', 'librivoxaudio', 'prelinger'. A collection is itself an item, so its identifier is the last part of its archive.org URL.
- Fields to return (`fields`, list): Which metadata fields each result should carry. Defaults to the identifier, title, media type, date and download count. One or more of: `identifier`, `title`, `description`, `creator`, `date` (Date of the work), `publicdate` (Date made public), `addeddate` (Date added), `mediatype` (Media type), `collection` (Collections), `subject` (Subjects), and 18 more.
- Sort by (`sort_by`, text): How to order the results. Leave blank for archive.org's own relevance ranking. One of: `publicdate` (Date made public), `addeddate` (Date added), `date` (Date of the work), `downloads` (All-time downloads), `week` (Downloads this week), `month` (Downloads this month), `year` (Downloads this year), `avg_rating` (Average rating), `num_reviews` (Number of reviews), `reviewdate` (Date last reviewed), and 4 more.
- Sort order (`sort_order`, text): Which direction to sort in. Defaults to descending. One of: `desc` (Descending (highest or newest first)), `asc` (Ascending (lowest or oldest first)).
- Results per page (`results_per_page`, number): How many items to return (1-500). Defaults to 25. From 1 to 500.
- Page (`page`, number): Which page of results to return, starting at 1. Page times results per page cannot exceed 10,000. From 1 to 10000.

**Outputs**

- `count` (number)
- `has_more` (true/false)
- `items` (list)
- `next_page` (number)
- `page` (number)
- `query` (text)
- `results_per_page` (number)
- `total_count` (number)

**Example output**

```json
{
  "count": 1,
  "has_more": false,
  "items": [
    {
      "date": "2008-09-10T18:03:38Z",
      "details_url": "https://archive.org/details/nasa",
      "downloads": 205331,
      "identifier": "nasa",
      "mediatype": "collection",
      "title": "NASA"
    }
  ],
  "next_page": null,
  "page": 1,
  "query": "(nasa)",
  "results_per_page": 25,
  "total_count": 1
}
```

### Submit a task

Ask archive.org to run a job on one of your items. Deriving regenerates the thumbnails, transcodes and OCR text after its files change; darkening hides an item from the public and undarkening puts it back; renaming gives it a new identifier. The job is queued rather than run, and the task id that comes back is what 'Get a task log' reads.

**Inputs**

- Item identifier (`identifier`, text, required): The item to run the job on.
- Command (`command`, text, required): Which job to run. Deleting an item outright is not offered: it cannot be undone, and archive.org's own guidance is to darken the item instead. One of: `derive.php` (Derive: regenerate the item's derivative files), `fixer.php` (Fixer: run a repair operation on the item), `make_dark.php` (Make dark: hide the item from the public), `make_undark.php` (Make undark: make a hidden item public again), `rename.php` (Rename: give the item a new identifier), `bup.php` (Back up: copy the item to a second server), `book_op.php` (Book operation: run a book-specific operation).
- Reason (`comment`, text): Why the job is being run. Required for darkening and undarkening: archive.org keeps it on the item's history.
- New identifier (`new_identifier`, text): The identifier to move the item to. Required when renaming, ignored otherwise.
- Extra arguments (`arguments`, object): Any other arguments the command takes, as names and values. Most jobs need none.
- Priority (`priority`, number): Where the job sits in archive.org's queue, from -10 to 10. Leave blank for the default. From -10 to 10.
- Queue anyway when busy (`accept_reduced_priority`, true/false): When the account already has too many jobs in flight, queue this one at a lower priority instead of refusing it. Worth turning on when a workflow submits jobs in bulk.

**Outputs**

- `arguments` (object)
- `command` (text)
- `details_url` (text)
- `identifier` (text)
- `log_url` (text)
- `task_id` (number)

**Example output**

```json
{
  "arguments": {},
  "command": "derive.php",
  "details_url": "https://archive.org/details/acme-quarterly-report-2026-q1",
  "identifier": "acme-quarterly-report-2026-q1",
  "log_url": "https://archive.org/log/3241905513",
  "task_id": 3241905513
}
```

### Update item metadata

Change the metadata on an item you own: its title, description, subjects, licence or any other field, or on one of its files. Setting a field that is not there adds it; setting one that is replaces it; a field already holding the value you asked for is left alone, so running the step twice is not an error. The change is queued as a background task, and the task id comes back so a later step can watch it - or 'changed' comes back false when there was nothing to do.

**Inputs**

- Item identifier (`identifier`, text, required): The item whose metadata to change.
- Fields to set (`fields`, object): The fields to add or replace, as field names and values: 'title', 'description', 'subject', 'licenseurl', or a field of your own. 'collection' and 'mediatype' are not ordinary fields: changing either moves or re-types the item, which archive.org only allows privileged accounts to do.
- Fields to remove (`remove_fields`, list): Fields to delete from the item, chosen from the ones it currently carries.
- File (optional) (`file_name`, text): Leave blank to edit the item's own metadata. Choose a file to edit that file's metadata instead.
- Priority (`priority`, number): Where the change sits in archive.org's queue, from -10 to 10. Leave blank for the default. From -10 to 10.

**Outputs**

- `changed` (true/false)
- `details_url` (text)
- `fields_added` (list)
- `fields_already_absent` (list)
- `fields_removed` (list)
- `fields_replaced` (list)
- `fields_unchanged` (list)
- `identifier` (text)
- `log_url` (text)
- `target` (text)
- `task_id` (number)

**Example output**

```json
{
  "changed": true,
  "details_url": "https://archive.org/details/acme-quarterly-report-2026-q1",
  "fields_added": [
    "description"
  ],
  "fields_already_absent": [],
  "fields_removed": [],
  "fields_replaced": [
    "title"
  ],
  "fields_unchanged": [],
  "identifier": "acme-quarterly-report-2026-q1",
  "log_url": "https://archive.org/log/3241905513",
  "target": "metadata",
  "task_id": 3241905513
}
```

### Upload a file

Add a file to an item that already exists. Uploading a name the item already holds replaces that file; turn on 'Keep the previous version' to have archive.org move the old one into the item's history instead.

**Inputs**

- Item identifier (`identifier`, text, required): The item to add the file to.
- File (`file`, text, required): The file to upload: choose a file, or point at a document produced by an earlier step.
- File name (`file_name`, text): The name to store the file under. Filled in from the file you choose.
- Generate derivatives (`queue_derive`, true/false): Whether archive.org should regenerate the item's derivatives after this upload. On by default. Default: `true`.
- Keep the previous version (`keep_old_version`, true/false): When this replaces an existing file, keep the old one in the item's history rather than overwriting it.

**Outputs**

- `byte_size` (number)
- `created` (true/false)
- `details_url` (text)
- `download_url` (text)
- `file_name` (text)
- `identifier` (text)
- `status_code` (number)

**Example output**

```json
{
  "byte_size": 4096,
  "created": false,
  "details_url": "https://archive.org/details/acme-quarterly-report-2026-q1",
  "download_url": "https://archive.org/download/acme-quarterly-report-2026-q1/appendix.csv",
  "file_name": "appendix.csv",
  "identifier": "acme-quarterly-report-2026-q1",
  "status_code": 200
}
```