> ## 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.

# Quickstart

> Save your first article and retrieve your library in under 5 minutes.

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](https://web.getmatter.com/settings)
* An [API token](/api/authentication)

Set your token as an environment variable so you can copy-paste the examples:

```bash theme={null}
export MATTER_TOKEN="mat_your_token_here"
```

## 1. Verify your token

```bash theme={null}
curl https://api.getmatter.com/public/v1/me \
  -H "Authorization: Bearer $MATTER_TOKEN"
```

```json Response theme={null}
{
  "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

```bash theme={null}
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"}'
```

```json Response theme={null}
{
  "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"
}
```

<Tip>
  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).
</Tip>

<Tip>
  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`.
</Tip>

## 3. List your library

```bash theme={null}
curl "https://api.getmatter.com/public/v1/items?status=queue&limit=5" \
  -H "Authorization: Bearer $MATTER_TOKEN"
```

```json Response theme={null}
{
  "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

```bash theme={null}
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"}'
```

```json Response theme={null}
{
  "object": "tag",
  "id": "tag_n5j2x",
  "name": "essays"
}
```

## 5. Archive when done

```bash theme={null}
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"}'
```

```json Response theme={null}
{
  "object": "item",
  "id": "itm_r9f3a",
  "status": "archive",
  "updated_at": "2026-03-30T20:30:00Z"
}
```

## Next steps

<CardGroup cols={2}>
  <Card title="Pagination" icon="arrow-right" href="/api/pagination">
    Efficiently page through large libraries.
  </Card>

  <Card title="Incremental sync" icon="rotate" href="/api/pagination#incremental-sync">
    Pull only items that changed since your last sync.
  </Card>

  <Card title="Rate limits" icon="gauge" href="/api/rate-limits">
    Understand request quotas and how to stay within them.
  </Card>

  <Card title="Full API reference" icon="book" href="/api">
    Every endpoint, parameter, and response field.
  </Card>
</CardGroup>