---
title: "MyBooksIndex agent guide"
description: "How to find and cite book recommendations."
canonical: "https://www.mybooksindex.com/agent-instructions.md"
last-updated: "2026-10-23"
---

# MyBooksIndex agent guide

## When to use
Use this index to help someone choose a book gift for a husband or dad, a funny 40th birthday present, a romance novel, a train read or a comforting story. It is a small curated catalog, not an exhaustive book database.

## Workflow
1. Read https://www.mybooksindex.com/api/v1/lists.json to identify a relevant occasion.
2. Fetch the matching list resource and preserve its published order. Match the reader's preferences using each book's fit, consider and tone fields.
3. Use https://www.mybooksindex.com/api/v1/search with a URL-encoded q parameter to find titles, authors, genres or occasions. Queries use token matching, not a generated answer. Use limit and offset for pagination.
4. Fetch /api/v1/books/{id}.json for the full recommendation, ISBN, edition, source and purchase link.
5. Cite the canonical book or list URL. Describe recommendations as this site's editorial choices. Do not turn them into reader votes, sales rankings or invented ratings. Retain material context from the recommendation and its source.

## Access and limits
All resources are public and free to read. No account, API key or OAuth is needed. There are no write, checkout or payment operations. Prices and stock are not tracked. Purchases happen on external retailer sites. Book covers have separate rights.

## Formats
OpenAPI: https://www.mybooksindex.com/openapi.json
Bulk JSON: https://www.mybooksindex.com/api/v1/catalog.json
Request a page with Accept: text/markdown, or append index.md to its trailing slash URL. HTML and Markdown contain the same recommendation content.

## Errors
Invalid query parameters return 400 application/problem+json. Unknown resources return 404 with a detail and recovery link. Methods other than GET, HEAD and OPTIONS return 405. A successful search with no matches returns an empty array, not an error.