Matter

https://docs.getmatter.com
Admin
Matter is a read-later app for saving articles, newsletters, PDFs, and other content with...
Tokens:33,159
Snippets:292
Trust Score:7.5
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Matter CLI from Source

Source: https://docs.getmatter.com/cli/quickstart

Clone the repository, install dependencies, and run the CLI from source. Useful for development or if direct installation fails.

```bash
git clone https://github.com/getmatterapp/matter-cli.git
cd matter-cli
bun install
bun run src/cli.tsx --help
```

--------------------------------

### Install Matter CLI on Windows

Source: https://docs.getmatter.com/cli/quickstart

Use this command to install the Matter CLI on Windows systems using PowerShell.

```powershell
irm https://cli.getmatter.com/install.ps1 | iex
```

--------------------------------

### Get Current Account Information (JavaScript)

Source: https://docs.getmatter.com/api/account/get-me

This JavaScript example shows how to fetch your account details using the `fetch` API. Make sure to include your API token in the `Authorization` header.

```javascript
const response = await fetch("https://api.getmatter.com/public/v1/me", {
  headers: { Authorization: `Bearer ${token}` }
});
const account = await response.json();
```

--------------------------------

### API Endpoint Examples

Source: https://docs.getmatter.com/api/versioning

Examples of API endpoints showing the version in the URL path.

```text
GET  https://api.getmatter.com/public/v1/items
POST https://api.getmatter.com/public/v1/items
GET  https://api.getmatter.com/public/v1/me
```

--------------------------------

### Plain Text Output Example

Source: https://docs.getmatter.com/cli/quickstart

Use the `--plain` flag to get human-readable table output for commands that list items.

```text
itm_r9f3a  How to Do Great Work          paulgraham.com  queue     35%
itm_k8w2p  The Art of Finishing           example.com     archive  100%
```

--------------------------------

### Example Endpoints

Source: https://docs.getmatter.com/api/versioning

Examples of how endpoints are structured with the version in the URL path.

```APIDOC
GET https://api.getmatter.com/public/v1/items
POST https://api.getmatter.com/public/v1/items
GET https://api.getmatter.com/public/v1/me
```

--------------------------------

### Example API Token Format

Source: https://docs.getmatter.com/api/authentication

Matter API tokens start with the 'mat_' prefix.

```text
mat_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6q7r8
```

--------------------------------

### Install Matter CLI on macOS / Linux

Source: https://docs.getmatter.com/cli/quickstart

Use this command to install the Matter CLI on macOS or Linux systems using curl.

```bash
curl -fsSL https://cli.getmatter.com/install.sh | sh
```

--------------------------------

### Incremental Sync Example

Source: https://docs.getmatter.com/api/pagination

Demonstrates how to perform an incremental sync using the 'updated_since' parameter and position fields for local sorting.

```APIDOC
## Incremental Sync

### Description
This section provides a Python example for performing an incremental sync of items. It fetches only changed items since the last sync using `updated_since` and then sorts them locally using the `library_position` and `inbox_position` fields.

### Method
GET (for fetching changed items)

### Endpoint
/public/v1/items

### Query Parameters
- **updated_since** (string) - Required for incremental sync - Timestamp to fetch items updated after.
- **limit** (integer) - Optional - Maximum number of items to return per request.

### Request Example (Python)
```python
# Assuming 'fetch_all_pages' is a function that handles pagination and API calls
# Assuming 'last_sync' is a variable holding the timestamp of the last sync

params = {"updated_since": last_sync, "limit": 100}
changed_items = fetch_all_pages(params)

# Update local database with changed items
for item in changed_items:
    local_db[item["id"]] = item

# Display queue items in app order using position fields
queue_items = sorted(
    [i for i in local_db.values() if i["status"] == "queue"],
    key=lambda i: i["library_position"] or 0,
    reverse=True,
)

# Display inbox items in feed order using position fields
inbox_items = sorted(
    [i for i in local_db.values() if i["status"] == "inbox"],
    key=lambda i: i["inbox_position"] or 0,
)
```

### Response
#### Success Response (200)
- **items** (array) - A list of items updated since the `updated_since` timestamp.
- **library_position** (integer) - The manual position of the item in the library.
- **inbox_position** (integer) - The position of the item in the inbox feed.
- **updated_at** (string) - The timestamp when the item was last updated.
```

--------------------------------

### API Base URL Example

Source: https://docs.getmatter.com/api/versioning

This is the base URL for the API, including the version.

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

--------------------------------

### Get Account Info

Source: https://docs.getmatter.com/cli/commands

Fetches your account details, including name, email, and Pro status. Use --plain for human-readable output.

```bash
matter account              # JSON
matter account --plain      # Human-readable
```

--------------------------------

### Deprecation Headers Example

Source: https://docs.getmatter.com/api/versioning

Headers indicating a version is deprecated and its sunset date.

```text
Sunset: Sat, 01 Nov 2027 00:00:00 GMT
Deprecation: true
```

--------------------------------

### Search for Items using JavaScript

Source: https://docs.getmatter.com/api/search

This JavaScript example shows how to perform a search using the `fetch` API. Replace `token` with your Matter API key and handle the response data as required.

```javascript
const response = await fetch(
  "https://api.getmatter.com/public/v1/search?query=machine+learning&type=items&status=queue",
  { headers: { Authorization: `Bearer ${token}` } }
);
const data = await response.json();
data.items.results.forEach(item => console.log(item.title));
```

--------------------------------

### JSON Output Example

Source: https://docs.getmatter.com/cli/quickstart

The default output format for the Matter CLI is JSON, which is suitable for scripting and piping data to other tools.

```json
{
  "object": "list",
  "results": [...],
  "has_more": true,
  "next_cursor": "cur_abc123"
}
```

--------------------------------

### Update Annotation Response Example

Source: https://docs.getmatter.com/api/annotations/update

This is an example of a successful response (200 OK) after updating an annotation. It returns the full annotation object, including the updated `note` field.

```json
{
  "object": "annotation",
  "id": "ann_m2k8v",
  "item_id": "itm_r9f3a",
  "text": "The way to figure out what to work on is by working.",
  "note": "Core thesis of the essay",
  "created_at": "2026-03-30T18:32:00Z",
  "updated_at": "2026-03-30T20:45:00Z"
}
```

--------------------------------

### Authentication Example

Source: https://docs.getmatter.com/api

All endpoints require a Bearer token in the Authorization header. See Authentication for details on generating and managing tokens.

```APIDOC
## Authentication Example

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

--------------------------------

### Search for Items using Python

Source: https://docs.getmatter.com/api/search

This Python script demonstrates how to search for items using the `requests` library. Ensure you have the library installed and replace `token` with your Matter API key.

```python
import requests

response = requests.get(
    "https://api.getmatter.com/public/v1/search",
    headers={"Authorization": f"Bearer {token}"},
    params={"query": "machine learning", "type": "items", "status": "queue"}
)
data = response.json()
for item in data["items"]["results"]:
    print(item["title"])
```

--------------------------------

### Get a Specific Item

Source: https://docs.getmatter.com/cli/quickstart

Retrieve detailed information about a specific item using its ID with the `matter items get` command.

```bash
matter items get itm_r9f3a
```

--------------------------------

### Item Not Found Response

Source: https://docs.getmatter.com/api/items/get

This example shows the JSON response when an item with the specified ID is not found.

```json
{
  "message": "No item found with ID itm_abc123."
}
```

--------------------------------

### Get Current Account Information (cURL)

Source: https://docs.getmatter.com/api/account/get-me

Use this cURL command to fetch your account details. Ensure you replace `mat_your_token_here` with your actual API token.

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

--------------------------------

### Get Item

Source: https://docs.getmatter.com/llms.txt

Returns a single item from your library with full metadata.

```APIDOC
## Get Item

### Description
Returns a single item from your library with full metadata.

### Method
GET

### Endpoint
/items/get
```

--------------------------------

### List Object Example

Source: https://docs.getmatter.com/api/ids

This JSON structure represents a list of resources, showing pagination details and individual item objects.

```json
{
  "object": "list",
  "results": [
    { "object": "item", "id": "itm_r9f3a" },
    { "object": "item", "id": "itm_x7k2p" }
  ],
  "has_more": false,
  "next_cursor": null
}
```

--------------------------------

### Get Current Account Information (Python)

Source: https://docs.getmatter.com/api/account/get-me

This Python script demonstrates how to retrieve your account information using the `requests` library. You need to provide your API token in the `Authorization` header.

```python
import requests

response = requests.get(
    "https://api.getmatter.com/public/v1/me",
    headers={"Authorization": f"Bearer {token}"}
)
account = response.json()
```

--------------------------------

### List Reading Sessions (cURL)

Source: https://docs.getmatter.com/api/reading-sessions/list

Make a GET request to the reading sessions endpoint. Include your API token in the Authorization header. This is the basic request to fetch sessions.

```bash
curl "https://api.getmatter.com/public/v1/reading_sessions" \
  -H "Authorization: Bearer mat_your_token_here"
```

--------------------------------

### Get items in manual library order

Source: https://docs.getmatter.com/api/pagination

Use the `order=library_position` parameter to retrieve items sorted according to manual library ordering. Requires an `Authorization` header.

```bash
curl "https://api.getmatter.com/public/v1/items?order=library_position" \
  -H "Authorization: Bearer $MATTER_TOKEN"
```

--------------------------------

### Set API Token Environment Variable

Source: https://docs.getmatter.com/api/quickstart

Set your API token as an environment variable to use it in subsequent examples. Ensure you replace 'mat_your_token_here' with your actual token.

```bash
export MATTER_TOKEN="mat_your_token_here"
```

--------------------------------

### Item Object Example

Source: https://docs.getmatter.com/api/ids

This JSON structure represents a single item resource, including its object type and ID.

```json
{
  "object": "item",
  "id": "itm_r9f3a",
  "title": "How to Do Great Work"
}
```

--------------------------------

### UTC Timestamp Example

Source: https://docs.getmatter.com/api/ids

All timestamps are formatted as ISO 8601 strings in UTC.

```text
2026-03-30T18:30:00Z
```

--------------------------------

### Get All Library Items (Queue + Archive) in Manual Order

Source: https://docs.getmatter.com/api/pagination

Retrieves all items from the queue and archive, sorted manually by library position.

```APIDOC
## GET /public/v1/items?order=library_position

### Description
Retrieves all library items (queue and archive) sorted in manual order based on their library position.

### Method
GET

### Endpoint
/public/v1/items?order=library_position

### Query Parameters
- **order** (string) - Required - Specifies the sorting order. Use 'library_position' for manual ordering.

### Request Example
```bash
curl "https://api.getmatter.com/public/v1/items?order=library_position" \
  -H "Authorization: Bearer $MATTER_TOKEN"
```

### Response
#### Success Response (200)
- **items** (array) - A list of library items.
- **library_position** (integer) - The manual position of the item in the library.
- **inbox_position** (integer) - The position of the item in the inbox feed.

#### Response Example
```json
{
  "items": [
    {
      "id": "item_id_1",
      "library_position": 1,
      "inbox_position": 5,
      "status": "queue",
      "updated_at": "2023-10-27T10:00:00Z"
    },
    {
      "id": "item_id_2",
      "library_position": 2,
      "inbox_position": 3,
      "status": "queue",
      "updated_at": "2023-10-26T12:00:00Z"
    }
  ]
}
```
```

--------------------------------

### Handling Errors Programmatically

Source: https://docs.getmatter.com/api/errors

This Python example demonstrates how to check for API errors, parse the error response, and implement retry logic for rate-limited requests or specific error handling for validation errors.

```APIDOC
## Handling errors

```python
import requests
import time

response = requests.post(url, headers=headers, json=data)

if response.status_code >= 400:
    error = response.json()["error"]
    if error["code"] == "rate_limited":
        retry_after = int(response.headers["Retry-After"])
        time.sleep(retry_after)
    elif error["code"] == "validation_error":
        print(f"Fix field '{error['field']}': {error['message']}")
    else:
        print(f"Error: {error['message']}")
```
```

--------------------------------

### Fetch First Page of Items

Source: https://docs.getmatter.com/api/pagination

Use this command to fetch the first page of items, specifying a limit for the number of results per page.

```bash
# First page
curl "https://api.getmatter.com/public/v1/items?limit=50" \
  -H "Authorization: Bearer $MATTER_TOKEN"
```

--------------------------------

### List Annotations

Source: https://docs.getmatter.com/cli/commands

Lists annotations for a specific item. Use --all to fetch all pages. --plain provides human-readable output.

```bash
matter annotations list --item <item_id> [options]
```

```bash
matter annotations list --item itm_r9f3a --plain
```

```bash
matter annotations list --item itm_r9f3a --all
```

--------------------------------

### Fetch an Item using Python

Source: https://docs.getmatter.com/api/items/get

This Python script demonstrates how to fetch an item and its markdown content using the `requests` library. Ensure you replace `token` with your actual API key.

```python
import requests

response = requests.get(
    "https://api.getmatter.com/public/v1/items/itm_r9f3a",
    headers={"Authorization": f"Bearer {token}"},
    params={"include": "markdown"}
)
item = response.json()
```

--------------------------------

### Get Annotation

Source: https://docs.getmatter.com/llms.txt

Returns a single annotation.

```APIDOC
## Get Annotation

### Description
Returns a single annotation.

### Method
GET

### Endpoint
/annotations/get
```

--------------------------------

### Get Annotation

Source: https://docs.getmatter.com/cli/commands

Retrieves a specific annotation by its ID.

```bash
matter annotations get <id>
```

```bash
matter annotations get ann_k3m9p
```

--------------------------------

### Get an Item

Source: https://docs.getmatter.com/cli/commands

Retrieves a specific item by its ID.

```APIDOC
## Get an Item

### Description
Retrieves a specific item by its ID.

### Method
`matter items get <id>`

### Parameters
#### Path Parameters
- **id** (string) - Required - The ID of the item to retrieve.

### Example
```bash
matter items get <id>
matter items get itm_r9f3a --plain
```
```

--------------------------------

### Update Annotation

Source: https://docs.getmatter.com/cli/commands

Updates an existing annotation, for example, its note.

```APIDOC
## Update Annotation

### Description
Updates an existing annotation, for example, its note.

### Method
`matter annotations update`

### Parameters
#### Path Parameters
- **id** (string) - Required - Annotation ID

#### Query Parameters
- **note** (string) - Optional - The updated note for the annotation

### Request Example
```bash
matter annotations update <id> --note "Updated note"
```
```

--------------------------------

### Paginate List Commands

Source: https://docs.getmatter.com/cli/quickstart

Use cursor-based pagination with `--limit` and `--cursor` for fetching lists of items. The `--all` flag fetches all pages at once.

```bash
# First page
matter items list --limit 10
```

```bash
# Next page (use next_cursor from previous response)
matter items list --limit 10 --cursor <cursor>
```

```bash
# Fetch all pages at once
matter items list --all
```

--------------------------------

### Save a URL as an Item

Source: https://docs.getmatter.com/cli/commands

Saves a given URL as a new item. Optionally set the initial status to 'queue' or 'archive'.

```bash
matter items save --url <url> [--status queue|archive]
```

```bash
matter items save --url "https://example.com/article"
matter items save --url "https://example.com/article" --status queue
```

--------------------------------

### Use .env Files for Local Development

Source: https://docs.getmatter.com/api/authentication

For local development, use a .env file to store your API token. Ensure this file is added to your .gitignore to prevent accidental commits.

```bash
# .env (add to .gitignore!)
MATTER_API_TOKEN=mat_your_token_here
```

--------------------------------

### Check Account Information

Source: https://docs.getmatter.com/cli/quickstart

Use the `matter account --plain` command to quickly check your account details in a human-readable format.

```bash
matter account --plain
```

--------------------------------

### Get Current Account

Source: https://docs.getmatter.com/llms.txt

Returns the authenticated user's account information and API quota.

```APIDOC
## Get Current Account

### Description
Returns the authenticated user's account information and API quota.

### Method
GET

### Endpoint
/account/get-me
```

--------------------------------

### Show Version

Source: https://docs.getmatter.com/cli/commands

Displays the current version of the Matter CLI.

```APIDOC
## Show Version

### Description
Displays the current version of the Matter CLI.

### Method
`matter version`
```

--------------------------------

### Get Inbox Items in Feed Order

Source: https://docs.getmatter.com/api/pagination

Retrieves items from the inbox, sorted by their position in the feed (newest first).

```APIDOC
## GET /public/v1/items?order=inbox_position

### Description
Retrieves items from the inbox, sorted by their position in the feed (newest first).

### Method
GET

### Endpoint
/public/v1/items?order=inbox_position

### Query Parameters
- **order** (string) - Required - Specifies the sorting order. Use 'inbox_position' for feed ordering.

### Request Example
```bash
curl "https://api.getmatter.com/public/v1/items?order=inbox_position" \
  -H "Authorization: Bearer $MATTER_TOKEN"
```

### Response
#### Success Response (200)
- **items** (array) - A list of inbox items.
- **library_position** (integer) - The manual position of the item in the library.
- **inbox_position** (integer) - The position of the item in the inbox feed.

#### Response Example
```json
{
  "items": [
    {
      "id": "item_id_1",
      "library_position": 5,
      "inbox_position": 1,
      "status": "inbox",
      "updated_at": "2023-10-27T14:00:00Z"
    },
    {
      "id": "item_id_2",
      "library_position": 3,
      "inbox_position": 2,
      "status": "inbox",
      "updated_at": "2023-10-27T13:00:00Z"
    }
  ]
}
```
```

--------------------------------

### List All Tags

Source: https://docs.getmatter.com/api/tags/list

Use this cURL command to fetch all tags from your library. Ensure you replace `mat_your_token_here` with your actual API token.

```bash
curl https://api.getmatter.com/public/v1/tags \
  -H "Authorization: Bearer mat_your_token_here"
```

--------------------------------

### Get Current Account Information

Source: https://docs.getmatter.com/api/account/get-me

Retrieves the authenticated user's account details and API quota information.

```APIDOC
## GET /public/v1/me

### Description
Returns the authenticated user's account information and API quota.

### Method
GET

### Endpoint
https://api.getmatter.com/public/v1/me

### Request Headers
- **Authorization** (string, required): Bearer mat_your_token_here

### Response
#### Success Response (200)
- **object** (string): Always "account".
- **id** (string): The account ID. Example: `act_k8x2m`.
- **name** (string): The user's display name.
- **email** (string): The user's email address.
- **rate_limit** (object): Rate limit quotas (requests per minute unless noted).
  - **read** (integer): All GET requests.
  - **write** (integer): POST, PATCH, DELETE requests.
  - **save** (integer): POST /items (each triggers extraction).
  - **markdown** (integer): GET requests with ?include=markdown.
  - **burst** (integer): Per-second ceiling across all requests.
- **created_at** (string): ISO 8601 timestamp of account creation.

### Response Example
```json
{
  "object": "account",
  "id": "act_k8x2m",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "rate_limit": {
    "read": 120,
    "write": 30,
    "save": 10,
    "search": 30,
    "markdown": 20,
    "burst": 5
  },
  "created_at": "2024-06-15T10:30:00Z"
}
```
```

--------------------------------

### List Tags

Source: https://docs.getmatter.com/cli/commands

Lists all available tags. Use --plain for human-readable output.

```bash
matter tags list
```

```bash
matter tags list --plain
```

--------------------------------

### Login to Matter CLI

Source: https://docs.getmatter.com/cli/commands

Logs into the Matter CLI. Opens a browser for token retrieval or accepts a token directly.

```bash
matter login                # Opens browser to get token
```

```bash
matter login <token>        # Pass token directly
```

--------------------------------

### Using your token

Source: https://docs.getmatter.com/api/authentication

Pass the token in the `Authorization` header on every request.

```APIDOC
## GET /public/v1/me

### Description
Fetches information about the authenticated user.

### Method
GET

### Endpoint
https://api.getmatter.com/public/v1/me

### Parameters
#### Headers
- **Authorization** (string) - Required - The authentication token in the format `Bearer mat_your_token_here`.

### Request Example
```bash
curl https://api.getmatter.com/public/v1/me \
  -H "Authorization: Bearer mat_your_token_here"
```

### Response
#### Success Response (200)
- **field1** (type) - Description

#### Response Example
{
  "example": "response body"
}
```

--------------------------------

### Get Item Details

Source: https://docs.getmatter.com/api/items/get

Fetches the details of a specific item by its ID. You can include the markdown content by adding the `include=markdown` query parameter.

```APIDOC
## GET /items/{itemId}

### Description
Retrieves the details of a specific item.

### Method
GET

### Endpoint
`/public/v1/items/{itemId}`

### Parameters
#### Query Parameters
- **include** (string) - Optional - Include additional data. Supported values: `markdown`.

### Request Example
```bash
curl https://api.getmatter.com/public/v1/items/itm_r9f3a \
  -H "Authorization: Bearer mat_your_token_here"
```

```bash
curl "https://api.getmatter.com/public/v1/items/itm_r9f3a?include=markdown" \
  -H "Authorization: Bearer mat_your_token_here"
```

```python
import requests

token = "your_token_here"
response = requests.get(
    "https://api.getmatter.com/public/v1/items/itm_r9f3a",
    headers={"Authorization": f"Bearer {token}"},
    params={"include": "markdown"}
)
item = response.json()
```

### Response
#### Success Response (200)
- **object** (string) - Always "item".
- **id** (string) - The item ID.
- **title** (string) - The item's title.
- **url** (string) - The original URL of the item.
- **site_name** (string) - The source website name.
- **author** (object) - The item's author, if known.
  - **object** (string) - Always "author".
  - **id** (string) - Author ID.
  - **name** (string) - Author display name.
- **status** (string) - One of `inbox`, `queue`, or `archive`.
- **processing_status** (string) - Content extraction status. One of `processing`, `completed`, or `failed`.
- **is_favorite** (boolean) - Whether the item is favorited.
- **content_type** (string) - One of `article`, `video`, `podcast`, `pdf`, `tweet`, `newsletter`.
- **word_count** (integer) - Estimated word count. `null` for non-text content.
- **reading_progress** (number) - Reading progress as a float from `0.0` to `1.0`.
- **image_url** (string) - URL of the item's hero image, if available.
- **markdown** (string) - The parsed article body as markdown. Only included when `?include=markdown` is set. `null` if the item hasn't been processed yet.
- **excerpt** (string) - Short excerpt or description of the item, if available.
- **library_position** (integer) - The item's position in the library.
- **inbox_position** (integer) - The item's 0-based index in the inbox feed.
- **tags** (array) - Tags applied to this item.
  - **object** (string) - Always "tag".
  - **id** (string) - Tag ID.
  - **name** (string) - Tag name.
  - **item_count** (integer) - Number of items with this tag.
  - **created_at** (string) - ISO 8601 timestamp.
- **updated_at** (string) - ISO 8601 timestamp of the last change to this item.

#### Response Example (200)
```json
{
  "object": "item",
  "id": "itm_r9f3a",
  "title": "How to Do Great Work",
  "url": "https://paulgraham.com/greatwork.html",
  "site_name": "paulgraham.com",
  "author": {
    "object": "author",
    "id": "aut_p4w7q",
    "name": "Paul Graham"
  },
  "status": "queue",
  "is_favorite": false,
  "content_type": "article",
  "word_count": 11842,
  "reading_progress": 0.35,
  "image_url": "https://cdn.getmatter.com/images/itm_r9f3a.jpg",
  "excerpt": "Paul Graham explores what it takes to do great work...",
  "library_position": 58974321000,
  "inbox_position": null,
  "tags": [
    {
      "object": "tag",
      "id": "tag_n5j2x",
      "name": "essays"
    }
  ],
  "updated_at": "2026-03-30T19:15:00Z"
}
```

#### Error Response (404)
```json
{
  "error": {
    "code": "not_found",
```
```

--------------------------------

### Authenticate with Matter CLI

Source: https://docs.getmatter.com/cli/quickstart

Log in to the Matter CLI using your API token. This can be done interactively by opening a browser, by passing the token directly, or via piped input for automation.

```bash
# Opens browser to copy your API token
matter login
```

```bash
# Or pass a token directly
matter login mat_yourtoken
```

```bash
# Piped input (for automation)
echo "$MATTER_TOKEN" | matter login
```

--------------------------------

### Get a Single Annotation

Source: https://docs.getmatter.com/api/annotations/get

Returns a single annotation based on its ID. You need to provide the annotation ID in the path and an authorization token.

```APIDOC
## GET /public/v1/annotations/{id}

### Description
Returns a single annotation.

### Method
GET

### Endpoint
/public/v1/annotations/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The annotation ID. Example: `ann_m2k8v`.

### Response
#### Success Response (200)
- **object** (string) - Always `"annotation"`.
- **id** (string) - The annotation ID.
- **item_id** (string) - The parent item ID.
- **text** (string) - The highlighted text.
- **note** (string) - User-added note, if any.
- **created_at** (string) - ISO 8601 timestamp.
- **updated_at** (string) - ISO 8601 timestamp.

### Request Example
```bash cURL
curl https://api.getmatter.com/public/v1/annotations/ann_m2k8v \
  -H "Authorization: Bearer mat_your_token_here"
```

### Response Example
```json 200
{
  "object": "annotation",
  "id": "ann_m2k8v",
  "item_id": "itm_r9f3a",
  "text": "The way to figure out what to work on is by working.",
  "note": "Core thesis of the essay",
  "created_at": "2026-03-30T18:32:00Z",
  "updated_at": "2026-03-30T18:32:00Z"
}
```
```

--------------------------------

### Launch Interactive TUI

Source: https://docs.getmatter.com/cli/tui

Run the Matter CLI with no arguments or explicitly with `matter tui` to launch the interactive terminal user interface.

```bash
matter
matter tui
```

--------------------------------

### Validation Error Example

Source: https://docs.getmatter.com/api/errors

When a specific field in the request is invalid, the `field` property in the error response will indicate which field caused the validation error.

```APIDOC
## Validation errors

When a specific field is invalid, the `field` property tells you which one:

```json
{
  "error": {
    "code": "validation_error",
    "message": "URL must start with http:// or https://.",
    "field": "url"
  }
}
```
```

--------------------------------

### Get Item by ID

Source: https://docs.getmatter.com/api/items/get

Fetches a single item from your library using its unique ID. You can also request additional fields like markdown content.

```APIDOC
## Get Item

### Description
Returns a single item from your library with full metadata.

### Method
GET

### Endpoint
/items/{id}

### Parameters
#### Path Parameters
- **id** (string) - Required - The item ID. Example: `itm_r9f3a`.

#### Query Parameters
- **include** (string) - Optional - Comma-separated list of additional fields to include. Currently supported: `markdown`.
  When `markdown` is included, the response adds a `markdown` field with the parsed article body. These requests count against the [content rate limit](/api/rate-limits) (20/min).

### Response
#### Success Response (200)
- **id** (string) - The item ID.
- **title** (string) - The item title.
- **url** (string) - The URL of the item.
- **created_at** (string) - The timestamp when the item was created.
- **updated_at** (string) - The timestamp when the item was last updated.
- **metadata** (object) - Additional metadata associated with the item.
- **markdown** (string) - The parsed markdown content of the article (only if `include=markdown` is specified).
```

--------------------------------

### List Annotations using Python

Source: https://docs.getmatter.com/api/annotations/list

This Python script demonstrates how to retrieve annotations for an item using the `requests` library. Replace `token` with your actual API token and `itm_r9f3a` with the target item ID.

```python
response = requests.get(
    "https://api.getmatter.com/public/v1/items/itm_r9f3a/annotations",
    headers={"Authorization": f"Bearer {token}"}
)
annotations = response.json()
```

--------------------------------

### List All Tags with Python

Source: https://docs.getmatter.com/api/tags/list

This Python script demonstrates how to retrieve all tags using the `requests` library. It requires your API token to be stored in the `token` variable.

```python
response = requests.get(
    "https://api.getmatter.com/public/v1/tags",
    headers={"Authorization": f"Bearer {token}"}
)
tags = response.json()
```

--------------------------------

### Annotation Response Structure

Source: https://docs.getmatter.com/api/annotations/get

This is an example of a successful JSON response when retrieving an annotation. It includes details such as the annotation ID, parent item ID, highlighted text, and timestamps.

```json
{
  "object": "annotation",
  "id": "ann_m2k8v",
  "item_id": "itm_r9f3a",
  "text": "The way to figure out what to work on is by working.",
  "note": "Core thesis of the essay",
  "created_at": "2026-03-30T18:32:00Z",
  "updated_at": "2026-03-30T18:32:00Z"
}
```

--------------------------------

### Order by Library Position

Source: https://docs.getmatter.com/api/pagination

This command retrieves items in the order they are manually arranged in the application, by specifying `library_position` for ordering.

```bash
# Queue in manual order (as arranged in the app)
curl "https://api.getmatter.com/public/v1/items?status=queue&order=library_position" \
  -H "Authorization: Bearer $MATTER_TOKEN"
```

--------------------------------

### Get items in inbox feed order

Source: https://docs.getmatter.com/api/pagination

Use the `order=inbox_position` parameter to retrieve items sorted by their inbox feed position (newest first). Requires an `Authorization` header.

```bash
curl "https://api.getmatter.com/public/v1/items?order=inbox_position" \
  -H "Authorization: Bearer $MATTER_TOKEN"
```

--------------------------------

### Incremental sync and local sorting with position fields

Source: https://docs.getmatter.com/api/pagination

Fetches changed items using `updated_since` for incremental sync, then sorts them locally using `library_position` for app display. Assumes `fetch_all_pages` and `local_db` are defined.

```python
# Incremental sync — fetches only changed items
params = {"updated_since": last_sync, "limit": 100}
changed = fetch_all_pages(params)

# Update local cache with changed items
for item in changed:
    local_db[item["id"]] = item

# Display in app order using position fields
queue_items = sorted(
    [i for i in local_db.values() if i["status"] == "queue"],
    key=lambda i: i["library_position"] or 0,
    reverse=True,
)
```

--------------------------------

### Log in

Source: https://docs.getmatter.com/cli/commands

Logs into the Matter service. Can open a browser for token acquisition or accept a token directly.

```APIDOC
## Log in

### Description
Logs into the Matter service. Can open a browser for token acquisition or accept a token directly.

### Method
`matter login`

### Parameters
#### Path Parameters
- **token** (string) - Optional - Pass token directly
```

--------------------------------

### Save a URL to your Library

Source: https://docs.getmatter.com/cli/quickstart

Add a new item to your Matter library by providing a URL to the `matter items save` command.

```bash
matter items save --url "https://paulgraham.com/greatwork.html"
```

--------------------------------

### List Items with Options

Source: https://docs.getmatter.com/cli/commands

Lists items with various filtering and sorting options. Use --plain for human-readable output. Supports filtering by status, content type, favorite status, tags, update date, and pagination.

```bash
matter items list [options]
```

```bash
matter items list --status queue --plain
matter items list --content-type article --favorite --limit 10
matter items list --status archive --all
```

--------------------------------

### Fetch Annotation by ID using cURL

Source: https://docs.getmatter.com/api/annotations/get

Use this cURL command to make a GET request to the annotations endpoint. Replace `ann_m2k8v` with the actual annotation ID and `mat_your_token_here` with your API token.

```bash
curl https://api.getmatter.com/public/v1/annotations/ann_m2k8v \
    -H "Authorization: Bearer mat_your_token_here"
```

--------------------------------

### Account Info

Source: https://docs.getmatter.com/cli/commands

Returns your account info including name, email, and Pro status.

```APIDOC
## Account Info

### Description
Returns your account info including name, email, and Pro status.

### Method
`matter account`

### Example
```bash
matter account
matter account --plain
```
```

--------------------------------

### List Annotations using cURL

Source: https://docs.getmatter.com/api/annotations/list

Use this cURL command to fetch annotations for a specific item. Ensure you replace `itm_r9f3a` with the actual item ID and `mat_your_token_here` with your API token.

```bash
curl "https://api.getmatter.com/public/v1/items/itm_r9f3a/annotations" \
    -H "Authorization: Bearer mat_your_token_here"
```

--------------------------------

### Filter by Multiple Content Types

Source: https://docs.getmatter.com/api/pagination

Use this command to retrieve items that are either articles or podcasts by providing a comma-separated list of content types.

```bash
# Articles OR podcasts
curl "https://api.getmatter.com/public/v1/items?content_type=article,podcast" \
  -H "Authorization: Bearer $MATTER_TOKEN"
```

--------------------------------

### Paginate Through All Items in Python

Source: https://docs.getmatter.com/api/pagination

This Python script demonstrates how to iteratively fetch all items by repeatedly requesting pages until `has_more` is false, updating the cursor with each request.

```python
import requests

url = "https://api.getmatter.com/public/v1/items"
headers = {"Authorization": f"Bearer {token}"}
params = {"limit": 50}
all_items = []

while True:
    response = requests.get(url, headers=headers, params=params).json()
    all_items.extend(response["results"])

    if not response["has_more"]:
        break
    params["cursor"] = response["next_cursor"]

print(f"Fetched {len(all_items)} items")
```

--------------------------------

### Save Item using Python

Source: https://docs.getmatter.com/api/items/create

This Python script demonstrates how to save an item using the requests library. It includes logic to poll for processing completion if the item is not immediately available.

```python
import requests
import time

# Save the item
response = requests.post(
    "https://api.getmatter.com/public/v1/items",
    headers={
        "Authorization": f"Bearer {token}",
        "Content-Type": "application/json"
    },
    json={"url": "https://paulgraham.com/greatwork.html", "status": "queue"}
)
item = response.json()

# Poll until processing completes (if needed)
while item["processing_status"] == "processing":
    time.sleep(5)
    item = requests.get(
        f"https://api.getmatter.com/public/v1/items/{item['id']}",
        headers={"Authorization": f"Bearer {token}"}
    ).json()

print(item["title"])  # "How to Do Great Work"
```

--------------------------------

### Search for Items using cURL

Source: https://docs.getmatter.com/api/search

Use this cURL command to search for items. Replace `mat_your_token_here` with your actual API token and adjust query parameters as needed.

```bash
curl "https://api.getmatter.com/public/v1/search?query=machine+learning&type=items&status=queue" \
    -H "Authorization: Bearer mat_your_token_here"
```

--------------------------------

### Incremental Sync in Python

Source: https://docs.getmatter.com/api/pagination

This Python script shows how to perform an incremental sync by fetching items updated since a specific timestamp. It includes logic to store the current time as a new sync checkpoint for future syncs.

```python
from datetime import datetime

last_sync = "2026-03-29T00:00:00Z"
params = {"updated_since": last_sync, "limit": 100}
changed_items = []

while True:
    response = requests.get(url, headers=headers, params=params).json()
    changed_items.extend(response["results"])
    if not response["has_more"]:
        break
    params["cursor"] = response["next_cursor"]

# Save the current time as your new sync checkpoint
new_sync = datetime.utcnow().isoformat() + "Z"
```

--------------------------------

### Fetch Next Page of Items

Source: https://docs.getmatter.com/api/pagination

To retrieve the subsequent page of items, pass the `next_cursor` value obtained from the previous response as the `cursor` parameter.

```bash
# Next page (use next_cursor from previous response)
curl "https://api.getmatter.com/public/v1/items?limit=50&cursor=eyJpZCI6MTIzNH0=" \
  -H "Authorization: Bearer $MATTER_TOKEN"
```

--------------------------------

### List Items in Queue

Source: https://docs.getmatter.com/cli/quickstart

Retrieve a list of items currently in your queue using the `matter items list` command with the `--status queue` and `--plain` flags for readable output.

```bash
matter items list --status queue --plain
```

--------------------------------

### List Items (cURL)

Source: https://docs.getmatter.com/api/items/list

Use this cURL command to fetch a paginated list of items, filtering by status and limiting the results per page. Ensure you replace `mat_your_token_here` with your actual API token.

```bash
curl "https://api.getmatter.com/public/v1/items?status=queue&limit=10" \
    -H "Authorization: Bearer mat_your_token_here"
```

--------------------------------

### List All Tags

Source: https://docs.getmatter.com/api/tags/list

Returns all tags in your library. You can paginate the results using `limit` and `cursor` query parameters.

```APIDOC
## GET /public/v1/tags

### Description
Returns all tags in your library.

### Method
GET

### Endpoint
https://api.getmatter.com/public/v1/tags

### Query Parameters
- **limit** (integer) - Optional - Number of tags per page. Min 1, max 100. Defaults to 25.
- **cursor** (string) - Optional - Cursor for the next page of results.

### Response
#### Success Response (200)
- **object** (string) - Always "list".
- **results** (array) - Array of tag objects.
  - **object** (string) - Always "tag".
  - **id** (string) - Tag ID.
  - **name** (string) - Tag name.
  - **item_count** (integer) - Number of items with this tag.
  - **created_at** (string) - ISO 8601 timestamp.
- **has_more** (boolean) - Whether there are more results.
- **next_cursor** (string) - Cursor for the next page.

### Request Example
```bash cURL
curl https://api.getmatter.com/public/v1/tags \
  -H "Authorization: Bearer mat_your_token_here"
```

```python Python
import requests

token = "your_token_here"
response = requests.get(
    "https://api.getmatter.com/public/v1/tags",
    headers={"Authorization": f"Bearer {token}"}
)
tags = response.json()
```

### Response Example
```json 200
{
  "object": "list",
  "results": [
    {
      "object": "tag",
      "id": "tag_n5j2x",
      "name": "essays",
      "item_count": 42,
      "created_at": "2025-01-15T10:00:00Z"
    },
    {
      "object": "tag",
      "id": "tag_k3m9p",
      "name": "tech",
      "item_count": 87,
      "created_at": "2025-02-20T14:30:00Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```
```

--------------------------------

### Launch Interactive TUI

Source: https://docs.getmatter.com/cli/commands

Launches the interactive terminal user interface for Matter.

```bash
matter tui                  # Launch the interactive terminal UI
```

--------------------------------

### List Annotations on an Item

Source: https://docs.getmatter.com/cli/quickstart

View all annotations associated with a specific item by using the `matter annotations list` command with the item ID.

```bash
matter annotations list --item itm_r9f3a
```

--------------------------------

### Verify your token

Source: https://docs.getmatter.com/api/quickstart

This endpoint verifies your API token by fetching your account information.

```APIDOC
## GET /public/v1/me

### Description
Verifies the provided API token by returning the authenticated account details.

### Method
GET

### Endpoint
/public/v1/me

### Request Example
```bash
curl https://api.getmatter.com/public/v1/me \
  -H "Authorization: Bearer $MATTER_TOKEN"
```

### Response
#### Success Response (200)
- **object** (string) - Type of the object returned, e.g., "account".
- **id** (string) - Unique identifier for the account.
- **name** (string) - Name of the account holder.
- **email** (string) - Email address of the account holder.
- **is_pro** (boolean) - Indicates if the account has a Pro subscription.
- **rate_limit** (object) - Object containing read and write rate limits.
  - **read** (integer) - Maximum number of read operations allowed.
  - **write** (integer) - Maximum number of write operations allowed.

#### Response Example
```json
{
  "object": "account",
  "id": "act_k8x2m",
  "name": "Jane Smith",
  "email": "jane@example.com",
  "is_pro": true,
  "rate_limit": {
    "read": 120,
    "write": 30
  }
}
```
```

--------------------------------

### Update Matter CLI

Source: https://docs.getmatter.com/cli/quickstart

Run the `matter update` command to immediately update the CLI to the latest version. Updates are typically downloaded in the background.

```bash
matter update
```

--------------------------------

### Save an Article

Source: https://docs.getmatter.com/api/quickstart

Save an article to your Matter library by providing its URL. The 'status' can be set to 'queue' to process it later. If the URL already exists, the existing item is returned.

```bash
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"}'
```

--------------------------------

### Interactive TUI

Source: https://docs.getmatter.com/cli/commands

Launches the interactive terminal user interface for Matter.

```APIDOC
## Interactive TUI

### Description
Launches the interactive terminal user interface for Matter. Also launches when `matter` is run with no arguments.

### Method
`matter tui`
```

--------------------------------

### List Tags

Source: https://docs.getmatter.com/llms.txt

Returns all tags in your library.

```APIDOC
## List Tags

### Description
Returns all tags in your library.

### Method
GET

### Endpoint
/tags/list
```

--------------------------------

### List Items (Python)

Source: https://docs.getmatter.com/api/items/list

This Python script demonstrates how to retrieve a paginated list of items using the `requests` library. It filters items by status and sets a limit for the number of results per page. Replace `token` with your actual API token.

```python
response = requests.get(
    "https://api.getmatter.com/public/v1/items",
    headers={"Authorization": f"Bearer {token}"},
    params={"status": "queue", "limit": 10}
)
items = response.json()
```
Tokens:
Raw