# 3.2 Constructing data requests

Using the `dataRequests`, you can specify one or more requests to be made to the Zotero API. In most cases, you'll be using the same `apikey` - what will be different is the `dataURI` argument, and possibly the parameters (`params`) you want to use.

### `dataURI` : scoping your request

The **dataURI** tells the API where to look for items ; it's composed of a **user-or-group prefix** and a **suffix**.

* *The* **user-or-group prefix** will be either `users/your_user_id` (for a personal library) or `groups/the_group_id` (for group libraries).
* The **suffix** is used to specify which items you want within the library. This means both *where the items are located*, and *what kind of items should be retrieved*. The [official API documentation](https://www.zotero.org/support/dev/web_api/v3/basics#user_and_group_library_urls) lists out the possible combinations - it's a great resource !

In most cases, I'd suggest using one of the following :

* All items from your user library : `users/your_user_id/items`
* All items from one of your collections : `users/your_user_id/collections/collection_id/items`

{% hint style="info" %}
You can request either **all items** or **top-level items only**. The difference between the two is that top-level items are the items themselves (book, article, paper...), while selecting *all items* will also return information about attachments & notes.

I suggest asking for all items - it may take longer for the data to be returned, but it'll allow you to open PDFs and import notes directly in Roam !
{% endhint %}

### `params` : filtering your items

The **params** can apply search parameters & filters to your request. Refer to the [official API documentation](https://www.zotero.org/support/dev/web_api/v3/basics#read_requests) for an overview of all that they can do ; within the context of the extension, you likely won't need to specify anything here. 

**If you don't want to apply any parameters, I highly recommend setting params to a value of `limit=100`.** It's the maximal number of items that can be returned in a single API call ; this will minimize the total number of calls the extension needs to make to get all the items that match a request.

With that said, there are some cases where you might want to use filters, if you have a particular system in Zotero for example. Here are two parameters which you might find helpful :

* `itemType` will let you scope your request to items of a given type (e.g, papers)
* `tag` will let you scope your request to items that have/don't have a tag (e.g, papers marked as #read). Logic operators are also available (and, or). Read more [in the official docs](https://www.zotero.org/support/dev/web_api/v3/basics#search_parameters).

### :pencil2: Examples

Requesting all items in your personal library that are tagged as #read

```javascript
zoteroRoam_settings = {
    dataRequests: {
        apikey: 'your API key',
        dataURI: 'users/<your_user_id>/items/top',
        params: 'tag=read&limit=100'
    }
}
```

Requesting all book items from one of your collections

```javascript
zoteroRoam_settings = {
    dataRequests: {
        apikey: 'your API key',
        dataURI: 'users/<your_user_id>/collections/<the_collection_id>/items',
        params: 'itemType=book&limit=100'
    }
}
```

## Using data from multiple libraries

The extension supports data retrieval from several Zotero libraries (e.g, personal + group(s)). There needs to be a separate data request for each library you want to be using, which you can specify like so :

```javascript
zoteroRoam_settings = {
    dataRequests: [
    {dataURI: 'users/1234567/items', apikey: 'XXXXXX', params: 'limit=100'},
    {dataURI: 'groups/7654321/items', apikey: 'YYYYYY', params: 'limit=100'}
    ]
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://alix-lahuec.gitbook.io/zotero-roam/v0.6/customization/api-request.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.