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

# Matter API

> REST API for saving articles, managing annotations, organizing tags, and syncing your Matter reading library.

The Matter API gives you full read/write access to your library. Save articles, manage annotations, organize with tags, and sync your reading data with any tool you use.

<Note>The API requires a Matter Pro subscription. [Upgrade to Pro](https://web.getmatter.com/settings) to get started.</Note>

## Base URL

```
https://api.getmatter.com/public/v1/
```

## Authentication

All endpoints require a Bearer token in the `Authorization` header:

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

See [Authentication](/api/authentication) for details on generating and managing tokens.

## Request format

* All request bodies must be JSON with `Content-Type: application/json`
* Query parameters are used for filtering and pagination
* IDs in URLs are prefixed strings (e.g., `itm_r9f3a`)

## Response format

All responses are JSON. Every object includes an `object` field identifying its type.

**Single resource:**

```json theme={null}
{
  "object": "item",
  "id": "itm_r9f3a",
  "title": "Example Article"
}
```

**List of resources:**

```json theme={null}
{
  "object": "list",
  "results": [...],
  "has_more": true,
  "next_cursor": "eyJpZCI6MTIzNH0="
}
```

**Error:**

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "No item found with ID itm_abc123."
  }
}
```

## Getting started

<CardGroup cols={2}>
  <Card title="Quickstart" icon="rocket" href="/api/quickstart">
    Save your first article and retrieve your library in under 5 minutes.
  </Card>

  <Card title="Authentication" icon="key" href="/api/authentication">
    Generate and manage your API token.
  </Card>

  <Card title="IDs & Object Types" icon="fingerprint" href="/api/ids">
    How resources are identified in the API.
  </Card>
</CardGroup>

## Concepts

<CardGroup cols={2}>
  <Card title="Pagination" icon="arrow-right" href="/api/pagination">
    Cursor-based pagination and incremental sync.
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/api/rate-limits">
    Request quotas and how to handle throttling.
  </Card>

  <Card title="Errors" icon="circle-exclamation" href="/api/errors">
    Error codes, status codes, and how to handle them.
  </Card>

  <Card title="Versioning" icon="code-branch" href="/api/versioning">
    API versioning and compatibility guarantees.
  </Card>
</CardGroup>

## API Reference

<CardGroup cols={2}>
  <Card title="Items" icon="book-open" href="/api/items/list">
    Articles, podcasts, videos, and everything in your library.
  </Card>

  <Card title="Annotations" icon="highlighter" href="/api/annotations/list">
    Text highlights and notes you've made while reading.
  </Card>

  <Card title="Tags" icon="tag" href="/api/tags/list">
    Labels you use to organize items in your library.
  </Card>

  <Card title="Search" icon="magnifying-glass" href="/api/search">
    Full-text search across your library.
  </Card>

  <Card title="Account" icon="user" href="/api/account/get-me">
    Your profile and API quota.
  </Card>
</CardGroup>