Items
List Items
Returns a paginated list of items in your library.
GET
/
v1
/
items
curl "https://api.getmatter.com/public/v1/items?status=queue&limit=10" \
-H "Authorization: Bearer mat_your_token_here"
response = requests.get(
"https://api.getmatter.com/public/v1/items",
headers={"Authorization": f"Bearer {token}"},
params={"status": "queue", "limit": 10}
)
items = response.json()
const response = await fetch(
"https://api.getmatter.com/public/v1/items?status=queue&limit=10",
{ headers: { Authorization: `Bearer ${token}` } }
);
const items = await response.json();
{
"object": "list",
"results": [
{
"object": "item",
"id": "itm_r9f3a",
"title": "How to Do Great Work",
"url": "https://paulgraham.com/greatwork.html",
"site_name": "paulgraham.com",
"author": {
"object": "author",
"id": "aut_p4w7q",
"name": "Paul Graham"
},
"status": "queue",
"is_favorite": false,
"content_type": "article",
"word_count": 11842,
"reading_progress": 0.35,
"image_url": "https://cdn.getmatter.com/images/itm_r9f3a.jpg",
"library_position": 58974321000,
"inbox_position": null,
"tags": [
{
"object": "tag",
"id": "tag_n5j2x",
"name": "essays"
}
],
"updated_at": "2026-03-30T19:15:00Z"
}
],
"has_more": true,
"next_cursor": "eyJpZCI6MTIzNH0="
}
Query Parameters
string
default:"all"
Filter by item status. Comma-separated for multiple:
queue,archive. Values: inbox, queue, archive, or all.string
default:"updated"
Sort order for results. Values:
updated— Sort by last-updated timestamp (default). Best for incremental sync.library_position— Sort by the item’s library position (manual queue ordering). Items without a library entry sort last.inbox_position— Sort by the item’s inbox feed position (newest first). Items not in the inbox sort last.
library_position and inbox_position fields regardless of the order used, enabling clients to sort locally after incremental sync.boolean
Filter to favorited items only.
string
Filter to items with a specific tag ID. Comma-separated for multiple:
tag_n5j2x,tag_k3m9p (returns items matching any of the tags).string
Filter by content type. Comma-separated for multiple:
article,podcast. Values: article, video, podcast, pdf, tweet, newsletter.string
ISO 8601 timestamp. Return only items updated after this time. Useful for incremental sync.An item’s
updated_at reflects any change to the item or its associated data — status changes, reading progress, favorites, tag additions/removals, new annotations, and content re-extraction all advance the timestamp. For inbox items that have never been interacted with, updated_at is the time the item appeared in your inbox.integer
default:25
Number of items per page. Min 1, max 100.
string
Cursor for the next page of results. Obtained from
next_cursor in a previous response.Response
string
required
Always
"list".boolean
required
Whether there are more results after this page.
string
Cursor to fetch the next page.
null when there are no more results.curl "https://api.getmatter.com/public/v1/items?status=queue&limit=10" \
-H "Authorization: Bearer mat_your_token_here"
response = requests.get(
"https://api.getmatter.com/public/v1/items",
headers={"Authorization": f"Bearer {token}"},
params={"status": "queue", "limit": 10}
)
items = response.json()
const response = await fetch(
"https://api.getmatter.com/public/v1/items?status=queue&limit=10",
{ headers: { Authorization: `Bearer ${token}` } }
);
const items = await response.json();
{
"object": "list",
"results": [
{
"object": "item",
"id": "itm_r9f3a",
"title": "How to Do Great Work",
"url": "https://paulgraham.com/greatwork.html",
"site_name": "paulgraham.com",
"author": {
"object": "author",
"id": "aut_p4w7q",
"name": "Paul Graham"
},
"status": "queue",
"is_favorite": false,
"content_type": "article",
"word_count": 11842,
"reading_progress": 0.35,
"image_url": "https://cdn.getmatter.com/images/itm_r9f3a.jpg",
"library_position": 58974321000,
"inbox_position": null,
"tags": [
{
"object": "tag",
"id": "tag_n5j2x",
"name": "essays"
}
],
"updated_at": "2026-03-30T19:15:00Z"
}
],
"has_more": true,
"next_cursor": "eyJpZCI6MTIzNH0="
}
curl "https://api.getmatter.com/public/v1/items?status=queue&limit=10" \
-H "Authorization: Bearer mat_your_token_here"
response = requests.get(
"https://api.getmatter.com/public/v1/items",
headers={"Authorization": f"Bearer {token}"},
params={"status": "queue", "limit": 10}
)
items = response.json()
const response = await fetch(
"https://api.getmatter.com/public/v1/items?status=queue&limit=10",
{ headers: { Authorization: `Bearer ${token}` } }
);
const items = await response.json();
{
"object": "list",
"results": [
{
"object": "item",
"id": "itm_r9f3a",
"title": "How to Do Great Work",
"url": "https://paulgraham.com/greatwork.html",
"site_name": "paulgraham.com",
"author": {
"object": "author",
"id": "aut_p4w7q",
"name": "Paul Graham"
},
"status": "queue",
"is_favorite": false,
"content_type": "article",
"word_count": 11842,
"reading_progress": 0.35,
"image_url": "https://cdn.getmatter.com/images/itm_r9f3a.jpg",
"library_position": 58974321000,
"inbox_position": null,
"tags": [
{
"object": "tag",
"id": "tag_n5j2x",
"name": "essays"
}
],
"updated_at": "2026-03-30T19:15:00Z"
}
],
"has_more": true,
"next_cursor": "eyJpZCI6MTIzNH0="
}