Quickstart

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:

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:

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

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.

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.