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

# Save Item

> Save a new item to your library by URL.

Saving an item triggers content extraction in the background. The item is returned immediately, but metadata fields like `title`, `author`, and `word_count` may not be available until processing completes.

Check the `processing_status` field to know when the item is ready:

| Status       | Meaning                                                                    |
| ------------ | -------------------------------------------------------------------------- |
| `completed`  | Content has been extracted. All fields are populated.                      |
| `processing` | Extraction is in progress. Poll `GET /items/{id}` to check for completion. |
| `failed`     | Extraction failed (e.g., site is unreachable or unsupported).              |

<Note>
  About 40% of saves complete instantly (cached content). For the rest, processing typically takes 20-60 seconds. Save requests count against a separate [rate limit tier](/api/rate-limits) (10/min).
</Note>

## Body Parameters

<ParamField body="url" type="string" required>
  The URL to save. Must be a valid `http://` or `https://` URL.
</ParamField>

<ParamField body="status" type="string" default="queue">
  Where to place the item. One of `queue` or `archive`.
</ParamField>

## Response

Returns the item with status `201`. If the URL is already in your library, the existing item is returned with status `200`.

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST https://api.getmatter.com/public/v1/items \
    -H "Authorization: Bearer mat_your_token_here" \
    -H "Content-Type: application/json" \
    -d '{"url": "https://paulgraham.com/greatwork.html", "status": "queue"}'
  ```

  ```python Python theme={null}
  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"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.getmatter.com/public/v1/items", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${token}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({ url: "https://paulgraham.com/greatwork.html", status: "queue" })
  });
  const item = await response.json();
  ```
</RequestExample>

<ResponseExample>
  ```json "201 — completed (cached content)" theme={null}
  {
    "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",
    "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"
  }
  ```

  ```json "201 — processing (async extraction)" theme={null}
  {
    "object": "item",
    "id": "itm_r9f3a",
    "url": "https://paulgraham.com/greatwork.html",
    "status": "queue",
    "processing_status": "processing",
    "title": null,
    "author": null,
    "site_name": null,
    "content_type": null,
    "word_count": null,
    "is_favorite": false,
    "reading_progress": 0.0,
    "image_url": null,
    "tags": [],
    "updated_at": "2026-03-30T18:30:00Z"
  }
  ```

  ```json 422 theme={null}
  {
    "error": {
      "code": "unprocessable",
      "message": "URL must start with http:// or https://.",
      "field": "url"
    }
  }
  ```
</ResponseExample>