{
  "openapi": "3.1.0",
  "info": {
    "title": "Library book price comparison API",
    "version": "1.0.0",
    "summary": "Find books by title, author, or ISBN and compare used & new prices.",
    "description": "Free, keyless, CORS-enabled. 60 requests/minute per IP; uncached lookups share a small budget, so prefer cached responses and back off on 429/503. Amounts are integer US cents including shipping to the US. Some links are affiliate links: if you buy through them I may earn a commission, at no extra cost to you. Prices and availability change; check the seller before you buy.",
    "contact": {
      "name": "Library",
      "url": "https://library.mncoleman.com/book-prices",
      "email": "library@mncoleman.com"
    },
    "termsOfService": "https://mncoleman.com/terms/#library"
  },
  "servers": [
    {
      "url": "https://library.mncoleman.com/api/v1"
    }
  ],
  "externalDocs": {
    "description": "Agent notes (llms-full.txt)",
    "url": "https://library.mncoleman.com/llms-full.txt"
  },
  "paths": {
    "/books/search": {
      "get": {
        "operationId": "searchBooks",
        "summary": "Search books by title, author, or ISBN",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 2,
              "maxLength": 120
            },
            "example": "the hobbit"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 20,
              "default": 10
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Matching editions (only ones with an ISBN-13)",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited (see Retry-After)",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "502": {
            "description": "Upstream catalogs unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/books/{isbn}": {
      "get": {
        "operationId": "getBook",
        "summary": "Book metadata and the cached price summary",
        "parameters": [
          {
            "name": "isbn",
            "in": "path",
            "required": true,
            "description": "ISBN-10 or ISBN-13 (hyphens allowed)",
            "schema": {
              "type": "string",
              "example": "9780547928227"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The book",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BookResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Unknown ISBN",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited (see Retry-After)",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Busy; retry after Retry-After seconds",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/books/{isbn}/prices": {
      "get": {
        "operationId": "getBookPrices",
        "summary": "All offers (cheapest first) with seller links, plus used/new summaries",
        "parameters": [
          {
            "name": "isbn",
            "in": "path",
            "required": true,
            "description": "ISBN-10 or ISBN-13 (hyphens allowed)",
            "schema": {
              "type": "string",
              "example": "9780547928227"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Prices",
            "headers": {
              "X-RateLimit-Limit": {
                "schema": {
                  "type": "integer"
                }
              },
              "X-RateLimit-Remaining": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Prices"
                }
              }
            }
          },
          "400": {
            "description": "Invalid input",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Unknown ISBN",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Rate limited (see Retry-After)",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Busy; retry after Retry-After seconds",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/books/{isbn}/cover": {
      "get": {
        "operationId": "getBookCover",
        "summary": "Cover image",
        "parameters": [
          {
            "name": "isbn",
            "in": "path",
            "required": true,
            "description": "ISBN-10 or ISBN-13 (hyphens allowed)",
            "schema": {
              "type": "string",
              "example": "9780547928227"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Image",
            "content": {
              "image/jpeg": {},
              "image/png": {},
              "image/webp": {}
            }
          },
          "404": {
            "description": "No cover"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          }
        }
      },
      "SearchHit": {
        "type": "object",
        "required": [
          "isbn13",
          "title",
          "authors",
          "url",
          "bookUrl",
          "pricesUrl"
        ],
        "properties": {
          "isbn13": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "subtitle": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "authors": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "year": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "publisher": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Human-readable page"
          },
          "bookUrl": {
            "type": "string",
            "format": "uri"
          },
          "pricesUrl": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "required": [
          "query",
          "limited",
          "results"
        ],
        "properties": {
          "query": {
            "type": "string"
          },
          "limited": {
            "type": "boolean",
            "description": "True when the search wasn't cached and the upstream budget was spent"
          },
          "results": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SearchHit"
            }
          }
        }
      },
      "Book": {
        "type": "object",
        "required": [
          "isbn13",
          "title",
          "authors",
          "url",
          "pricesUrl"
        ],
        "properties": {
          "isbn13": {
            "type": "string"
          },
          "isbn10": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "title": {
            "type": "string"
          },
          "subtitle": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "authors": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "publisher": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "publishDate": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "year": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "pages": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "description": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "subjects": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "coverUrl": {
            "anyOf": [
              {
                "type": "string",
                "format": "uri"
              },
              {
                "type": "null"
              }
            ]
          },
          "pricesUrl": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "BookResponse": {
        "type": "object",
        "required": [
          "book",
          "prices"
        ],
        "properties": {
          "book": {
            "$ref": "#/components/schemas/Book"
          },
          "prices": {
            "anyOf": [
              {
                "type": "object",
                "properties": {
                  "asOf": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "stale": {
                    "type": "boolean"
                  },
                  "usedLowestCents": {
                    "anyOf": [
                      {
                        "type": "integer",
                        "description": "US cents, shipping to the US included where noted"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "usedMedianCents": {
                    "anyOf": [
                      {
                        "type": "integer",
                        "description": "US cents, shipping to the US included where noted"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "usedOffers": {
                    "type": "integer"
                  },
                  "newLowestCents": {
                    "anyOf": [
                      {
                        "type": "integer",
                        "description": "US cents, shipping to the US included where noted"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "newMedianCents": {
                    "anyOf": [
                      {
                        "type": "integer",
                        "description": "US cents, shipping to the US included where noted"
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "newOffers": {
                    "type": "integer"
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "ConditionSummary": {
        "type": "object",
        "properties": {
          "count": {
            "type": "integer"
          },
          "lowestCents": {
            "anyOf": [
              {
                "type": "integer",
                "description": "US cents, shipping to the US included where noted"
              },
              {
                "type": "null"
              }
            ]
          },
          "medianCents": {
            "anyOf": [
              {
                "type": "integer",
                "description": "US cents, shipping to the US included where noted"
              },
              {
                "type": "null"
              }
            ]
          },
          "lowestUrl": {
            "anyOf": [
              {
                "type": "string",
                "format": "uri"
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "Offer": {
        "type": "object",
        "required": [
          "source",
          "condition",
          "priceCents",
          "shippingCents",
          "totalCents"
        ],
        "properties": {
          "source": {
            "type": "string",
            "enum": [
              "booksrun",
              "abebooks",
              "openlibrary"
            ]
          },
          "sourceName": {
            "type": "string"
          },
          "condition": {
            "type": "string",
            "enum": [
              "new",
              "used"
            ]
          },
          "conditionNote": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "seller": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "priceCents": {
            "type": "integer",
            "description": "US cents, shipping to the US included where noted"
          },
          "shippingCents": {
            "type": "integer",
            "description": "US cents, shipping to the US included where noted"
          },
          "totalCents": {
            "type": "integer",
            "description": "US cents, shipping to the US included where noted"
          },
          "url": {
            "anyOf": [
              {
                "type": "string",
                "format": "uri"
              },
              {
                "type": "null"
              }
            ]
          },
          "affiliate": {
            "type": "boolean",
            "description": "The link carries our affiliate tag"
          }
        }
      },
      "Prices": {
        "type": "object",
        "required": [
          "isbn13",
          "currency",
          "status",
          "offers",
          "retailerSearchLinks",
          "disclosure"
        ],
        "properties": {
          "isbn13": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "currency": {
            "type": "string",
            "const": "USD"
          },
          "asOf": {
            "anyOf": [
              {
                "type": "string",
                "format": "date-time"
              },
              {
                "type": "null"
              }
            ]
          },
          "stale": {
            "type": "boolean"
          },
          "limited": {
            "type": "boolean"
          },
          "status": {
            "type": "string",
            "enum": [
              "ok",
              "no_offers",
              "error",
              "pending",
              "unavailable"
            ]
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                }
              }
            }
          },
          "used": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ConditionSummary"
              },
              {
                "type": "null"
              }
            ]
          },
          "new": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/ConditionSummary"
              },
              {
                "type": "null"
              }
            ]
          },
          "offers": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Offer"
            }
          },
          "retailerSearchLinks": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string"
                },
                "url": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          },
          "pageUrl": {
            "type": "string",
            "format": "uri"
          },
          "disclosure": {
            "type": "string"
          }
        }
      }
    }
  }
}