quickstart.mdx

title	Get Started with the Noteboxd API
sidebarTitle	Quickstart
description	Learn how to authenticate and make your first Noteboxd API call in under five minutes with a working curl example.

This page walks you through everything you need to go from zero to a live API response. You'll create a project, copy your API key, and make your first search call — all in under five minutes. No SDK required; a terminal and your API key are all you need.

Sign in to the Noteboxd developer dashboard at [developers.noteboxd.com](https://developers.noteboxd.com). From the dashboard, create a new project — give it any name you like. In the **Keys** section, create an API key. The full secret is shown once and is prefixed with `nb_live_`. Copy it before you leave the screen. The dashboard does not show that secret again.

Keep this key safe. You'll pass it as a Bearer token in every request you make to the API.

A new account can call the API on the free tier: **50 calls per day**, with no card and no prepaid balance. Those calls still count toward your account rate limit.

When you need more than the free allowance, switch to pay-as-you-go and add a prepaid balance from the **Billing** section. Successful calls then deduct that endpoint's price from the balance. If the balance is less than the cost of a call, that call returns `402 INSUFFICIENT_BALANCE`. Calls that return `4xx` or `5xx` are not charged.

With your key and balance in place, run the following `curl` command in your terminal. This calls the `/v1/search` endpoint and searches across all entity types for "Chanel No 5":

```bash
curl -G https://api.noteboxd.com/v1/search \
  -H "Authorization: Bearer nb_live_YOUR_KEY" \
  --data-urlencode "q=Chanel No 5" \
  --data-urlencode "limit=5"
```

Replace `nb_live_YOUR_KEY` with the key you copied from your project's Keys section.

A successful response returns a `results` array containing matching fragrances, brands, notes, perfumers, and collections. Each result includes a `type` field so you know what kind of entity it is, along with its canonical `id`, `name`, and relevant metadata. Here's an example of what you'll see:

```json
{
  "results": [
    {
      "type": "fragrance",
      "id": "chanel-no-5",
      "name": "No 5",
      "brand": "Chanel"
    }
  ]
}
```

You can use the `id` from any result to look up the full record for that entity using the corresponding detail endpoint.

Now that you've made your first call, here are a few good places to go next:

- [Fragrances API reference](/api-reference/fragrances/list) — filter fragrances and page the matches with a cursor
- [Fragrance enrichment guide](/guides/fragrance-enrichment) — learn how to match and enrich existing product data in bulk
- [Pricing concepts](/concepts/pricing) — understand per-call costs and how to manage your balance

Free-tier calls are not drawn from a balance. On pay-as-you-go, only successful (`2xx`) calls are deducted, and the price depends on the endpoint (most reads are 1¢). Failed calls (`4xx` and `5xx`) are not billed. Monitor usage from the [developer dashboard](https://developers.noteboxd.com).