Skip to main content
GET
/
v1
/
items
/
{id}
curl https://api.getmatter.com/public/v1/items/itm_r9f3a \
  -H "Authorization: Bearer mat_your_token_here"

{
  "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",
  "excerpt": "Paul Graham explores what it takes to do great work...",
  "library_position": 58974321000,
  "inbox_position": null,
  "tags": [
    {
      "object": "tag",
      "id": "tag_n5j2x",
      "name": "essays"
    }
  ],
  "updated_at": "2026-03-30T19:15:00Z"
}

Documentation Index

Fetch the complete documentation index at: https://docs.getmatter.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Path Parameters

​
id
string
required
The item ID. Example: itm_r9f3a.

​
Query Parameters

​
include
string
Comma-separated list of additional fields to include. Currently supported: markdown.When markdown is included, the response adds a markdown field with the parsed article body. These requests count against the content rate limit (20/min).

​
Response

​
object
string
required
Always "item".
​
id
string
required
The item ID.
​
title
string
required
The item’s title.
​
url
string
required
The original URL of the item.
​
site_name
string
The source website name.
​
author
object
The item’s author, if known.
​
status
string
required
One of inbox, queue, or archive.
​
processing_status
string
required
Content extraction status. One of processing, completed, or failed. See Save Item for details.
​
is_favorite
boolean
required
Whether the item is favorited.
​
content_type
string
required
One of article, video, podcast, pdf, tweet, newsletter.
​
word_count
integer
Estimated word count. null for non-text content.
​
reading_progress
number
required
Reading progress as a float from 0.0 to 1.0.
​
image_url
string
URL of the item’s hero image, if available.
​
markdown
string
The parsed article body as markdown. Only included when ?include=markdown is set. null if the item hasn’t been processed yet.
​
excerpt
string
Short excerpt or description of the item, if available.
​
library_position
integer
The item’s position in the library (queue/archive). Non-null when the item has a library entry. Higher values are closer to the top. Use this to recreate library order locally.
​
inbox_position
integer
The item’s 0-based index in the inbox feed. Non-null when the item is in the inbox. Lower values are closer to the top. Use this to recreate inbox order locally.
​
tags
array
required
Tags applied to this item.
​
updated_at
string
required
ISO 8601 timestamp of the last change to this item or its associated data (status, reading progress, favorites, tags, annotations, or content re-extraction). For inbox items with no interactions, this is the time the item appeared in your inbox.
curl https://api.getmatter.com/public/v1/items/itm_r9f3a \
  -H "Authorization: Bearer mat_your_token_here"

{
  "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",
  "excerpt": "Paul Graham explores what it takes to do great work...",
  "library_position": 58974321000,
  "inbox_position": null,
  "tags": [
    {
      "object": "tag",
      "id": "tag_n5j2x",
      "name": "essays"
    }
  ],
  "updated_at": "2026-03-30T19:15:00Z"
}