JavaScript / TypeScript SDK

npm install polyvia

import { Polyvia } from "polyvia";

const client = new Polyvia({ apiKey: "poly_<key>" });

// Ingest → wait → query
const result = await client.ingest.file("report.pdf");
await client.ingest.wait(result.task_id);
const answer = await client.query("What are the key findings?");
console.log(answer.answer);

// Single file — accepts a file path, Buffer, or Blob.
// `group` takes the group name; it's created if it doesn't exist yet.
const result = await client.ingest.file("report.pdf", {
  name: "Q4 Report",
  group: "Finance",
});

// Multiple files (the group is resolved once for the batch)
const items = await client.ingest.batch(["q3.pdf", "q4.pdf"], {
  names: ["Q3 Report", "Q4 Report"],
  group: "Finance",
});

// Check status
const status = await client.ingest.status(result.task_id);

// Block until done — throws IngestionError on failure, IngestionTimeout on timeout
await client.ingest.wait(result.task_id, { pollInterval: 5, timeout: 300 });

// All completed documents
const answer = await client.query("What risks are mentioned across all reports?");

// Single document (fastest)
const answer = await client.query("Summarise section 3.", { documentId: "doc_<id>" });

// Scoped to a group — by name (must already exist)
const answer = await client.query("Key findings?", { group: "Finance" });

// Multiple groups — by id
const answer = await client.query("Compare results.", { groupIds: ["g_<id>", "g_<id>"] });

console.log(answer.answer);

// Idempotent: returns the existing "Finance" group or creates it (matched by
// exact name, so never a duplicate).
const group = await client.groups.getOrCreate("Finance");
group.id;     // backend id, if you ever need it
group.name;   // "Finance"

// Look one up without creating it (undefined if there isn't one)
const existing = await client.groups.find("Finance");

// List
const groups = await client.groups.list();

// Delete all documents in a group, then the group itself
await client.groups.delete(group.id, { deleteDocuments: true });

// List — filter by status and/or group
const docs = await client.documents.list({ status: "completed", groupId: "g_<id>" });
const docs = await client.documents.list({ groupIds: ["g_<id>", "g_<id>"] });

// Get one
const doc = await client.documents.get("doc_<id>");

// Move to a different group / remove from group
await client.documents.update("doc_<id>", { groupId: "g_other" });
await client.documents.update("doc_<id>", { groupId: null });

// Delete
await client.documents.delete("doc_<id>");

const usage = await client.usage();
console.log(usage.usage.requests.period);    // requests this calendar month
console.log(usage.usage.documents_stored);   // live document count

const limits = await client.rateLimits();
console.log(limits.limits["requests_per_minute"]);
console.log(limits.current["remaining_this_minute"]);

import {
  AuthenticationError,  // 401 — bad or missing API key
  ForbiddenError,        // 403 — document belongs to another user
  NotFoundError,         // 404 — document, group, or task not found
  RateLimitError,        // 429 — too many requests
  IngestionError,        // task finished with status "failed"
  IngestionTimeout,      // ingest.wait() exceeded its timeout
} from "polyvia";

try {
  await client.ingest.wait(taskId, { timeout: 60 });
} catch (e) {
  if (e instanceof IngestionError) console.error("Parsing failed:", e.error);
  else if (e instanceof IngestionTimeout) console.error("Timed out");
  else if (e instanceof RateLimitError) console.error("Rate limited");
  else if (e instanceof NotFoundError) console.error("Not found");
  else if (e instanceof AuthenticationError) console.error("Invalid API key");
  else throw e;
}