Items
Save Item
Save a new item to your library by URL.
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"}'
import requests
import time
# Save the item
response = requests.post(
"https://api.getmatter.com/public/v1/items",
headers={
"Authorization": f"Bearer {token}",
"Content-Type": "application/json"
},
json={"url": "https://paulgraham.com/greatwork.html", "status": "queue"}
)
item = response.json()
# Poll until processing completes (if needed)
while item["processing_status"] == "processing":
time.sleep(5)
item = requests.get(
f"https://api.getmatter.com/public/v1/items/{item['id']}",
headers={"Authorization": f"Bearer {token}"}
).json()
print(item["title"]) # "How to Do Great Work"
const response = await fetch("https://api.getmatter.com/public/v1/items", {
method: "POST",
headers: {
Authorization: `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({ url: "https://paulgraham.com/greatwork.html", status: "queue" })
});
const item = await response.json();
{
"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"
}
{
"object": "item",
"id": "itm_r9f3a",
"url": "https://paulgraham.com/greatwork.html",
"status": "queue",
"processing_status": "processing",
"title": null,
"author": null,
"site_name": null,
"content_type": null,
"word_count": null,
"is_favorite": false,
"reading_progress": 0.0,
"image_url": null,
"tags": [],
"updated_at": "2026-03-30T18:30:00Z"
}
{
"error": {
"code": "unprocessable",
"message": "URL must start with http:// or https://.",
"field": "url"
}
}
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:
| Status | Meaning |
|---|---|
completed | Content has been extracted. All fields are populated. |
processing | Extraction is in progress. Poll GET /items/{id} to check for completion. |
failed | Extraction 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
string
required
The URL to save. Must be a valid
http:// or https:// URL.string
default:"queue"
Where to place the item. One of
queue or archive.Response
Returns the item with status201. 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"}'
import requests
import time
# Save the item
response = requests.post(
"https://api.getmatter.com/public/v1/items",
headers={
"Authorization": f"Bearer {token}",
"Content-Type": "application/json"
},
json={"url": "https://paulgraham.com/greatwork.html", "status": "queue"}
)
item = response.json()
# Poll until processing completes (if needed)
while item["processing_status"] == "processing":
time.sleep(5)
item = requests.get(
f"https://api.getmatter.com/public/v1/items/{item['id']}",
headers={"Authorization": f"Bearer {token}"}
).json()
print(item["title"]) # "How to Do Great Work"
const response = await fetch("https://api.getmatter.com/public/v1/items", {
method: "POST",
headers: {
Authorization: `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({ url: "https://paulgraham.com/greatwork.html", status: "queue" })
});
const item = await response.json();
{
"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"
}
{
"object": "item",
"id": "itm_r9f3a",
"url": "https://paulgraham.com/greatwork.html",
"status": "queue",
"processing_status": "processing",
"title": null,
"author": null,
"site_name": null,
"content_type": null,
"word_count": null,
"is_favorite": false,
"reading_progress": 0.0,
"image_url": null,
"tags": [],
"updated_at": "2026-03-30T18:30:00Z"
}
{
"error": {
"code": "unprocessable",
"message": "URL must start with http:// or https://.",
"field": "url"
}
}
⌘I
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"}'
import requests
import time
# Save the item
response = requests.post(
"https://api.getmatter.com/public/v1/items",
headers={
"Authorization": f"Bearer {token}",
"Content-Type": "application/json"
},
json={"url": "https://paulgraham.com/greatwork.html", "status": "queue"}
)
item = response.json()
# Poll until processing completes (if needed)
while item["processing_status"] == "processing":
time.sleep(5)
item = requests.get(
f"https://api.getmatter.com/public/v1/items/{item['id']}",
headers={"Authorization": f"Bearer {token}"}
).json()
print(item["title"]) # "How to Do Great Work"
const response = await fetch("https://api.getmatter.com/public/v1/items", {
method: "POST",
headers: {
Authorization: `Bearer ${token}`,
"Content-Type": "application/json"
},
body: JSON.stringify({ url: "https://paulgraham.com/greatwork.html", status: "queue" })
});
const item = await response.json();
{
"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"
}
{
"object": "item",
"id": "itm_r9f3a",
"url": "https://paulgraham.com/greatwork.html",
"status": "queue",
"processing_status": "processing",
"title": null,
"author": null,
"site_name": null,
"content_type": null,
"word_count": null,
"is_favorite": false,
"reading_progress": 0.0,
"image_url": null,
"tags": [],
"updated_at": "2026-03-30T18:30:00Z"
}
{
"error": {
"code": "unprocessable",
"message": "URL must start with http:// or https://.",
"field": "url"
}
}