# Quickstart

Five steps from an API key to the event feed. You need a terminal with curl, Node.js 18+ or Python 3.

AI agent prompt: https://docs.melioralab.io/en/agent-prompt.txt

### Get an API key

During early access, we issue keys for you: contact [Support](https://docs.melioralab.io/en/support/) and tell us which permissions and scope you need. To get started, the Campaigns, Leads and Events permissions are enough.

If your organization has **Settings › Integrations › API** enabled, an Owner or Admin can create a key with the "Create key" button.

The key is shown only once. Save it right away: you can't recover it, only rotate it.

### Store the key in an environment variable

Don't hardcode the key or pass it in the request URL. Store it in an environment variable:

```bash
export MELIORA_API_KEY="mel_live_..."
```

### Check access

`GET /v1/me` returns the organization, permissions and limits of the key. It works with any set of permissions.

```bash
curl https://api.melioralab.io/v1/me \
  -H "Authorization: Bearer $MELIORA_API_KEY"
```
```js
const res = await fetch('https://api.melioralab.io/v1/me', {
  headers: { Authorization: `Bearer ${process.env.MELIORA_API_KEY}` },
});
console.log(res.status, await res.json());
```
```python
import os
import requests

resp = requests.get(
    "https://api.melioralab.io/v1/me",
    headers={"Authorization": f"Bearer {os.environ['MELIORA_API_KEY']}"},
    timeout=15,
)
print(resp.status_code, resp.json())
```

In the response, check `scopes` and `scope`: these are the key's permissions and scope. If you get an error, look up its code and how to fix it in [Errors](https://docs.melioralab.io/en/errors/). The most common one is `invalid_api_key`: the key was copied only partially or with an extra space.

### List campaigns and leads

Campaigns are returned in pages, oldest first:

```bash
curl -G https://api.melioralab.io/v1/campaigns \
  -H "Authorization: Bearer $MELIORA_API_KEY" \
  -d status=active
```

Take the `id` of the campaign you need and request its leads:

```bash
curl -G https://api.melioralab.io/v1/leads \
  -H "Authorization: Bearer $MELIORA_API_KEY" \
  -d campaign_id=4d8b2f73-6e1a-4c95-b7d0-8a3f5e2c9b14 \
  -d limit=100
```

If the response has `has_more: true`, pass the `next_cursor` value as the `cursor` parameter of your next request. See [Pagination](https://docs.melioralab.io/en/pagination/) for details.

### Subscribe to events

To learn about new messages and replies without walking through every lead, read the event feed. The first request with `start=now` returns an empty page and the cursor the feed starts from:

```bash
curl -G https://api.melioralab.io/v1/events \
  -H "Authorization: Bearer $MELIORA_API_KEY" \
  -d start=now
```

Save `next_cursor` and request `GET /v1/events?cursor=...` once a minute. Every response contains a new cursor, even when there are no events: always save it.

## What's next

- [Polling events](https://docs.melioralab.io/en/events-polling/): a loop that never loses or duplicates events, with Node.js and Python examples.
- [CRM mapping](https://docs.melioralab.io/en/crm-mapping/): how to match a lead to a CRM record with `record_id`.
- [Rate limits and retries](https://docs.melioralab.io/en/rate-limits/): how to handle 429 and 503.