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