> ## Documentation Index > Fetch the complete documentation index at: https://docs.alura.io/llms.txt > Use this file to discover all available pages before exploring further. # Saved research > Folders, lists and saved items: the same saved research as in the Alura app. Saved research in the API is the saved research in the Alura app: a list you create through the API shows up in the app, and the other way around. * **Folders** group lists, one level deep. A **list** sits in a folder or on its own, and can hold products, shops and keywords together. * Each folder and list has a **visibility**: `workspace` (the default) shows it to every member of the workspace; `private` shows it only to the person who created it. An API key acts as the person who created the key, so it sees their private lists. * Folder IDs start with `fld_`, list IDs with `lst_` and saved item IDs with `itm_`. ## Reading and writing * `GET /v1/research/saved/folders` and `GET /v1/research/saved/lists` list your folders and lists. Reading folders and lists is free, and so is every change. * `GET /v1/research/saved/lists/{id}/items` returns the items with the same summary a search returns (a keyword: the keyword object), so you see current data: products first, then shops, then keywords, `?type=` for one kind. It costs 1 API credit per item returned with data. An item whose product or shop is no longer available comes back with `data: null` and `status: unavailable`, one whose shop opted out of Alura with `status: shop_opted_out`; both are free. * `POST /v1/research/saved/lists/{id}/items` adds up to 100 items at once (`{"items": [{"type": "product", "ref_id": "..."}]}`), all or nothing. Adding an item that is already there does nothing. You can only add items Alura already has: anything else is named in a `422 unprocessable` and nothing is added. Adding never fetches anything from Etsy. * `DELETE /v1/research/saved/lists/{id}/items` removes items by their `itm_` ID (`{"items": [{"id": "itm_..."}]}`), or by `type` and `ref_id`. By type and ID, an item that is not in the list is skipped. An `itm_` ID that names no item of the list is `404 not_found`, and nothing is removed. * `POST /v1/research/saved/folders` and `POST /v1/research/saved/lists` create a folder or a list. `PATCH` on a folder or list renames it, changes its visibility, or moves a list into a folder or out of one (`folder_id: null`). The last change wins, and the answer carries the new `updated_at`. * Deleting a folder that still has lists needs `lists=move_to_root` or `lists=delete`; an empty folder needs nothing. A folder that also holds lists you cannot see (another member's private list) cannot be deleted through the API. * Only the person who created a folder or list, or a workspace owner or admin, can rename, move, change or delete it (`403 role_required`). Any member can create folders and lists and save into them. * A deleted folder or list is gone from the app at once. For 7 days Alura support can restore it, with its lists and items. ## Retrying writes safely Send an `Idempotency-Key` header (a fresh UUID per change) on `POST`, `PATCH` and `DELETE`. Repeating the same request with the same key within 24 hours returns the first answer with `Idempotent-Replayed: true` and changes nothing again. The same key with a different request is `409 conflict`; while the first request is still running, `409 idempotency_processing`. Through MCP there is no such header: `create_saved_folder` and `create_saved_list` return the folder or list you can already see with exactly that name in the same place instead of making a second one. ## Private folders and lists Private folders and lists are always respected: nobody but their creator sees them through the API. Creating a private one, or making one private, is not possible through the API yet (`400 invalid_request`), until the Alura app hides them from the rest of the workspace too. ## How many items you can save | Plan | Saved items per workspace | | - | - | | Free | 0 (read and delete only) | | Basic | 250 | | Growth | 5,000 | | Professional | 100,000 | The API counts this limit **per workspace**, against the workspace's plan. The Alura app counts it differently: per user, using the best plan among all the workspaces that user belongs to. So the same person can have room left in the app and be at the limit in the API, or the other way around. Over the limit, adding answers `403 plan_required`. ## What the API doesn't show **Global and public lists** in the app are not available through the API. They never appear in lists or counts, and opening one by ID answers `404 not_found`. ## Lists created without a workspace Older writers, such as older versions of the Alura app, may create a folder or list without saying which workspace it belongs to. The database then assigns it to its creator's active workspace in the app at that moment, and that never changes afterwards. If you switch workspace in the app often, check which workspace a new list landed in. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.