Skip to content

API reference

This reference is generated at build time from openapi/openlibrary.yaml, an OpenAPI 3.1 description written by hand for this site.

Unofficial and partial

It covers only the endpoints used in the guides, and only the fields the guides rely on. Real responses have more fields. It was checked against live responses on 2026-11-11.

Open Library API (unofficial description) 0.3.0

Unofficial. Not affiliated with or endorsed by Open Library or the Internet Archive.

Written by hand from real responses observed on 2026-11-11. It covers only the endpoints used in this site's guides, and only the fields those guides rely on. Responses contain more fields than listed here.


Contact: Isaiah Peebles

License: CC BY 4.0

Servers

Description URL
Open Library https://openlibrary.org

GET /search.json

Search for works

Description Returns works that match the query. A request with no query parameters returns 200 with no results.

Input parameters

Parameter In Type Default Nullable Description
author query string No Match the author name only.
fields query string No Comma-separated list of fields to return for each result.
limit query integer No Maximum number of results in this batch.
offset query integer No 0-based index of the first result.
page query integer No 1-based page number, in steps of limit. Alternative to offset.
q query string No Free-text query. Matches titles, authors, and subjects.
title query string No Match the title only.

Response 200 OK

application/json

{
    "numFound": 0,
    "num_found": 0,
    "numFoundExact": true,
    "start": 0,
    "q": "string",
    "offset": 0,
    "documentation_url": "string",
    "docs": [
        {
            "key": "/works/OL27482W",
            "title": "string",
            "author_name": [
                "string"
            ],
            "author_key": [
                "OL26320A"
            ],
            "first_publish_year": 0,
            "edition_count": 0,
            "cover_i": 0,
            "isbn": [
                "string"
            ]
        }
    ]
}
This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "object",
    "required": [
        "numFound",
        "start",
        "docs"
    ],
    "properties": {
        "numFound": {
            "type": "integer",
            "description": "Total number of matches."
        },
        "num_found": {
            "type": "integer",
            "description": "Same value as `numFound`."
        },
        "numFoundExact": {
            "type": "boolean"
        },
        "start": {
            "type": "integer",
            "description": "Index of the first result in this batch."
        },
        "q": {
            "type": "string",
            "description": "The `q` value sent. Empty when `q` was not used."
        },
        "offset": {
            "type": [
                "integer",
                "null"
            ],
            "description": "The `offset` value sent, or null."
        },
        "documentation_url": {
            "type": "string"
        },
        "docs": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/SearchDoc"
            }
        }
    }
}

GET /search/authors.json

Search for authors

Description Returns authors whose names match q. Keys in the results have no /authors/ prefix.

Input parameters

Parameter In Type Default Nullable Description
limit query integer No Maximum number of results in this batch.
q query string No Author name to search for.

Response 200 OK

application/json

{
    "numFound": 0,
    "numFoundExact": true,
    "start": 0,
    "docs": [
        {
            "key": "OL26320A",
            "name": "string",
            "type": "author",
            "top_work": "string",
            "work_count": 0,
            "birth_date": "string",
            "death_date": "string",
            "alternate_names": [
                "string"
            ],
            "top_subjects": [
                "string"
            ]
        }
    ]
}
This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "object",
    "required": [
        "numFound",
        "start",
        "docs"
    ],
    "properties": {
        "numFound": {
            "type": "integer"
        },
        "numFoundExact": {
            "type": "boolean"
        },
        "start": {
            "type": "integer"
        },
        "docs": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/AuthorSearchDoc"
            }
        }
    }
}

GET /subjects/{subject}.json

List works on a subject

Description Returns the works tagged with a subject. Results are in works, not docs.

Input parameters

Parameter In Type Default Nullable Description
limit query integer No Maximum number of results in this batch.
subject path string No Subject in lowercase, with underscores for spaces.

Response 200 OK

application/json

{
    "key": "/subjects/science_fiction",
    "name": "science fiction",
    "subject_type": "subject",
    "work_count": 0,
    "works": [
        {
            "key": "/works/OL138052W",
            "title": "string",
            "edition_count": 0,
            "cover_id": 0,
            "first_publish_year": 0,
            "has_fulltext": true,
            "authors": [
                {
                    "key": "/authors/OL22098A",
                    "name": "string"
                }
            ]
        }
    ]
}
This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "object",
    "required": [
        "key",
        "name",
        "work_count",
        "works"
    ],
    "properties": {
        "key": {
            "type": "string",
            "examples": [
                "/subjects/science_fiction"
            ]
        },
        "name": {
            "type": "string",
            "examples": [
                "science fiction"
            ]
        },
        "subject_type": {
            "type": "string",
            "examples": [
                "subject"
            ]
        },
        "work_count": {
            "type": "integer",
            "description": "Total number of works on this subject."
        },
        "works": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/SubjectWork"
            }
        }
    }
}

Works

GET /works/{workId}.json

Get a work

Description Returns one work. Author links are keys in authors[].author.key.

Input parameters

Parameter In Type Default Nullable Description
workId path string No Work ID, ending in W.

Response 200 OK

application/json

{
    "key": "/works/OL27448W",
    "title": "string",
    "authors": [
        {
            "author": {
                "key": "/works/OL27448W"
            },
            "type": null
        }
    ],
    "description": null,
    "covers": [
        0
    ],
    "subjects": [
        "string"
    ],
    "first_publish_date": "string",
    "links": [
        {
            "title": "string",
            "url": "string",
            "type": null
        }
    ],
    "type": null,
    "revision": 0,
    "created": {
        "type": "/type/datetime",
        "value": "2026-09-09T17:03:04.654326"
    },
    "last_modified": null
}
This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "object",
    "required": [
        "key",
        "title"
    ],
    "properties": {
        "key": {
            "type": "string",
            "examples": [
                "/works/OL27448W"
            ]
        },
        "title": {
            "type": "string"
        },
        "authors": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "author": {
                        "$ref": "#/components/schemas/KeyRef"
                    },
                    "type": {
                        "$ref": "#/components/schemas/KeyRef"
                    }
                }
            }
        },
        "description": {
            "$ref": "#/components/schemas/Text"
        },
        "covers": {
            "type": "array",
            "items": {
                "type": "integer"
            }
        },
        "subjects": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "first_publish_date": {
            "type": "string"
        },
        "links": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/Link"
            }
        },
        "type": {
            "$ref": "#/components/schemas/KeyRef"
        },
        "revision": {
            "type": "integer"
        },
        "created": {
            "$ref": "#/components/schemas/Datetime"
        },
        "last_modified": {
            "$ref": "#/components/schemas/Datetime"
        }
    }
}

Response 404 Not Found

Refer to the common response description: NotFoundJson

GET /works/{workId}/editions.json

List the editions of a work

Description Returns editions in batches. Follow links.next for the next batch.

Input parameters

Parameter In Type Default Nullable Description
limit query integer No Maximum number of results in this batch.
offset query integer No 0-based index of the first result.
workId path string No Work ID, ending in W.

Response 200 OK

application/json

{
    "links": {
        "self": "string",
        "work": "string",
        "next": "string"
    },
    "size": 0,
    "entries": [
        {
            "key": "/books/OL33912545M",
            "title": "string",
            "works": [
                {
                    "key": "/works/OL27448W"
                }
            ],
            "publishers": [
                "string"
            ],
            "publish_date": "string",
            "isbn_10": [
                "string"
            ],
            "isbn_13": [
                "string"
            ],
            "number_of_pages": 0,
            "physical_format": "string",
            "covers": [
                0
            ],
            "languages": null,
            "type": null,
            "revision": 0,
            "created": {
                "type": "/type/datetime",
                "value": "2026-09-09T17:03:04.654326"
            },
            "last_modified": null
        }
    ]
}
This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "object",
    "required": [
        "links",
        "size",
        "entries"
    ],
    "properties": {
        "links": {
            "type": "object",
            "properties": {
                "self": {
                    "type": "string"
                },
                "work": {
                    "type": "string"
                },
                "next": {
                    "type": "string",
                    "description": "Path of the next batch."
                }
            }
        },
        "size": {
            "type": "integer",
            "description": "Total number of editions."
        },
        "entries": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/Edition"
            }
        }
    }
}

Editions

GET /books/{editionId}.json

Get an edition

Description Returns one edition. The edition links to its work in works[].key.

Input parameters

Parameter In Type Default Nullable Description
editionId path string No Edition ID, ending in M.

Response 200 OK

application/json

{
    "key": "/books/OL33912545M",
    "title": "string",
    "works": [
        {
            "key": "/works/OL27448W"
        }
    ],
    "publishers": [
        "string"
    ],
    "publish_date": "string",
    "isbn_10": [
        "string"
    ],
    "isbn_13": [
        "string"
    ],
    "number_of_pages": 0,
    "physical_format": "string",
    "covers": [
        0
    ],
    "languages": null,
    "type": null,
    "revision": 0,
    "created": {
        "type": "/type/datetime",
        "value": "2026-09-09T17:03:04.654326"
    },
    "last_modified": null
}
This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "object",
    "required": [
        "key",
        "title"
    ],
    "properties": {
        "key": {
            "type": "string",
            "examples": [
                "/books/OL33912545M"
            ]
        },
        "title": {
            "type": "string"
        },
        "works": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/KeyRef"
            }
        },
        "publishers": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "publish_date": {
            "type": "string",
            "description": "Free text. Formats vary, such as `2004` or `25/01/2023`."
        },
        "isbn_10": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "isbn_13": {
            "type": "array",
            "description": "Some values contain hyphens.",
            "items": {
                "type": "string"
            }
        },
        "number_of_pages": {
            "type": "integer"
        },
        "physical_format": {
            "type": "string"
        },
        "covers": {
            "type": "array",
            "items": {
                "type": "integer"
            }
        },
        "languages": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/KeyRef"
            }
        },
        "type": {
            "$ref": "#/components/schemas/KeyRef"
        },
        "revision": {
            "type": "integer"
        },
        "created": {
            "$ref": "#/components/schemas/Datetime"
        },
        "last_modified": {
            "$ref": "#/components/schemas/Datetime"
        }
    }
}

GET /isbn/{isbn}.json

Look up an edition by ISBN

Description Redirects to the edition's /books/{editionId}.json URL.

Input parameters

Parameter In Type Default Nullable Description
isbn path string No ISBN-10 or ISBN-13, digits only.

Response 302 Found

Name Description Schema
Location URL of the edition, such as https://openlibrary.org/books/OL33912545M.json. string

Response 404 Not Found

text/html

"string"
This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "string"
}

Authors

GET /authors/{authorId}.json

Get an author

Description Returns one author. bio can be a string or a typed text object.

Input parameters

Parameter In Type Default Nullable Description
authorId path string No Author ID, ending in A.

Response 200 OK

application/json

{
    "key": "/authors/OL26320A",
    "name": "string",
    "personal_name": "string",
    "fuller_name": "string",
    "birth_date": "string",
    "death_date": "string",
    "bio": null,
    "alternate_names": [
        "string"
    ],
    "photos": [
        0
    ],
    "links": [
        {
            "title": "string",
            "url": "string",
            "type": {
                "key": "/works/OL27448W"
            }
        }
    ],
    "remote_ids": {},
    "type": null,
    "revision": 0,
    "created": {
        "type": "/type/datetime",
        "value": "2026-09-09T17:03:04.654326"
    },
    "last_modified": null
}
This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "object",
    "required": [
        "key",
        "name"
    ],
    "properties": {
        "key": {
            "type": "string",
            "examples": [
                "/authors/OL26320A"
            ]
        },
        "name": {
            "type": "string"
        },
        "personal_name": {
            "type": "string"
        },
        "fuller_name": {
            "type": "string"
        },
        "birth_date": {
            "type": "string"
        },
        "death_date": {
            "type": "string"
        },
        "bio": {
            "$ref": "#/components/schemas/Text"
        },
        "alternate_names": {
            "type": "array",
            "items": {
                "type": "string"
            }
        },
        "photos": {
            "type": "array",
            "description": "Photo IDs for the covers API (`/a/id/{value}-{size}.jpg`).",
            "items": {
                "type": "integer"
            }
        },
        "links": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/Link"
            }
        },
        "remote_ids": {
            "type": "object",
            "description": "IDs in other catalogs, such as `wikidata` or `viaf`.",
            "additionalProperties": {
                "type": "string"
            }
        },
        "type": {
            "$ref": "#/components/schemas/KeyRef"
        },
        "revision": {
            "type": "integer"
        },
        "created": {
            "$ref": "#/components/schemas/Datetime"
        },
        "last_modified": {
            "$ref": "#/components/schemas/Datetime"
        }
    }
}

GET /authors/{authorId}/works.json

List an author's works

Description Returns works in batches. Follow links.next for the next batch.

Input parameters

Parameter In Type Default Nullable Description
authorId path string No Author ID, ending in A.
limit query integer No Maximum number of results in this batch.
offset query integer No 0-based index of the first result.

Response 200 OK

application/json

{
    "links": {
        "self": "string",
        "author": "string",
        "next": "string"
    },
    "size": 0,
    "entries": [
        {
            "key": "/works/OL27448W",
            "title": "string",
            "authors": [
                {
                    "author": {
                        "key": "/works/OL27448W"
                    },
                    "type": null
                }
            ],
            "description": null,
            "covers": [
                0
            ],
            "subjects": [
                "string"
            ],
            "first_publish_date": "string",
            "links": [
                {
                    "title": "string",
                    "url": "string",
                    "type": null
                }
            ],
            "type": null,
            "revision": 0,
            "created": {
                "type": "/type/datetime",
                "value": "2026-09-09T17:03:04.654326"
            },
            "last_modified": null
        }
    ]
}
This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "object",
    "required": [
        "links",
        "size",
        "entries"
    ],
    "properties": {
        "links": {
            "type": "object",
            "properties": {
                "self": {
                    "type": "string"
                },
                "author": {
                    "type": "string"
                },
                "next": {
                    "type": "string",
                    "description": "Path of the next batch."
                }
            }
        },
        "size": {
            "type": "integer",
            "description": "Total number of works."
        },
        "entries": {
            "type": "array",
            "items": {
                "$ref": "#/components/schemas/Work"
            }
        }
    }
}

Covers

GET /b/{idType}/{value}-{size}.jpg

Get a book cover image

Description id URLs return the image directly. isbn and olid URLs were observed to redirect to archive.org.

Input parameters

Parameter In Type Default Nullable Description
default query string No Set to false to get 404 for a missing image instead of a 1x1 blank GIF.
idType path string No What value is.
size path string No S small, M medium, or L large.
value path string No A cover ID, an ISBN, or an edition ID such as OL33912545M.

Response 200 OK

Refer to the common response description: Image

Response 302 Found

Refer to the common response description: ImageRedirect

Response 404 Not Found

GET /a/{idType}/{value}-{size}.jpg

Get an author photo

Description Returns an author photo by photo ID or author ID.

Input parameters

Parameter In Type Default Nullable Description
default query string No Set to false to get 404 for a missing image instead of a 1x1 blank GIF.
idType path string No What value is.
size path string No S small, M medium, or L large.
value path string No A photo ID from the author's photos, or an author ID such as OL26320A.

Response 200 OK

Refer to the common response description: Image

Response 404 Not Found


Schemas

Author

Name Type Description
alternate_names Array<string>
bio Text
birth_date string
created Datetime
death_date string
fuller_name string
key string
last_modified Datetime
links Array<Link>
name string
personal_name string
photos Array<integer> Photo IDs for the covers API (/a/id/{value}-{size}.jpg).
remote_ids IDs in other catalogs, such as wikidata or viaf.
revision integer
type KeyRef

AuthorSearchDoc

Name Type Description
alternate_names Array<string>
birth_date string
death_date string
key string Author ID without the /authors/ prefix.
name string
top_subjects Array<string>
top_work string
type string
work_count integer

AuthorSearchResponse

Name Type Description
docs Array<AuthorSearchDoc>
numFound integer
numFoundExact boolean
start integer

Datetime

Name Type Description
type string
value string

Edition

Name Type Description
covers Array<integer>
created Datetime
isbn_10 Array<string>
isbn_13 Array<string> Some values contain hyphens.
key string
languages Array<KeyRef>
last_modified Datetime
number_of_pages integer
physical_format string
publish_date string Free text. Formats vary, such as 2004 or 25/01/2023.
publishers Array<string>
revision integer
title string
type KeyRef
works Array<KeyRef>

EditionList

Name Type Description
entries Array<Edition>
links _Properties: _self, work, next
size integer Total number of editions.

KeyRef

Name Type Description
key string
Name Type Description
title string
type KeyRef
url string

NotFound

Name Type Description
error string
key string

SearchDoc

Name Type Description
author_key Array<string> Author IDs without the /authors/ prefix.
author_name Array<string>
cover_i integer Cover ID for the covers API.
edition_count integer
first_publish_year integer
isbn Array<string>
key string
title string

SearchResponse

Name Type Description
docs Array<SearchDoc>
documentation_url string
num_found integer Same value as numFound.
numFound integer Total number of matches.
numFoundExact boolean
offset integer | null The offset value sent, or null.
q string The q value sent. Empty when q was not used.
start integer Index of the first result in this batch.

SubjectResponse

Name Type Description
key string
name string
subject_type string
work_count integer Total number of works on this subject.
works Array<SubjectWork>

SubjectWork

Name Type Description
authors Array<_Properties: _key, name>
cover_id integer Cover ID for the covers API.
edition_count integer
first_publish_year integer
has_fulltext boolean
key string
title string

Text

Type: 

Work

Name Type Description
authors Array<_Properties: _author, type>
covers Array<integer>
created Datetime
description Text
first_publish_date string
key string
last_modified Datetime
links Array<Link>
revision integer
subjects Array<string>
title string
type KeyRef

WorkList

Name Type Description
entries Array<Work>
links _Properties: _self, author, next
size integer Total number of works.

Common responses

This section describes common responses that are reused across operations.

NotFoundJson

No record with this key. The body is JSON, but the response was observed with no Content-Type header.

application/json

{
    "error": "notfound",
    "key": "/works/OL0000000000W"
}

Schema of the response body

{
    "type": "object",
    "required": [
        "error",
        "key"
    ],
    "properties": {
        "error": {
            "type": "string",
            "examples": [
                "notfound"
            ]
        },
        "key": {
            "type": "string"
        }
    }
}

Image

The image. For a missing image without default=false, this is a 1x1 GIF with Content-Type image/gif.

image/jpeg

"string"
This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "string",
    "contentMediaType": "image/jpeg"
}

image/gif

"string"
This example has been generated automatically from the schema and it is not accurate. Refer to the schema for more information.

Schema of the response body

{
    "type": "string",
    "contentMediaType": "image/gif"
}

ImageRedirect

Redirect to the image file on archive.org.

Common parameters

This section describes common parameters that are reused across operations.

limit

Name In Type Default Nullable Description

offset

Name In Type Default Nullable Description

workId

Name In Type Default Nullable Description

authorId

Name In Type Default Nullable Description

coverSize

Name In Type Default Nullable Description

coverDefault

Name In Type Default Nullable Description

Tags

Name Description
Search Find works and authors, and browse by subject.
Works Works and their editions.
Editions Single published versions of a work.
Authors Authors and their works.
Covers Cover images and author photos, served from covers.openlibrary.org.