SDK (Node.js)

npm install nephia

import { Nephia } from "nephia";

const client = new Nephia({ apiKey: process.env.NEPHIA_API_KEY });

// Everything your keywords caught in the last 24 hours, newest first.
const { mentions } = await client.mentions.list({ limit: 50 });

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

const keyword = await client.keywords.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,
});

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

// Free: a substring scan over your own stored mentions.
const page = await client.mentions.list({
  since: "2026-08-01T00:00:00.000Z",
  source: "reddit",
  intent: ["purchase_intent", "comparison"],
});

// Charged: searches by meaning instead of by substring.
const semantic = await client.mentions.list({ q: "pricing complaints", mode: "semantic" });

// One row per Source and sentiment over the last seven days.
const { total, rows } = await client.mentions.stats({ group_by: "source,sentiment" });

// The ten authors who said the most in a closed week.
const authors = await client.mentions.stats({
  group_by: "author",
  since: "2026-09-01T00:00:00.000Z",
  until: "2026-09-08T00:00:00.000Z",
});

// Charged: the mentions closest in meaning to one you already have.
const similar = await client.mentions.similar(page.mentions[0].id);

let cursor: string | undefined;
do {
  const page = await client.mentions.list({ cursor, limit: 100 });
  handle(page.mentions);
  cursor = page.nextCursor;
} while (cursor);

const body = {
  globalCriteria: { market: "global", query: "alternative to stalkr" },
  sources: [
    { source: "reddit", enabled: true },
    { source: "hackernews", enabled: true },
  ],
};

// Free: the run's own validation, the credits per search and your balance.
const { valid, estimate, estimateToken, refusal } = await client.explore.estimate(body);

// Charged per search, when it runs. The token refuses any other body.
const { run, mentions, outcomes } = await client.explore.run(body, { estimateToken });

// The run is kept: read it again for free rather than running it twice.
const again = await client.mentions.list({ run: run.id });

const { keywords } = await client.keywords.list();
const detail = await client.keywords.get(keywords[0].id);

// Mentions scoped to one keyword, carrying the bucket each was sorted into.
const { mentions } = await client.keywords.listResults(detail.id, { limit: 50 });

// A patch: a key you leave out is left alone; `null` clears it.
const { keyword, resetSearches } = await client.keywords.update(detail.id, {
  refreshIntervalSeconds: 1800,
});

// The raw replay: each event is the body its webhook delivered, newest first.
const { events } = await client.keywords.events(detail.id, {
  since: "2026-07-01T00:00:00.000Z",
  source: "reddit",
});

// What happened underneath: every check, and every webhook delivery with its status code.
const { activity } = await client.keywords.activity(detail.id, { since: "2026-07-01T00:00:00.000Z" });
const failed = activity.filter((entry) => entry.type === "webhook.failed");

// Every stored run of the keyword's AI answers Source, the unchanged ones included.
const { runs } = await client.keywords.aiAnswerRuns(detail.id, { engine: "chatgpt" });

npx nephia mentions list --since 24h --sentiment negative --intent question
npx nephia mentions stats --group-by day,source --since 7d
npx nephia keywords list --json | jq '.keywords[] | select(.staleSources > 0)'

npx nephia keywords estimate -f keyword.json
npx nephia keywords create -f keyword.json --yes

import { Nephia } from "nephia";

const ok = await Nephia.webhooks.verify(rawBody, req.headers["x-signature"], secret);