Quickstart

Create a token and make your first Claret API call in five minutes.

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.

Replace {tenant} in every URL with your tenant name (for example, demo). Replace {token} with the token you create in step 1.

1. Create a token

Log into Claret and go to Settings → Workspace Settings → API Access.
On the Tokens tab, click Create Token.
Name it (for example, quickstart) and select the Read scope.
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 and the Scopes Reference.

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:

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:

{
  "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:

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 for the full query syntax and Pagination for paging through large result sets.