iGPT Node.js SDK

Official Node.js SDK for the iGPT API.

• Website: https://www.igpt.ai
• Documentation: https://docs.igpt.ai
• Playground: https://igpt.ai/hub/playground/

Requirements

• Node.js >= 18

Install

npm install igptai

Authentication

All requests use a Bearer token:

• Header: Authorization: Bearer <IGPT_API_KEY>

Store keys in a secret manager or environment variables.

Quick start

The typical flow when using iGPT is:

1. Connect datasources (per user)
2. Retrieve answers using the connected context

Connect a datasource

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);
}

Ask with recall.ask()

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);
}

Services and routing

Calls map to API routes automatically, for example:

• igpt.recall.ask(...) → POST /recall/ask
• igpt.recall.search(...) → POST /recall/search
• igpt.datasources.list(...) → POST /datasources/list
• igpt.datasources.disconnect(...) → POST /datasources/disconnect
• igpt.connectors.authorize(...) → POST /connectors/authorize

Connectors

connectors.authorize()

Authorize, connect, and start indexing a new datasource. ↗

Parameters

• 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).

Example: start an authorization flow

const res = await igpt.connectors.authorize({
  service: "spike",
  scope: "messages",
  redirect_uri: "https://your-app.com/callback",
  state: "optional_state"
});

console.log(res);

Recall

recall.ask()

Generate a response based on input and connected context. ↗

Parameters

• input (string, required): The prompt/question to ask.

• user (string, optional if set in constructor): Unique user identifier.

• stream (boolean, optional, default: false): If true, 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

Example: text 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);

Example: JSON output

const res = await igpt.recall.ask({
  input: "Return a JSON object with { title, summary } for my last meeting.",
  output_format: "json"
});

console.log(res);

Example: Structured output with JSON Schema

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);

Example response (schema)

{
  "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"
    }
  ]
}

Streaming (SSE)

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.

Parameters (streaming-specific)

• stream must be true
• Other parameters are the same as recall.ask

Example: basic streaming

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);
  }
}

recall.search()

Search in connected datasources. ↗

Parameters

• 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).

Example: simple search

const res = await igpt.recall.search({
  query: "board meeting notes"
});

console.log(res);

Example: date-bounded search

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);

Datasources

datasources.list()

List datasources and indexing status. ↗

Parameters

• user (string, optional if set in constructor): Unique user identifier.

Example

const res = await igpt.datasources.list();
console.log(res);

datasources.disconnect()

Disconnect a datasource and remove indexed data. ↗

Parameters

• id (string, required): Datasource ID to disconnect (e.g., "service/id/type").
• user (string, optional if set in constructor): Unique user identifier.

Example

const res = await igpt.datasources.disconnect({
  id: "service/id/type"
});

console.log(res);

Advanced Configuration

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.

Constructor options

• apiKey (string, required): Your iGPT API key.
• user (string, optional): Default user identifier. If provided, you can omit user in 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).

Error handling

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 }

Client errors

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.

Server errors

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.

Security & compliance

• 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/

Resources

• Docs: https://docs.igpt.ai
• Playground: https://igpt.ai/hub/playground/
• Book a demo: https://www.igpt.ai/contact-sales/
• Contact: [email protected]

License

MIT