/dev/docs/api/lists
Type: /type/page
body: value: * [Create a list](#create-list)
 * [Add/delete a seed from a list](#edits-seed)
 * [Delete a list](#delete-list)
 * [Update a list](#update-list) -- not implemented
 * [Get a user's lists](#users-lists)
 * [Get lists containing a seed](#seed-lists)
 * [Get seeds of a list](#read-list)
 * [Get editions of a list](#get-editions) (for works use the seeds API above)
 * [Get subjects of a list](#get-subjects)
 * [Search lists](#search-lists)

<a name="users-lists">&nbsp;</a>
## Get a user's lists

Request:

    GET http://openlibrary.org/people/george08/lists.json

Response:

    {
        "links": {
            "self": "/people/george08/lists.json", 
            "next": "/people/george08/lists.json?limit=5&offset=5"
        }, 
        "size": 12, 
        "entries": [
            {
                "url": "/people/george08/lists/OL13L", 
                "full_url": "/people/george08/lists/OL13L/Various_Seeds_for_Testing", 
                "name": "Various Seeds for Testing",
                "last_update": "2010-12-21T00:46:17.712513", 
                "seed_count": 13, 
                "edition_count": 13181
            }, 
            {
                "url": "/people/george08/lists/OL97L", 
                "full_url": "/people/george08/lists/OL97L/Time_Travel", 
                "name": "Time Travel",
                "last_update": "2010-12-17T18:27:14.781336", 
                "seed_count": 5,
                "edition_count": 838
            }, 
            ...
        ]
    }

<a name="seed-lists">&nbsp;</a>
## Get lists containing a seed

URL Format:

* http://openlibrary.org/books/OL1M/lists.json
* http://openlibrary.org/works/OL1W/lists.json
* http://openlibrary.org/authors/OL1A/lists.json
* http://openlibrary.org/subjects/place:san_francisco/lists.json


Sample Request:

    GET http://openlibrary.org/works/OL8721462W/lists.json

Response:

    {
        "size": 1, 
        "links": {
            "self": "/works/OL8721462W/lists.json"
        }, 
        "entries": [
            {
                "url": "/people/george08/lists/OL43L", 
                "full_url": "/people/george08/lists/OL43L/Top_100_Works_in_World_Literature_(in_progress)", 
                "name": "Top 100 Works in World Literature (in progress)",
                "last_update": "2010-12-21T04:17:33.140325", 
                "seed_count": 28, 
                "edition_count": 2105
            }
        ]
    }

<a name="search-lists">&nbsp;</a>
## Search lists

- limited to 100 results for performance reasons

Request:

    GET http://openlibrary.org/search/lists.json?q=book&limit=20&offset=0

Response:

    {
        "start": 0,
        "docs": [
            {
            "seed_count": 1,
            "edition_count": 0,
            "url": "/people/rosey1234/lists/OL68457L",
            "last_update": "2019-10-12T17:05:09.130806",
            "full_url": "/people/rosey1234/lists/OL68457L/book",
            "name": "book"
            },
            {
            "seed_count": 1,
            "edition_count": 0,
            "url": "/people/alebuitrago/lists/OL69449L",
            "last_update": "2019-10-12T17:05:09.130806",
            "full_url": "/people/alebuitrago/lists/OL69449L/book",
            "name": "book"
            },
            ...
        ]
    }


<a name="create-list">&nbsp;</a>
## Create a list

- create an empty list (no book seed)

Request:

    POST /people/anand/lists HTTP/1.1
    Content-Type: application/json
    
    {
        "name": "Empty List",
        "description": "This is an empty list with no books added yet.",
    }

Response:

    HTTP/1.1 201 Created
    Location: http://openlibrary.org/user/anand/lists/OL1L

- create a list with book seed(s)

Request:

    POST /people/anand/lists HTTP/1.1
    Content-Type: application/json
    
    {
        "name": "18th Century Architecture",
        "description": "Studies of architectural practice, mainly English works",
        "tags": ["Architecture", "18th Century", "Drawings", "Buildings"],
        "seeds": [
            "/books/OL1M",
            "/subjects/gothic_architecture"
        ]
    }

Response:

    HTTP/1.1 201 Created
    Location: http://openlibrary.org/user/anand/lists/OL1L

<a name="read-list">&nbsp;</a>
##Read a list

Request:

    GET http://openlibrary.org/people/george08/lists/OL97L.json

Response:

    {
        "links": {
            "editions": "/people/george08/lists/OL97L/editions", 
            "self": "/people/george08/lists/OL97L", 
            "seeds": "/people/george08/lists/OL97L/seeds", 
            "subjects": "/people/george08/lists/OL97L/subjects"
        }, 
        "meta": {
            "last_modified": "2010-12-17T18:54:58.115370", 
            "revision": 5, 
            "created": "2010-12-17T18:50:35.064318"
        }, 
        "name": "Time Travel", 
        "description": "Happy to lose myself in reading about that.",
        "seed_count": 5, 
        "edition_count": 838
    }

<a name="delete-list">&nbsp;</a>
## Delete a list

Request:

    POST /people/anand/list/OL1L/delete.json 
    Content-Type: application/json

<a name="update-list">&nbsp;</a>
## Update a list

<div class="warning red">This is not yet implemented!</div>

Request:

    PUT /people/anand/list/OL1L HTTP/1.1
    Content-Type: application/json
    
    {
        "name": "18th Century Architecture",
        "description": "Studies of architectural practice, mainly English works",
        "tags": ["Architecture", "18th Century", "Drawings", "Buildings"],
        "seeds": [
            "subject:gothic_architecture"
        ]
    }

Response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {"key": "/people/anand/list/OL1L", "revision": 3}

<a name="read-list">&nbsp;</a>
## Get seeds of a list

Request:

    GET http://openlibrary.org/people/george08/lists/OL97L/seeds.json
    
Response:

    {
        "size": 5, 
        "links": {
            "self": "/people/george08/lists/OL97L/seeds", 
            "list": "/people/george08/lists/OL97L"
        }, 
        "entries": [
            {
                "url": "/books/OL24331810M", 
                "full_url": "/books/OL24331810M/The_Time_Machine", 
                "type": "edition", 
                "title": "The Time Machine", 
                "last_update": "2010-12-17T18:27:14.781336", 
                "work_count": 1,
                "edition_count": 1, 
                "ebook_count": 1, 
                "picture": {
                    "url": "http://covers.openlibrary.org/b/id/6570017-S.jpg"
                }
            }, 
            {
                "url": "/books/OL22864669M", 
                "full_url": "/books/OL22864669M/A_Connecticut_Yankee_in_King_Arthur's_Court", 
                "type": "edition", 
                "title": "A Connecticut Yankee in King Arthur's Court", 
                "last_update": "2010-09-06T02:05:15.820687", 
                "work_count": 1,
                "edition_count": 1, 
                "ebook_count": 7, 
                "picture": {
                    "url": "http://covers.openlibrary.org/b/id/6031475-S.jpg"
                }
            }, 
            ...
        ]
    }    

<a name="edits-seeds">&nbsp;</a>
## Add/delete a seed from a list

- Add seed(s) to a list

Request:

    POST /people/anand/list/OL1L/seeds HTTP/1.1
    Content-Type: application/json
    
    {
        "add": [
            {key: "/books/OL25083437M"},
            {key: "/books/OL24375501M"}
        ]
    }

Response:

    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {"key": "/people/anand/list/OL1L", "revision": 3}

- Delete seed(s) from a list

Request:

    POST /people/anand/lists/OL1L/seeds HTTP/1.1
    Content-Type: application/json
    
    {
        "add": [
            "/subjects/gothic_architecture"
        ],
        "remove": [
            "/works/OL1958650W"
        ]
    }

Response:

    200 OK HTTP/1.1
    Content-Type: application/json
    
    {"ok": "true"}

<a name="get-editions">&nbsp;</a>
## Get editions of a list

Request:

    GET http://openlibrary.org/people/george08/lists/OL97L/editions.json?limit=2
    
Response:

    {
        "links": {
            "self": "/people/george08/lists/OL97L/editions.json?limit=2", 
            "next": "/people/george08/lists/OL97L/editions.json?limit=2&offset=2",
            "list": "/people/george08/lists/OL97L"
        }, 
        "size": 838, 
        "entries": [
            {
                "number_of_pages": 216, 
                "table_of_contents": [...],
                "series": ["Buckram series"], 
                "covers": [6570017], 
                "lc_classifications": ["PZ3.W465 Ti"], 
                "latest_revision": 6, 
                "ocaid": "timemachineinven00well", 
                "subtitle": "an invention", 
                "source_records": ["ia:timemachineinven00well"], 
                "title": "The Time Machine", 
                "languages": [
                    {
                        "key": "/languages/eng"
                    }
                ], 
                "publish_country": "nyu", 
                "by_statement": "by H. G. Wells", 
                "oclc_numbers": [
                    "002345875"
                ], 
                "type": {
                    "key": "/type/edition"
                }, 
                "revision": 6, 
                "publishers": [
                    "H. Holt and Company"
                ], 
                "last_modified": {
                    "type": "/type/datetime", 
                    "value": "2010-12-17T18:27:14.781336"
                }, 
                "key": "/books/OL24331810M", 
                "authors": [
                    {
                        "key": "/authors/OL13066A"
                    }
                ], 
                "publish_places": [
                    "New York"
                ], 
                "pagination": "vii, 216 p.", 
                "classifications": {}, 
                "created": {
                    "type": "/type/datetime", 
                    "value": "2010-08-12T15:25:20.784688"
                }, 
                "lccn": [
                    "08036642"
                ], 
                "identifiers": {}, 
                "publish_date": "1895", 
                "works": [
                    {
                        "key": "/works/OL52267W"
                    }
                ]
            }, 
            {
                ...
            }
        ]
    }
    

<a name="get-subjects">&nbsp;</a>
## Get subjects of a list

Request:

    GET http://openlibrary.org/people/george08/lists/OL97L/subjects.json?limit=5

Response:

    {
        "links": {
            "self": "/people/george08/lists/OL97L/subjects", 
            "list": "/people/george08/lists/OL97L"
        }, 
        "subjects": [
            {
                "count": 256, 
                "url": "/subjects/general_relativity_(physics)", 
                "name": "General relativity (Physics)"
            }, 
            ...
        ], 
        "places": [
            {
                "count": 1, 
                "url": "/subjects/place:great_britain", 
                "name": "Great Britain"
            }, 
            ...
        ], 
        "people": [
            {
                "count": 1, 
                "url": "/subjects/person:mark_twain_(1835-1910)", 
                "name": "Mark Twain (1835-1910)"
            }, 
            ...
        ],
        "times": [
            {
                "count": 1, 
                "url": "/subjects/time:19th_century", 
                "name": "19th century"
            }
        ]
    }

<a name="edits-seed">&nbsp;</a>
m: edit
title: Lists API