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

{
  "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

​
query
string
required
Search query string (min 2 characters). Supports operators:
  • "exact phrase" — required phrase match
  • -excluded — exclude articles containing a term
  • by:author — filter by author or publisher name
  • site:domain — filter by domain or publisher
  • title:word — match in title only
Examples: machine learning, "deep work", by:graham site:paulgraham.com
​
type
string
required
Comma-separated list of result types to include. Currently supported: items.
​
status
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 only
  • archive — archived items only
  • queue,archive — both queue and archive
​
limit
integer
default:25
Maximum results per type. Min 1, max 100.
​
cursor
string
Cursor for the next page of results. Obtained from next_cursor in a previous response.

​
Response

​
object
string
required
Always "search_results".
​
items
object
Matching items, ranked by relevance. Present when items is in the type parameter.
curl "https://api.getmatter.com/public/v1/search?query=machine+learning&type=items&status=queue" \
  -H "Authorization: Bearer mat_your_token_here"

{
  "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
  }
}