> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nouvelhq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> From an API key to your first scan in about two minutes.

## 1. Get a key

Sign in to Nouvel, open **Settings → API**, and create a key.

<Warning>
  The key is shown **once**, at creation. We store a hash, not the key, so a lost key cannot be recovered and has to be replaced.
</Warning>

If you do not see an API tab, your account has not been granted access yet.

## 2. Add credit

The API is prepaid. Buy credit from **Settings → API → Add to balance**.

A request against an empty balance returns `402 insufficient_credit` before any work is done, so you are never charged for a call that could not run.

## 3. Make a call

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://nouvelhq.com/api/v1/scan \
    -H "Authorization: Bearer $NOUVEL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"query": "skincare routine for oily skin", "limit": 5}'
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch('https://nouvelhq.com/api/v1/scan', {
    method: 'POST',
    headers: {
      authorization: `Bearer ${process.env.NOUVEL_API_KEY}`,
      'content-type': 'application/json',
    },
    body: JSON.stringify({ query: 'skincare routine for oily skin', limit: 5 }),
  })

  const { reels, market } = await response.json()
  console.log(`${reels.length} reels from ${market}`)
  console.log('charged', response.headers.get('x-nouvel-charged-usd'))
  ```

  ```python Python theme={null}
  import os, requests

  response = requests.post(
      "https://nouvelhq.com/api/v1/scan",
      headers={"Authorization": f"Bearer {os.environ['NOUVEL_API_KEY']}"},
      json={"query": "skincare routine for oily skin", "limit": 5},
  )
  data = response.json()
  print(len(data["reels"]), "reels from", data["market"])
  print("charged", response.headers["x-nouvel-charged-usd"])
  ```
</CodeGroup>

A scan takes roughly 20 to 30 seconds. Set your client timeout to at least 90 seconds.

## 4. Watch what it cost

Every successful response carries the charge and the balance left:

```
x-nouvel-charged-usd: 0.037500
x-nouvel-balance-usd: 99.962500
```

You never need a second call to check your balance.

## Timeouts to configure

Analysis work is genuinely slow. These are the ceilings the API itself enforces, so your client should allow at least as much.

| Endpoint       | Typical                   | Set client timeout to |
| -------------- | ------------------------- | --------------------- |
| `/v1/assist`   | under 1s                  | 30s                   |
| `/v1/scan`     | 20 to 30s                 | 90s                   |
| `/v1/playbook` | 50 to 90s                 | 300s                  |
| `/v1/music`    | 35s warm, up to 150s cold | 300s                  |

<Tip>
  Music is slow the first time it meets an unfamiliar niche, because it has to listen to sounds it has never heard. Those results are cached permanently, so the same niche is much faster afterwards.
</Tip>