Search
Search
Full-text search across Matter, grouped by type.
GET
/
v1
/
search
curl "https://api.getmatter.com/public/v1/search?query=machine+learning&type=items&status=queue" \
-H "Authorization: Bearer mat_your_token_here"
response = requests.get(
"https://api.getmatter.com/public/v1/search",
headers={"Authorization": f"Bearer {token}"},
params={"query": "machine learning", "type": "items", "status": "queue"}
)
data = response.json()
for item in data["items"]["results"]:
print(item["title"])
const response = await fetch(
"https://api.getmatter.com/public/v1/search?query=machine+learning&type=items&status=queue",
{ headers: { Authorization: `Bearer ${token}` } }
);
const data = await response.json();
data.items.results.forEach(item => console.log(item.title));
{
"object": "search_results",
"items": {
"object": "list",
"results": [
{
"object": "item",
"id": "itm_r9f3a",
"title": "Introduction to Machine Learning",
"url": "https://example.com/intro-ml",
"site_name": "example.com",
"author": {
"object": "author",
"id": "aut_p4w7q",
"name": "Jane Smith"
},
"status": "queue",
"is_favorite": false,
"content_type": "article",
"processing_status": "completed",
"word_count": 4200,
"reading_progress": 0.35,
"image_url": null,
"library_position": 58974321000,
"inbox_position": null,
"tags": [],
"updated_at": "2026-03-30T19:15:00Z"
},
{
"object": "item",
"id": "itm_k4m2n",
"title": "Neural Networks from Scratch",
"url": "https://example.com/nn-scratch",
"site_name": "example.com",
"author": null,
"status": null,
"is_favorite": false,
"content_type": "article",
"processing_status": "completed",
"word_count": 8100,
"reading_progress": 0.0,
"image_url": null,
"library_position": null,
"inbox_position": null,
"tags": [],
"updated_at": "2026-03-28T12:00:00Z"
}
],
"has_more": false,
"next_cursor": null
}
}
Search across Matter. Results are grouped by type, each with independent
pagination. Currently supports
items; more types will be added in
future releases.
Query Parameters
string
required
Search query string (min 2 characters). Supports operators:
"exact phrase"— required phrase match-excluded— exclude articles containing a termby:author— filter by author or publisher namesite:domain— filter by domain or publishertitle:word— match in title only
machine learning, "deep work", by:graham site:paulgraham.comstring
required
Comma-separated list of result types to include. Currently supported:
items.string
Filter for item results. Restricts results to items with the given status. Comma-separated for multiple values. Omit to search all content. Only applies when
items is in the type parameter.queue— queue items onlyarchive— archived items onlyqueue,archive— both queue and archive
integer
default:25
Maximum results per type. Min 1, max 100.
string
Cursor for the next page of results. Obtained from
next_cursor in a previous response.Response
string
required
Always
"search_results".object
Matching items, ranked by relevance. Present when
items is in the type parameter.Show items properties
Show items properties
string
Always
"list".Item[]
Array of item objects ranked by relevance.
Show Item properties
Show Item properties
string
Always
"item".string
Prefixed item ID (e.g.
itm_r9f3a).string
The item’s title.
string
Original URL of the content.
string
The source website name.
object | null
string | null
Status:
inbox, queue, or archive. null when the item has no status.string
Type of content:
article, podcast, pdf, or tweet.string
Content extraction status:
processing or completed.boolean
Whether the item is favorited.
number
Reading progress from
0.0 to 1.0.integer | null
Estimated word count.
string | null
URL of the item’s hero image.
string | null
Short excerpt or description.
integer | null
Position in the library.
null if not in the library.integer | null
Position in the inbox feed.
null if not in the inbox.Tag[]
Tags applied to this item.
string
ISO 8601 timestamp of the last change.
boolean
Whether there are more results after this page.
string | null
Cursor for the next page, or
null.curl "https://api.getmatter.com/public/v1/search?query=machine+learning&type=items&status=queue" \
-H "Authorization: Bearer mat_your_token_here"
response = requests.get(
"https://api.getmatter.com/public/v1/search",
headers={"Authorization": f"Bearer {token}"},
params={"query": "machine learning", "type": "items", "status": "queue"}
)
data = response.json()
for item in data["items"]["results"]:
print(item["title"])
const response = await fetch(
"https://api.getmatter.com/public/v1/search?query=machine+learning&type=items&status=queue",
{ headers: { Authorization: `Bearer ${token}` } }
);
const data = await response.json();
data.items.results.forEach(item => console.log(item.title));
{
"object": "search_results",
"items": {
"object": "list",
"results": [
{
"object": "item",
"id": "itm_r9f3a",
"title": "Introduction to Machine Learning",
"url": "https://example.com/intro-ml",
"site_name": "example.com",
"author": {
"object": "author",
"id": "aut_p4w7q",
"name": "Jane Smith"
},
"status": "queue",
"is_favorite": false,
"content_type": "article",
"processing_status": "completed",
"word_count": 4200,
"reading_progress": 0.35,
"image_url": null,
"library_position": 58974321000,
"inbox_position": null,
"tags": [],
"updated_at": "2026-03-30T19:15:00Z"
},
{
"object": "item",
"id": "itm_k4m2n",
"title": "Neural Networks from Scratch",
"url": "https://example.com/nn-scratch",
"site_name": "example.com",
"author": null,
"status": null,
"is_favorite": false,
"content_type": "article",
"processing_status": "completed",
"word_count": 8100,
"reading_progress": 0.0,
"image_url": null,
"library_position": null,
"inbox_position": null,
"tags": [],
"updated_at": "2026-03-28T12:00:00Z"
}
],
"has_more": false,
"next_cursor": null
}
}
curl "https://api.getmatter.com/public/v1/search?query=machine+learning&type=items&status=queue" \
-H "Authorization: Bearer mat_your_token_here"
response = requests.get(
"https://api.getmatter.com/public/v1/search",
headers={"Authorization": f"Bearer {token}"},
params={"query": "machine learning", "type": "items", "status": "queue"}
)
data = response.json()
for item in data["items"]["results"]:
print(item["title"])
const response = await fetch(
"https://api.getmatter.com/public/v1/search?query=machine+learning&type=items&status=queue",
{ headers: { Authorization: `Bearer ${token}` } }
);
const data = await response.json();
data.items.results.forEach(item => console.log(item.title));
{
"object": "search_results",
"items": {
"object": "list",
"results": [
{
"object": "item",
"id": "itm_r9f3a",
"title": "Introduction to Machine Learning",
"url": "https://example.com/intro-ml",
"site_name": "example.com",
"author": {
"object": "author",
"id": "aut_p4w7q",
"name": "Jane Smith"
},
"status": "queue",
"is_favorite": false,
"content_type": "article",
"processing_status": "completed",
"word_count": 4200,
"reading_progress": 0.35,
"image_url": null,
"library_position": 58974321000,
"inbox_position": null,
"tags": [],
"updated_at": "2026-03-30T19:15:00Z"
},
{
"object": "item",
"id": "itm_k4m2n",
"title": "Neural Networks from Scratch",
"url": "https://example.com/nn-scratch",
"site_name": "example.com",
"author": null,
"status": null,
"is_favorite": false,
"content_type": "article",
"processing_status": "completed",
"word_count": 8100,
"reading_progress": 0.0,
"image_url": null,
"library_position": null,
"inbox_position": null,
"tags": [],
"updated_at": "2026-03-28T12:00:00Z"
}
],
"has_more": false,
"next_cursor": null
}
}