Skip to main content
POST
/
v1
/
items
curl -X POST https://api.getmatter.com/public/v1/items \
  -H "Authorization: Bearer mat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://paulgraham.com/greatwork.html", "status": "queue"}'

{
  "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",
  "processing_status": "completed",
  "is_favorite": false,
  "content_type": "article",
  "word_count": 11842,
  "reading_progress": 0.0,
  "image_url": null,
  "tags": [],
  "updated_at": "2026-03-30T18:30: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.

Saving an item triggers content extraction in the background. The item is returned immediately, but metadata fields like title, author, and word_count may not be available until processing completes. Check the processing_status field to know when the item is ready:
StatusMeaning
completedContent has been extracted. All fields are populated.
processingExtraction is in progress. Poll GET /items/{id} to check for completion.
failedExtraction failed (e.g., site is unreachable or unsupported).
About 40% of saves complete instantly (cached content). For the rest, processing typically takes 20-60 seconds. Save requests count against a separate rate limit tier (10/min).

​
Body Parameters

​
url
string
required
The URL to save. Must be a valid http:// or https:// URL.
​
status
string
default:"queue"
Where to place the item. One of queue or archive.

​
Response

Returns the item with status 201. If the URL is already in your library, the existing item is returned with status 200. 
curl -X POST https://api.getmatter.com/public/v1/items \
  -H "Authorization: Bearer mat_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://paulgraham.com/greatwork.html", "status": "queue"}'

{
  "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",
  "processing_status": "completed",
  "is_favorite": false,
  "content_type": "article",
  "word_count": 11842,
  "reading_progress": 0.0,
  "image_url": null,
  "tags": [],
  "updated_at": "2026-03-30T18:30:00Z"
}