> For the complete documentation index, see [llms.txt](https://docs.claret.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.claret.app/api-guide/quickstart.md).

# Quickstart

This guide takes you from nothing to a working API call in about five minutes. You will create a token, make your first request, and read the response.

{% hint style="info" %}
Replace `{tenant}` in every URL with your tenant name (for example, `demo`). Replace `{token}` with the token you create in step 1.
{% endhint %}

## 1. Create a token

1. Log into Claret and go to **Settings → Workspace Settings → API Access**.
2. On the **Tokens** tab, click **Create Token**.
3. Name it (for example, `quickstart`) and select the **Read** scope.
4. Click **Create**, then **copy the token now**. It is shown only once.

The token looks like `42|clrt_aBcDeF...`. Keep it somewhere safe.

For more on tokens and scopes, see [Authentication & Tokens](/api-guide/authentication.md) and the [Scopes Reference](/api-guide/scopes.md).

## 2. Make your first call

Call a reference endpoint to list units of measure. This is the lightest possible request and confirms everything is wired up:

```bash
curl "https://plan.claret.app/{tenant}/api/v1/uoms" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
```

## 3. Read the response

A successful call returns `200` with the standard response envelope:

```json
{
  "message": "Units of measure retrieved.",
  "data": {
    "uoms": [
      { "id": 1, "name": "Liter", "abbr": "L" },
      { "id": 2, "name": "Kilogram", "abbr": "kg" }
    ]
  },
  "meta": {
    "credits": { "cost": 1, "remaining": 9999999 },
    "pagination": { "per_page": 100, "total": 2 }
  },
  "links": {}
}
```

Every response follows this shape:

* `data` holds the result, keyed by the resource name.
* `meta` holds credit usage and pagination details.
* `links` holds navigation links when applicable.

The response headers also report usage: `X-Api-Credits-Remaining` and `X-RateLimit-Remaining`.

## 4. Try a filtered query

Add query parameters to narrow results. This fetches items whose name contains "Chardonnay", sorted by name:

```bash
curl "https://plan.claret.app/{tenant}/api/v1/items?filter[name]=Chardonnay&sort=name&per_page=10" \
  -H "Authorization: Bearer {token}" \
  -H "Accept: application/json"
```

See [Filtering & Sorting](/api-guide/filtering-and-sorting.md) for the full query syntax and [Pagination](/api-guide/pagination.md) for paging through large result sets.

## Next steps

| Goal                                        | Guide                                                      |
| ------------------------------------------- | ---------------------------------------------------------- |
| Understand tokens and authorization         | [Authentication & Tokens](/api-guide/authentication.md)    |
| Page through large datasets                 | [Pagination](/api-guide/pagination.md)                     |
| Filter, sort, and include relationships     | [Filtering & Sorting](/api-guide/filtering-and-sorting.md) |
| Sync inventory, pull sales, generate a plan | [Common Recipes](/api-guide/recipes.md)                    |
| Handle errors                               | [Error Reference](/api-guide/errors.md)                    |
| Browse every endpoint                       | the **API Reference** section                              |