TypeScript SDK

originalvoices is a small, typed client for the API. Types come straight from the API spec, so every field shows up with its docs in your editor.

npm install originalvoices   # Node.js 20+

Set ORIGINALVOICES_API_KEY, or pass { apiKey }. Create a key under Developers → API Keys in the platform.

Ask

import { OriginalVoices } from "originalvoices";

const ov = new OriginalVoices();

const result = await ov.ask({
  target: { audience: "UK, 18-30, fitness enthusiasts" },
  questions: [
    {
      id: "pick",
      type: "choice",
      question: "Which matters most when buying running shoes?",
      choices: ["Price", "Comfort", "Style", "Durability"],
    },
    { id: "why", type: "open", question: "Why did you pick that?" },
  ],
});

result.questions[0].results;        // [{ choice, count, percentage }, …]
result.participants[0].answers.why; // { answer, confidence }

ask() takes the same body as POST /v1/ask and returns its data: a saved audience is target: { audienceId }, a study is target: { studyId }.

Methods

Method	Endpoint
ov.ask(params)	POST /v1/ask
ov.audiences.list()	GET /v1/audiences
ov.audiences.create({ title, prompt })	POST /v1/audiences
ov.audiences.update(id, { title })	PATCH /v1/audiences/{id}
ov.audiences.delete(id)	DELETE /v1/audiences/{id}
ov.studies.list()	GET /v1/studies
ov.studies.participants(studyId)	GET /v1/studies/{studyId}/participants

Errors

Failed requests throw an OriginalVoicesError with the API's status, code, message and requestId. See Errors & limits for every code.

import { OriginalVoicesError } from "originalvoices";

try {
  await ov.ask({ target: { audience: "…" }, questions: [{ type: "open", question: "…" }] });
} catch (e) {
  if (e instanceof OriginalVoicesError && e.code === "insufficient_twins") {
    // broaden the audience
  }
}

Options

new OriginalVoices({
  apiKey: "…",                              // default: ORIGINALVOICES_API_KEY
  baseURL: "https://api.originalvoices.ai", // default
  timeout: 300_000,                         // ms; asks take tens of seconds
});

Upgrading from 0.x

1.0 replaces the old generated client. ask.open() and ask.choices() are now one ask(), results come back without the .data wrapper, and projects are replaced by studies.

npm · GitHub