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

## 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](https://docs.getmatter.com/api/authentication.md) 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

> [card] [Quickstart](https://docs.getmatter.com/api/quickstart.md)
>
> Save your first article and retrieve your library in under 5 minutes.

> [card] [Authentication](https://docs.getmatter.com/api/authentication.md)
>
> Generate and manage your API token.

> [card] [IDs & Object Types](https://docs.getmatter.com/api/ids.md)
>
> How resources are identified in the API.

## Concepts

> [card] [Pagination](https://docs.getmatter.com/api/pagination.md)
>
> Cursor-based pagination and incremental sync.

> [card] [Rate Limits](https://docs.getmatter.com/api/rate-limits.md)
>
> Request quotas and how to handle throttling.

> [card] [Errors](https://docs.getmatter.com/api/errors.md)
>
> Error codes, status codes, and how to handle them.

> [card] [Versioning](https://docs.getmatter.com/api/versioning.md)
>
> API versioning and compatibility guarantees.

## API Reference

> [card] [Items](https://docs.getmatter.com/api/items/list.md)
>
> Articles, podcasts, videos, and everything in your library.

> [card] [Annotations](https://docs.getmatter.com/api/annotations/list.md)
>
> Text highlights and notes you've made while reading.

> [card] [Tags](https://docs.getmatter.com/api/tags/list.md)
>
> Labels you use to organize items in your library.

> [card] [Search](https://docs.getmatter.com/api/search.md)
>
> Full-text search across your library.

> [card] [Account](https://docs.getmatter.com/api/account/get-me.md)
>
> Your profile and API quota.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.