---
url: /developers/backend/writing-bots.md
---
# Writing Bots

For legacy documentation, please check the [Open Library Archives](https://openlibrary.org/dev/docs/bots?v=12). Most Bot code now lives at <https://github.com/internetarchive/openlibrary-bots>

## Introduction

If you encounter recurring metadata errors on Open Library editions, works, or authors; notice duplicate authors that should be merged; find fake books that should be deleted; or want to import missing books from other sources, these tasks can be handled by bot accounts.

Open Library bot accounts make HTTP POSTs to work, author, edition, and subject pages to correct metadata or create and import new records (books, authors, book covers) in bulk.

## Applying for a Bot Account

To apply for a privileged bot account:

1. [Register a new Open Library account](https://openlibrary.org/account/create) that meets these guidelines:
   * The bot account must be **separate** from your personal Open Library account.
   * The username must end with "Bot" (for example, `WorkBot`, `ImportBot`).
   * These conventions enable [filtering Recent Changes by bots](https://openlibrary.org/recentchanges#bots) to identify changes made by bot accounts. Bots perform repetitive operations at high frequency and would overwhelm the list if shown alongside human edits.
2. Open a GitHub issue and ask a site admin (for example, @mekarpeles) to grant bot privileges to your account and [add it to the "API" usergroup](http://openlibrary.org/usergroup/api?m=edit).

## Getting Started: Rules

**Q: I have written a bot. Am I ready to run it?**

If your bot script is ready, fork the <https://github.com/internetarchive/openlibrary-bots> repository, create a new branch, add a directory named according to the action your bot will perform, and submit a PR for review. Do not run bulk modifications until @mekarpeles has reviewed and approved your script, or your bot privileges may be revoked.

**Q: My bot reads metadata from a source file and modifies records on Open Library. Should these source data files be saved?**

Yes. If your bot adds new or updated metadata from files, commit those files with your script to <https://github.com/internetarchive/openlibrary-bots>.

### openlibrary-client Library

Instead of making POSTs directly to API endpoints using a `bot account`, use the official Python client library [`openlibrary-client`](https://github.com/internetarchive/openlibrary-client), which streamlines metadata updates and bot development. The older `openlibrary/api.py` library has been deprecated in favor of the easier and safer `openlibrary-client`.

* [Click here for instructions on installing and using the openlibrary-client](https://github.com/internetarchive/openlibrary-client).

### Bot Account Etiquette

Avoid using bot accounts directly for one-off changes from the command line. Instead, code changes into bot scripts and check them into the [openlibrary-bots](https://github.com/internetarchive/openlibrary-bots) repository. This allows the team to review what changes were made, debug issues, and update or re-apply logic as needed.

### Example Bots

[Here's an example by @hornc of a bot that uses openlibrary-client for merging works and editions and updating records in bulk](https://github.com/hornc/catharbot).

The following **legacy examples** used `api.py` (now deprecated) instead of openlibrary-client. They illustrate what Open Library bots do, how they are written, and how they are used. Refer to the [openlibrary-client documentation](https://github.com/internetarchive/openlibrary-client) for modern examples:

* [Daniel's IdentifierBot](http://github.com/dmontalvo/IdentifierBot/blob/master/fastadder.py)
* [Ben's Goodreads bot](https://github.com/internetarchive/openlibrary/blob/master/scripts/2010/04/import_goodreads_ids.py)
* [AMillarBot](http://openlibrary.org/people/AMillarBot)
* [oclcBot, by Bruce Washburn](http://openlibrary.org/people/oclcBot)

### Bot Opportunities

Migrated to <https://github.com/internetarchive/openlibrary/issues/2863>

Also see [Ideas for new bots](https://github.com/internetarchive/openlibrary-bots/labels/Ideas%20for%20new%20bots).