Quickstart

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

Prerequisites

A Matter account with an active Pro subscription
An API token

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.

Getting Started

Concepts

API Reference

Prerequisites

1. Verify your token

2. Save an article

3. List your library

4. Tag the article

5. Archive when done

Next steps

Pagination

Incremental sync

Rate limits

Full API reference

​Prerequisites

​1. Verify your token

​2. Save an article

​3. List your library

​4. Tag the article

​5. Archive when done

​Next steps

Pagination

Incremental sync

Rate limits

Full API reference

Prerequisites

1. Verify your token

2. Save an article

3. List your library

4. Tag the article

5. Archive when done

Next steps