Official Node.js SDK for the iGPT API.
- Website: https://www.igpt.ai
- Documentation: https://docs.igpt.ai
- Playground: https://igpt.ai/hub/playground/
- Node.js >= 18
npm install igptaiAll requests use a Bearer token:
- Header:
Authorization: Bearer <IGPT_API_KEY>
Store keys in a secret manager or environment variables.
The typical flow when using iGPT is:
- Connect datasources (per user)
- Retrieve answers using the connected context
This example starts an authorization flow to connect a user’s datasource.
The response includes a URL the user must open to complete authorization.
import IGPT from "igptai";
const igpt = new IGPT({
apiKey: process.env.IGPT_API_KEY
});
const res = await igpt.connectors.authorize({
service: "spike",
scope: "messages",
user: "user_123"
});
if (res?.error) {
console.error("Connection error:", res);
} else {
console.log("Open this URL to authorize:", res.url);
}After connecting a datasource, you can retrieve answers scoped to that user.
import IGPT from "igptai";
const igpt = new IGPT({
apiKey: process.env.IGPT_API_KEY,
user: "user_123" // optional default user
});
const res = await igpt.recall.ask({
input: "Summarize key risks, decisions, and next steps from this week's meetings."
});
if (res?.error) {
// No-throw design: handle errors via return value
console.error("iGPT error:", res);
} else {
console.log("iGPT response:", res);
}Calls map to API routes automatically, for example:
igpt.recall.ask(...)→POST /recall/askigpt.recall.search(...)→POST /recall/searchigpt.datasources.list(...)→POST /datasources/listigpt.datasources.disconnect(...)→POST /datasources/disconnectigpt.connectors.authorize(...)→POST /connectors/authorize
Authorize, connect, and start indexing a new datasource. ↗
service(string, required): Service provider identifier (e.g.,"spike").scope(string, required): Space-delimited scopes (e.g.,"messages").user(string, optional if set in constructor): Unique user identifier.redirect_uri(string, optional): Redirect URL after authorization completes.state(string, optional): Application state (returned after redirect).
const res = await igpt.connectors.authorize({
service: "spike",
scope: "messages",
redirect_uri: "https://your-app.com/callback",
state: "optional_state"
});
console.log(res);Generate a response based on input and connected context. ↗
-
input(string, required): The prompt/question to ask. -
user(string, optional if set in constructor): Unique user identifier. -
stream(boolean, optional, default:false): Iftrue, returns an async iterable stream. -
quality(string, optional): Context engineering quality (e.g.,"cef-1-normal"). Read more. -
output_format(string | object, optional):"text"(default)"json"{ schema: <JSON Schema> }to enforce a structured output
const res = await igpt.recall.ask({
input: "Summarize my last meeting in 5 bullet points.",
quality: "cef-1-normal",
output_format: "text"
});
console.log(res);const res = await igpt.recall.ask({
input: "Return a JSON object with { title, summary } for my last meeting.",
output_format: "json"
});
console.log(res);Use a schema to get consistent, machine-validated structure.
const output_format = {
strict: true,
schema: {
type: "object",
properties: {
action_items: {
type: "array",
description: "List of action items",
items: {
type: "object",
properties: {
title: { type: "string", description: "Short summary of the action item" },
owner: { type: "string", description: "Person responsible for the action item" },
due_date: { type: "string", format: "date", description: "Expected completion date" }
},
required: ["title", "owner", "due_date"],
additionalProperties: false
}
}
},
required: ["action_items"],
additionalProperties: false
}
};
const res = await igpt.recall.ask({
output_format,
input: "Open action items from yesterday’s board meeting",
quality: "cef-1-normal"
});
console.log(res);{
"action_items": [
{
"title": "Approve revised Q1 budget allocation",
"owner": "Dvir Ben-Aroya",
"due_date": "2026-01-15"
},
{
"title": "Approve final FY2026 strategic priorities",
"owner": "Board of Directors",
"due_date": "2026-01-31"
}
]
}Note: Streaming requests do not use retries. If a stream is interrupted, it terminates with an error chunk rather than retrying.
For streaming responses, set stream: true. The SDK returns an async iterable that yields parsed JSON chunks.
Streaming is designed to be resilient: if the stream breaks due to connectivity, the iterator yields an error chunk and finishes rather than throwing.
streammust betrue- Other parameters are the same as
recall.ask
const stream = await igpt.recall.ask({
input: "Stream the answer in chunks.",
stream: true
});
if (stream?.error) {
console.error("Stream init error:", stream);
} else {
for await (const chunk of stream) {
if (chunk?.error) {
console.error("Stream chunk error:", chunk);
break;
}
console.log("chunk:", chunk);
}
}Search in connected datasources. ↗
query(string, optional): Search query to execute.user(string, optional if set in constructor): Unique user identifier.date_from(string, optional): Start date filter (YYYY-MM-DD).date_to(string, optional): End date filter (YYYY-MM-DD).max_results(number, optional): Limit number of results (e.g.,50).
const res = await igpt.recall.search({
query: "board meeting notes"
});
console.log(res);const res = await igpt.recall.search({
query: "budget allocation",
date_from: "2026-01-01",
date_to: "2026-01-31",
max_results: 25
});
console.log(res);List datasources and indexing status. ↗
user(string, optional if set in constructor): Unique user identifier.
const res = await igpt.datasources.list();
console.log(res);Disconnect a datasource and remove indexed data. ↗
id(string, required): Datasource ID to disconnect (e.g.,"service/id/type").user(string, optional if set in constructor): Unique user identifier.
const res = await igpt.datasources.disconnect({
id: "service/id/type"
});
console.log(res);const igpt = new IGPT({
apiKey: process.env.IGPT_API_KEY, // required
user: "default_user_id", // optional default user
baseUrl: "https://api.igpt.ai/v1", // optional override
retries: 3, // optional: network retries for non-stream calls
backoffBase: 100, // optional: initial retry delay (ms)
backoffFactor: 2 // optional: exponential backoff factor
});Note: Retries apply only to non-stream requests. Streaming requests disable retries by design.
apiKey(string, required): Your iGPT API key.user(string, optional): Default user identifier. If provided, you can omituserin method calls.baseUrl(string, optional): Override API base URL (default:https://api.igpt.ai/v1).retries(number, optional): Retry attempts for non-stream requests (default:3).backoffBase(number, optional): Initial retry delay in milliseconds (default:100).backoffFactor(number, optional): Exponential backoff multiplier (default:2).
The SDK does not throw exceptions for request or stream failures.
Instead, it returns (or yields) normalized error objects with a consistent shape:
{ error: string }Errors originating from the client environment:
{ error: "network_error" }- A network-level failure occurred (timeout, DNS issue, offline).{ error: "request_aborted" }- The request was explicitly aborted by the caller.
Errors returned by the API:
{ error: "auth" }- Authentication failed due to missing, invalid, or expired credentials.{ error: "params" }- The request parameters were invalid or malformed.
- Use a secure secret manager for
IGPT_API_KEY(do not hardcode keys in source control). - Ensure user identifiers (
user) align with your internal identity and access model. - For policy and legal references:
- Privacy Policy: https://www.igpt.ai/privacy-policy/
- Terms & Conditions: https://www.igpt.ai/terms-and-conditions/
- Docs: https://docs.igpt.ai
- Playground: https://igpt.ai/hub/playground/
- Book a demo: https://www.igpt.ai/contact-sales/
- Contact: hello@igpt.ai
MIT