# Getting started

This page walks you through your first authenticated request to the **Frontline Public API**.

## 1. Generate an API key

Frontline issues two kinds of API key. Pick the one that matches what you're building (see [Authentication](/docs/authentication) for the full breakdown of which endpoints accept which):

### Personal API key (`USER`)

Use this when your integration acts on behalf of a specific user — creating agents, updating settings, publishing flows, building flow/workflow graphs, etc.

1. In the Frontline app, click your **user name in the bottom-left of the sidebar**, then **Settings**.
2. In the settings sidebar, under **My settings**, open **Bring your own Agent**.
3. Click **Create personal API key**, name it, and confirm.
4. **Copy the key now** — Frontline only stores its hash, so it can never be displayed again. If you lose it, delete that key and create a new one.


Each user can hold up to **5 personal keys** at a time; the same screen shows the current count (e.g. `1/5 personal keys used`).

### Account API key (`GENERAL`)

Use this for account-wide, machine-to-machine integrations that don't need to be attributed to a specific user (dashboards, read-only sync, etc.). `GENERAL` keys do **not** work on endpoints that require `USER` scope.

1. Open **Settings** in the Frontline app (same path as above).
2. In the settings sidebar, under **Account settings**, open **Developer**.
3. Click **Create API key**, give it a memorable name, and confirm.
4. **Copy the key now** — same one-time-display rule as the personal key.


> Treat API keys like passwords. Don't commit them to git, paste them in chat, or embed them in client-side code. In CI/CD inject them via secrets.


## 2. Set the base URL

All Public API endpoints live under:


```
https://prod-api.getfrontline.ai/public/v1
```

## 3. Make your first request

Hit `GET /public/v1/me` to confirm your key works. It returns the account (and user, if you used a `USER` key) associated with the key.


```bash
curl https://prod-api.getfrontline.ai/public/v1/me \
  -H "Authorization: Bearer $FRONTLINE_API_KEY"
```

A successful response looks like:


```json
{
    "ok": true,
    "data": {
        "account": {
            "id": 1234,
            "name": "Acme Inc.",
            "namespace": "acme"
        },
        "user": {
            "id": 56,
            "email": "you@acme.com"
        }
    }
}
```

If you used a `GENERAL` key the `user` field will be `null`.

## 4. List your agents


```bash
curl https://prod-api.getfrontline.ai/public/v1/agents \
  -H "Authorization: Bearer $FRONTLINE_API_KEY"
```


```json
{
    "results": [{ "id": "uuid-...", "name": "Support Agent", "isOffline": false }]
}
```

## 5. Same call from Node and Python


```js
// Node 18+ — native fetch
const res = await fetch("https://prod-api.getfrontline.ai/public/v1/agents", {
    headers: { Authorization: `Bearer ${process.env.FRONTLINE_API_KEY}` },
});
const { results } = await res.json();
console.log(results);
```


```python
# Python 3 — requests
import os, requests

res = requests.get(
    "https://prod-api.getfrontline.ai/public/v1/agents",
    headers={"Authorization": f"Bearer {os.environ['FRONTLINE_API_KEY']}"},
)
res.raise_for_status()
print(res.json()["results"])
```

## Next steps

- Read the full **[Authentication](/docs/authentication)** reference for `USER` vs `GENERAL` key rules.
- Learn the **[Rate limits](/docs/rate-limits)** before going to production.
- Browse the **[API Reference](/reference/openapi)** for every endpoint and schema.
- Prefer a terminal workflow? The **[CLI](/cli)** wraps the same endpoints.


## Need help using the platform itself?

These docs cover the **Public API and CLI**. For walkthroughs of the Frontline app — setting up channels, configuring agents in the UI, managing your team, billing in-product, troubleshooting — head to [https://help.getfrontline.ai](https://help.getfrontline.ai).