Skip to main content
This guide walks you through the basics: authenticating, saving an item, listing your library, and creating an annotation.

​
Prerequisites

Set your token as an environment variable so you can copy-paste the examples: 
export MATTER_TOKEN="mat_your_token_here"

​
1. Verify your token

curl https://api.getmatter.com/public/v1/me \
  -H "Authorization: Bearer $MATTER_TOKEN"
Response
{
  "object": "account",
  "id": "act_k8x2m",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "is_pro": true,
  "rate_limit": {
    "read": 120,
    "write": 30
  }
}

​
2. Save an article

curl -X POST https://api.getmatter.com/public/v1/items \
  -H "Authorization: Bearer $MATTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://paulgraham.com/greatwork.html", "status": "queue"}'
Response
{
  "object": "item",
  "id": "itm_r9f3a",
  "title": "How to Do Great Work",
  "url": "https://paulgraham.com/greatwork.html",
  "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"
}
If processing_status is "processing", the content is being extracted in the background. Poll GET /items/{id} until it becomes "completed" (typically 20-60 seconds).
If the URL is already in your library, the existing item is returned instead of creating a duplicate. The response status will be 200 instead of 201.

​
3. List your library

curl "https://api.getmatter.com/public/v1/items?status=queue&limit=5" \
  -H "Authorization: Bearer $MATTER_TOKEN"
Response
{
  "object": "list",
  "results": [
    {
      "object": "item",
      "id": "itm_r9f3a",
      "title": "How to Do Great Work",
      "status": "queue",
      "content_type": "article"
    }
  ],
  "has_more": false,
  "next_cursor": null
}

​
4. Tag the article

curl -X POST https://api.getmatter.com/public/v1/items/itm_r9f3a/tags \
  -H "Authorization: Bearer $MATTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "essays"}'
Response
{
  "object": "tag",
  "id": "tag_n5j2x",
  "name": "essays"
}

​
5. Archive when done

curl -X PATCH https://api.getmatter.com/public/v1/items/itm_r9f3a \
  -H "Authorization: Bearer $MATTER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "archive"}'
Response
{
  "object": "item",
  "id": "itm_r9f3a",
  "status": "archive",
  "updated_at": "2026-03-30T20:30:00Z"
}

​
Next steps

Pagination

Efficiently page through large libraries.

Incremental sync

Pull only items that changed since your last sync.

Rate limits

Understand request quotas and how to stay within them.

Full API reference

Every endpoint, parameter, and response field.