# `image.list`

<span class="badge">bearer / PAT</span>

**List the caller's images (cursor-paginated)**

Ordered by capture time (taken_at, falling back to created_at), newest first. Pass the returned next_cursor back as cursor to page; an empty next_cursor means the last page.

## Parameters

Passed by name in the `params` object.

| Name | Type | Required | Description |
|---|---|---|---|
| `limit` | integer | no | Max items per page (default 50) |
| `cursor` | string | no | Opaque cursor from a prior page's next_cursor; omit for the first page |
| `album_id` | string | no | Restrict to one folder (UUID); folder view orders by manual position first. Omit for the whole library. Keep it constant across a paginated run |

## Result

Returns `listResult`:

| Field | Type | Description |
|---|---|---|
| `items *` | `array<imageSummary>` |  |
| `next_cursor *` | string |  |

## Example

Request:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "image.list",
  "params": {
    "limit": 50
  }
}
```

Response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "items": [
      {
        "id": "018f3a7d-2b8c-7f1a-a4d5-6e7f8a9b0c1d",
        "title": "Golden Gate at dawn",
        "status": "ready",
        "width": 6000,
        "height": 4000,
        "thumb_url": "https://img.peinture.gumeniuk.com/r/018f3a7d-2b8c-7f1a-a4d5-6e7f8a9b0c1d/thumb.webp?v=3",
        "taken_at": "2026-02-11T06:42:18Z",
        "created_at": "2026-02-11T07:03:00Z"
      }
    ],
    "next_cursor": "018f3a6b-9d1e-7c4a-8b2f-1a2b3c4d5e6f"
  }
}
```

**curl**

```bash
curl -s https://peinture.gumeniuk.com/rpc \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"image.list","params":{"limit":50}}'
```

**JavaScript**

```js
const res = await fetch("https://peinture.gumeniuk.com/rpc", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${token}`,
  },
  body: JSON.stringify({
    jsonrpc: "2.0", id: 1, method: "image.list", params: {"limit":50},
  }),
});
const { result, error } = await res.json();
```

**Go**

```go
body := []byte(`{"jsonrpc":"2.0","id":1,"method":"image.list","params":{"limit":50}}`)
req, _ := http.NewRequest("POST", "https://peinture.gumeniuk.com/rpc", bytes.NewReader(body))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
resp, err := http.DefaultClient.Do(req)
```