Quickstart

Open the Nephia dashboard and sign in with Google or a sign-in link. Your Account is provisioned automatically on first sign-in.

2. Create an API key

Go to API Keys and create a key. Copy it immediately — it is shown only once.

3. Create a query

A Query polls every Source you switch on, keeps what matches, and reads each mention for sentiment and intent. Swap figma for your own brand.

Node.js SDK

npm install nephia

import { Nephia } from "nephia";

const client = new Nephia({ apiKey: "YOUR_API_KEY" });

const query = await client.queries.create({
  name: "figma",
  refreshIntervalSeconds: 900,
  globalCriteria: { market: "fr", terms: ["figma", "figma alternative"] },
  sources: [
    { source: "reddit", enabled: true },
    { source: "x", enabled: true },
  ],
  aiEnabled: true,
  sentimentEnabled: true,
});

curl

curl -X POST https://api.nephia.cc/v1/queries \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{
        "name": "figma",
        "refreshIntervalSeconds": 900,
        "globalCriteria": { "market": "fr", "terms": ["figma", "figma alternative"] },
        "sources": [
          { "source": "reddit", "enabled": true },
          { "source": "x", "enabled": true }
        ],
        "aiEnabled": true,
        "sentimentEnabled": true
      }'

subjectRole says what the query is about: own for your own brand or product (the default, and what every query written before this field reads as), competitor for somebody else’s, topic for a problem or a category rather than a product. It changes nothing about what gets polled — it is what a reply draft reads to decide whose voice it writes in.

Query bodies are camelCase, unlike the rest of this API. A query is the one object you round-trip — read it, change a field, send it back — so its body is spelled the way its response is. See Overview.

A new query starts empty until its sources are polled. Add backfill: true to the body above and each source is searched once immediately, at one tick per source, so the next step answers with content straight away — see History & backfill.

4. Read the mentions

One read across every Source and every query on the Account, newest first. Free.

const { mentions } = await client.mentions.list({ limit: 50 });

for (const m of mentions) {
  console.log(m.source, m.sentiment, m.intent, m.title, m.url);
}

curl "https://api.nephia.cc/v1/mentions?limit=50" \
  -H "x-api-key: YOUR_API_KEY"

Each mention carries what the query read into it: sentiment, intent, your agent step’s answer under agent, the marks a rule put on it, and — on GET /v1/queries/{id}/results — the bucket it was sorted into. Add a webhookUrl to the query and each match is delivered to your endpoint as it is found instead of waiting to be polled — see Webhooks.

5. Or watch a single Source

A Watch is a query’s unit of polling, and you can create one directly when a whole query is more than you need. backfill gives it content straight away.

const watch = await client.x.watches.create({
  query: "figma",
  refreshIntervalSeconds: 300,
  backfill: true,
});

const events = await client.x.watches.listEvents(watch.id);

curl -X POST https://api.nephia.cc/v1/x/watches \
  -H "x-api-key: YOUR_API_KEY" \
  -H "content-type: application/json" \
  -d '{"query":"figma","refresh_interval_seconds":300,"backfill":true}'

The same contract runs on every Source — Reddit, YouTube, Bluesky, Hacker News, RSS, and AI answers, which tracks what ChatGPT, Gemini and Perplexity say about you. Watching a clothing brand or sourcing resale? Vinted is a first-class Source too, with observed price history and market statistics on top of its Watches.

Next steps

SDK (Node.js) — typed client, mentions and queries included
Authentication — key management and headers
Credits — per-endpoint costs
Limits — request quota and Watch entitlements per plan
Sources — per-Source coverage and Watch criteria (Reddit, Youtube)
Watches — subscribe to changes
API Reference — full endpoint list

Guides

Sources

Integrations

API Reference

2. Create an API key

3. Create a query

Node.js SDK

curl

4. Read the mentions

5. Or watch a single Source

Next steps

​1. Sign in to the dashboard

​2. Create an API key

​3. Create a query

​Node.js SDK

​curl

​4. Read the mentions

​5. Or watch a single Source

​Next steps

1. Sign in to the dashboard

2. Create an API key

3. Create a query

Node.js SDK

curl

4. Read the mentions

5. Or watch a single Source

Next steps