# Quickstart

> Create a token, make your first call to the NessFlow API and launch a crawl, in a few minutes.

The NessFlow API is a REST API that speaks JSON. It exposes what the product does: projects, campaigns, crawls, reports, exports, rank tracking and webhooks.

## Create a token

Open your team's **API** screen, in the team settings, then **Create a token**. Pick its scopes (what it may read or do) and its lifetime. The token starts with `nf_` and is shown once: store it in your secret manager.

The examples of this documentation read the token from the `NESSFLOW_TOKEN` environment variable:

```bash
export NESSFLOW_TOKEN="paste your token here"
```

## First call

`GET /v1/me` describes the token, the team it acts for and what your plan opens:

```bash
curl "https://api.nessflow.com/v1/me" \
  -H "Authorization: Bearer $NESSFLOW_TOKEN"
```

The response notably returns `api_access`, the verbs your plan opens (`read`, and `write` from the Pro plan).

## List your projects

```bash
curl "https://api.nessflow.com/v1/projects" \
  -H "Authorization: Bearer $NESSFLOW_TOKEN"
```

Each project carries an `id` (a UUID): it is what the other operations expect.

## Launch a crawl

A crawl is launched on a **campaign** of the project. Launching a crawl consumes one crawl of your monthly quota, so the `Idempotency-Key` header is required: a retry after a timeout never launches a second crawl.

```bash
curl -X POST "https://api.nessflow.com/v1/campaigns/$CAMPAIGN_ID/crawls" \
  -H "Authorization: Bearer $NESSFLOW_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
```

The API answers `202` with the crawl to follow. Poll `GET /v1/crawls/{id}` while `active` is `true`, or subscribe a webhook to `crawl.completed` to be told.

## What next

- authentication and scopes, in detail;
- the full reference of every operation;
- webhooks, to stop polling.