Skip to main content
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

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.