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 |
Search
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"
]
}
]
}
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"
]
}
]
}
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"
}
]
}
]
}
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
}
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
}
]
}
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
}
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"
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
}
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
}
]
}
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 |
Link
| 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"
Schema of the response body
{
"type": "string",
"contentMediaType": "image/jpeg"
}
image/gif
"string"
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. |