exa-js 1.7.1 → 1.7.3

package/README.md

@@ -190,6 +190,34 @@ Each chunk contains:
 - `content`: A string containing the next piece of generated text
 - `citations`: An array of citation objects containing source information
 
+### `exa.research.createTask(input: object, options?: { schema?: object }): Promise<{id: string}>`
+
+Exa's research agent can autonomously gather information and return a structured JSON object that conforms to a schema you provide.
+
+```javascript
+import Exa from "exa-js";
+
+const exa = new Exa(process.env.EXA_API_KEY);
+
+const schema = {
+  type: "object",
+  required: ["answer"],
+  properties: {
+    answer: { type: "string" },
+  },
+};
+
+const { id: taskId } = await exa.research.createTask(
+  {
+    instructions: "In ≤3 sentences, explain quantum computing.",
+  },
+  { schema }
+);
+const result = await exa.research.pollTask(taskId);
+```
+
+Use the `status` field to poll long-running tasks if needed (a future `getTask` helper will be added when the async API is released).
+
 # Contributing
 
 Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.

package/dist/index.d.mts

@@ -5,11 +5,11 @@
 /**
  * Type for API query parameters
  */
-type QueryParams = Record<string, string | number | boolean | string[] | undefined>;
+type QueryParams$1 = Record<string, string | number | boolean | string[] | undefined>;
 /**
  * Type for API request body
  */
-interface RequestBody {
+interface RequestBody$1 {
     [key: string]: unknown;
 }
 /**
@@ -44,13 +44,13 @@ declare class WebsetsBaseClient {
      * @returns The response JSON
      * @throws ExaError with API error details if the request fails
      */
-    protected request<T = unknown>(endpoint: string, method?: string, data?: RequestBody, params?: QueryParams): Promise<T>;
+    protected request<T = unknown>(endpoint: string, method?: string, data?: RequestBody$1, params?: QueryParams$1): Promise<T>;
     /**
      * Helper to build pagination parameters
      * @param pagination The pagination parameters
      * @returns QueryParams object with pagination parameters
      */
-    protected buildPaginationParams(pagination?: PaginationParams): QueryParams;
+    protected buildPaginationParams(pagination?: PaginationParams): QueryParams$1;
 }
 
 interface components {
@@ -1340,6 +1340,103 @@ declare class WebsetsClient extends WebsetsBaseClient {
     } | number): Promise<Webset>;
 }
 
+type QueryParams = Record<string, string | number | boolean | string[] | undefined>;
+interface RequestBody {
+    [key: string]: unknown;
+}
+/**
+ * Base client class for all Research-related API clients
+ */
+declare class ResearchBaseClient {
+    protected client: Exa;
+    /**
+     * Initialize a new Research base client
+     * @param client The Exa client instance
+     */
+    constructor(client: Exa);
+    /**
+     * Make a request to the Research API (prefixes all paths with `/research`).
+     * @param endpoint The endpoint path, beginning with a slash (e.g. "/tasks").
+     * @param method The HTTP method. Defaults to "POST".
+     * @param data Optional request body
+     * @param params Optional query parameters
+     * @returns The parsed JSON response
+     */
+    protected request<T = unknown>(endpoint: string, method?: string, data?: RequestBody, params?: QueryParams): Promise<T>;
+}
+
+/**
+ * Client for interacting with the Research Tasks API.
+ */
+declare class ResearchClient extends ResearchBaseClient {
+    constructor(client: Exa);
+    /**
+     * Create a research task.
+     *
+     * Both parameters are required and have fixed shapes:
+     * 1. `input`
+     *      `{ instructions: string }`
+     *     • `instructions` – High-level guidance that tells the research agent what to do.
+     * 2. `output`
+     *    defines the exact structure you expect back, and guides the research conducted by the agent.
+     *      `{ schema: JSONSchema }`.
+     *    The agent's response will be validated against this schema.
+     *
+     * @param input  Object containing high-level research instructions.
+     * @param output Object containing the expected output schema.
+     * @returns The ResearchTaskResponse returned by the API.
+     */
+    createTask(input: {
+        instructions: string;
+    }, output: {
+        schema: JSONSchema;
+    }): Promise<{
+        id: string;
+    }>;
+    /**
+     * Retrieve a research task by ID.
+     */
+    getTask(id: string): Promise<ResearchTask>;
+    /**
+     * Poll a research task until completion or failure.
+     * Polls every 1 second with a maximum timeout of 10 minutes.
+     */
+    pollTask(id: string): Promise<ResearchTask>;
+}
+
+/**
+ * Enum representing the status of a research task.
+ */
+declare enum ResearchStatus {
+    /** The research task is still in progress. */
+    in_progress = "in_progress",
+    /** The research request has finished successfully. */
+    completed = "completed",
+    /** The research task request failed. */
+    failed = "failed"
+}
+/**
+ * Response object returned from the research API.
+ */
+type ResearchTask = {
+    /** Unique identifier for the task. */
+    id: string;
+    /** Current status. */
+    status: ResearchStatus;
+    /** The original instructions provided along with the task. */
+    instructions: string;
+    /** The original schema defining the task */
+    schema: Record<string, any>;
+    /** Structured output that follows the user-provided schema (null while running or if failed). */
+    data: Record<string, any> | null;
+    /**
+     * Citations collected while deriving each top-level field in `output`.
+     * The key is the field name, the value is the list of `SearchResult`s that
+     * were used to compute that field.
+     */
+    citations: Record<string, SearchResult<{}>[]>;
+};
+
 /**
  * HTTP status codes
  */
@@ -1694,29 +1791,6 @@ type AnswerStreamResponse = {
     answer?: string;
     citations?: SearchResult<{}>[];
 };
-/**
- * Enum representing the status of a research task.
- */
-declare enum ResearchStatus {
-    /** The research request has finished successfully. */
-    completed = "completed",
-    /** The research request failed. */
-    failed = "failed"
-}
-/**
- * @typedef {Object} ResearchTaskResponse
- * @property {string} id - The unique identifier of the research request.
- * @property {ResearchStatus | string} status - The current status of the research request.
- * @property {Record<string, any> | null} output - The structured output, if the research has completed.
- * @property {SearchResult<{}>[]} citations - References used for the research.
- */
-type ResearchTaskResponse = {
-    id: string;
-    status: ResearchStatus | string;
-    output: Record<string, any> | null;
-    citations: SearchResult<{}>[];
-};
-
 /**
  * The Exa class encapsulates the API's endpoints.
  */
@@ -1727,6 +1801,10 @@ declare class Exa {
      * Websets API client
      */
     websets: WebsetsClient;
+    /**
+     * Research API client
+     */
+    research: ResearchClient;
     /**
      * Helper method to separate out the contents-specific options from the rest.
      */
@@ -1833,42 +1911,7 @@ declare class Exa {
         outputSchema?: Record<string, unknown>;
     }): AsyncGenerator<AnswerStreamChunk>;
     private processChunk;
-    /**
-     * Creates and runs a research task in a blocking manner.
-     *
-     * Both parameters are required and have fixed shapes:
-     * 1. `input`
-     *      `{ instructions: string }`
-     *     • `instructions` – High-level guidance that tells the research agent what to do.
-     * 2. `output`
-     *    defines the exact structure you expect back, and guides the research conducted by the agent.
-     *      `{ schema: JSONSchema }`.
-     *    The agent’s response will be validated against this schema.
-     *
-     * @param {{ instructions: string }} input   The research prompt.
-     * @param {{ schema: JSONSchema }}                output  The desired output schema.
-     * @returns {Promise<ResearchTaskResponse>}                     The research response.
-     *
-     * @example
-     * const response = await exa.researchTask(
-     *   { instructions: "I need a few key facts about honey pot ants." },
-     *   {
-     *     schema: {
-     *       type: "object",
-     *       required: ["scientificName", "primaryRegions"],
-     *       properties: {
-     *         scientificName: { type: "string" },
-     *         primaryRegions:  { type: "string" },
-     *       },
-     *     },
-     *   },
-     * );
-     */
-    researchTask(input: {
-        instructions: string;
-    }, output: {
-        schema: JSONSchema;
-    }): Promise<ResearchTaskResponse>;
+    private parseSSEStream;
 }
 
-export { type AnswerOptions, type AnswerResponse, type AnswerStreamChunk, type AnswerStreamResponse, type BaseSearchOptions, type ContentsOptions, type ContentsResultComponent, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, type CreateEnrichmentParameters, CreateEnrichmentParametersFormat, type CreateWebhookParameters, type CreateWebsetParameters, type CreateWebsetSearchParameters, CreateWebsetSearchParametersBehaviour, type Default, type EnrichmentResult, type Event, EventType, Exa, ExaError, type ExtrasOptions, type ExtrasResponse, type FindSimilarOptions, type GetWebsetResponse, type HighlightsContentsOptions, type HighlightsResponse, HttpStatusCode, type JSONSchema, type ListEventsResponse, type ListWebhooksOptions, type ListWebhooksResponse, type ListWebsetItemResponse, type ListWebsetsOptions, type ListWebsetsResponse, type LivecrawlOptions, type RegularSearchOptions, ResearchStatus, type ResearchTaskResponse, type SearchResponse, type SearchResult, type SubpagesResponse, type SummaryContentsOptions, type SummaryResponse, type TextContentsOptions, type TextResponse, type UpdateWebhookParameters, type UpdateWebsetRequest, type Webhook, WebhookStatus, type Webset, type WebsetEnrichment, WebsetEnrichmentFormat, WebsetEnrichmentStatus, WebsetEnrichmentsClient, type WebsetItem, WebsetItemEvaluationSatisfied, WebsetItemSource, WebsetItemsClient, type WebsetSearch, WebsetSearchCanceledReason, WebsetSearchStatus, WebsetSearchesClient, WebsetStatus, WebsetWebhooksClient, WebsetsClient, Exa as default };
+export { type AnswerOptions, type AnswerResponse, type AnswerStreamChunk, type AnswerStreamResponse, type BaseSearchOptions, type ContentsOptions, type ContentsResultComponent, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, type CreateEnrichmentParameters, CreateEnrichmentParametersFormat, type CreateWebhookParameters, type CreateWebsetParameters, type CreateWebsetSearchParameters, CreateWebsetSearchParametersBehaviour, type Default, type EnrichmentResult, type Event, EventType, Exa, ExaError, type ExtrasOptions, type ExtrasResponse, type FindSimilarOptions, type GetWebsetResponse, type HighlightsContentsOptions, type HighlightsResponse, HttpStatusCode, type JSONSchema, type ListEventsResponse, type ListWebhooksOptions, type ListWebhooksResponse, type ListWebsetItemResponse, type ListWebsetsOptions, type ListWebsetsResponse, type LivecrawlOptions, type RegularSearchOptions, ResearchClient, ResearchStatus, type ResearchTask, type SearchResponse, type SearchResult, type SubpagesResponse, type SummaryContentsOptions, type SummaryResponse, type TextContentsOptions, type TextResponse, type UpdateWebhookParameters, type UpdateWebsetRequest, type Webhook, WebhookStatus, type Webset, type WebsetEnrichment, WebsetEnrichmentFormat, WebsetEnrichmentStatus, WebsetEnrichmentsClient, type WebsetItem, WebsetItemEvaluationSatisfied, WebsetItemSource, WebsetItemsClient, type WebsetSearch, WebsetSearchCanceledReason, WebsetSearchStatus, WebsetSearchesClient, WebsetStatus, WebsetWebhooksClient, WebsetsClient, Exa as default };

package/dist/index.d.ts

@@ -5,11 +5,11 @@
 /**
  * Type for API query parameters
  */
-type QueryParams = Record<string, string | number | boolean | string[] | undefined>;
+type QueryParams$1 = Record<string, string | number | boolean | string[] | undefined>;
 /**
  * Type for API request body
  */
-interface RequestBody {
+interface RequestBody$1 {
     [key: string]: unknown;
 }
 /**
@@ -44,13 +44,13 @@ declare class WebsetsBaseClient {
      * @returns The response JSON
      * @throws ExaError with API error details if the request fails
      */
-    protected request<T = unknown>(endpoint: string, method?: string, data?: RequestBody, params?: QueryParams): Promise<T>;
+    protected request<T = unknown>(endpoint: string, method?: string, data?: RequestBody$1, params?: QueryParams$1): Promise<T>;
     /**
      * Helper to build pagination parameters
      * @param pagination The pagination parameters
      * @returns QueryParams object with pagination parameters
      */
-    protected buildPaginationParams(pagination?: PaginationParams): QueryParams;
+    protected buildPaginationParams(pagination?: PaginationParams): QueryParams$1;
 }
 
 interface components {
@@ -1340,6 +1340,103 @@ declare class WebsetsClient extends WebsetsBaseClient {
     } | number): Promise<Webset>;
 }
 
+type QueryParams = Record<string, string | number | boolean | string[] | undefined>;
+interface RequestBody {
+    [key: string]: unknown;
+}
+/**
+ * Base client class for all Research-related API clients
+ */
+declare class ResearchBaseClient {
+    protected client: Exa;
+    /**
+     * Initialize a new Research base client
+     * @param client The Exa client instance
+     */
+    constructor(client: Exa);
+    /**
+     * Make a request to the Research API (prefixes all paths with `/research`).
+     * @param endpoint The endpoint path, beginning with a slash (e.g. "/tasks").
+     * @param method The HTTP method. Defaults to "POST".
+     * @param data Optional request body
+     * @param params Optional query parameters
+     * @returns The parsed JSON response
+     */
+    protected request<T = unknown>(endpoint: string, method?: string, data?: RequestBody, params?: QueryParams): Promise<T>;
+}
+
+/**
+ * Client for interacting with the Research Tasks API.
+ */
+declare class ResearchClient extends ResearchBaseClient {
+    constructor(client: Exa);
+    /**
+     * Create a research task.
+     *
+     * Both parameters are required and have fixed shapes:
+     * 1. `input`
+     *      `{ instructions: string }`
+     *     • `instructions` – High-level guidance that tells the research agent what to do.
+     * 2. `output`
+     *    defines the exact structure you expect back, and guides the research conducted by the agent.
+     *      `{ schema: JSONSchema }`.
+     *    The agent's response will be validated against this schema.
+     *
+     * @param input  Object containing high-level research instructions.
+     * @param output Object containing the expected output schema.
+     * @returns The ResearchTaskResponse returned by the API.
+     */
+    createTask(input: {
+        instructions: string;
+    }, output: {
+        schema: JSONSchema;
+    }): Promise<{
+        id: string;
+    }>;
+    /**
+     * Retrieve a research task by ID.
+     */
+    getTask(id: string): Promise<ResearchTask>;
+    /**
+     * Poll a research task until completion or failure.
+     * Polls every 1 second with a maximum timeout of 10 minutes.
+     */
+    pollTask(id: string): Promise<ResearchTask>;
+}
+
+/**
+ * Enum representing the status of a research task.
+ */
+declare enum ResearchStatus {
+    /** The research task is still in progress. */
+    in_progress = "in_progress",
+    /** The research request has finished successfully. */
+    completed = "completed",
+    /** The research task request failed. */
+    failed = "failed"
+}
+/**
+ * Response object returned from the research API.
+ */
+type ResearchTask = {
+    /** Unique identifier for the task. */
+    id: string;
+    /** Current status. */
+    status: ResearchStatus;
+    /** The original instructions provided along with the task. */
+    instructions: string;
+    /** The original schema defining the task */
+    schema: Record<string, any>;
+    /** Structured output that follows the user-provided schema (null while running or if failed). */
+    data: Record<string, any> | null;
+    /**
+     * Citations collected while deriving each top-level field in `output`.
+     * The key is the field name, the value is the list of `SearchResult`s that
+     * were used to compute that field.
+     */
+    citations: Record<string, SearchResult<{}>[]>;
+};
+
 /**
  * HTTP status codes
  */
@@ -1694,29 +1791,6 @@ type AnswerStreamResponse = {
     answer?: string;
     citations?: SearchResult<{}>[];
 };
-/**
- * Enum representing the status of a research task.
- */
-declare enum ResearchStatus {
-    /** The research request has finished successfully. */
-    completed = "completed",
-    /** The research request failed. */
-    failed = "failed"
-}
-/**
- * @typedef {Object} ResearchTaskResponse
- * @property {string} id - The unique identifier of the research request.
- * @property {ResearchStatus | string} status - The current status of the research request.
- * @property {Record<string, any> | null} output - The structured output, if the research has completed.
- * @property {SearchResult<{}>[]} citations - References used for the research.
- */
-type ResearchTaskResponse = {
-    id: string;
-    status: ResearchStatus | string;
-    output: Record<string, any> | null;
-    citations: SearchResult<{}>[];
-};
-
 /**
  * The Exa class encapsulates the API's endpoints.
  */
@@ -1727,6 +1801,10 @@ declare class Exa {
      * Websets API client
      */
     websets: WebsetsClient;
+    /**
+     * Research API client
+     */
+    research: ResearchClient;
     /**
      * Helper method to separate out the contents-specific options from the rest.
      */
@@ -1833,42 +1911,7 @@ declare class Exa {
         outputSchema?: Record<string, unknown>;
     }): AsyncGenerator<AnswerStreamChunk>;
     private processChunk;
-    /**
-     * Creates and runs a research task in a blocking manner.
-     *
-     * Both parameters are required and have fixed shapes:
-     * 1. `input`
-     *      `{ instructions: string }`
-     *     • `instructions` – High-level guidance that tells the research agent what to do.
-     * 2. `output`
-     *    defines the exact structure you expect back, and guides the research conducted by the agent.
-     *      `{ schema: JSONSchema }`.
-     *    The agent’s response will be validated against this schema.
-     *
-     * @param {{ instructions: string }} input   The research prompt.
-     * @param {{ schema: JSONSchema }}                output  The desired output schema.
-     * @returns {Promise<ResearchTaskResponse>}                     The research response.
-     *
-     * @example
-     * const response = await exa.researchTask(
-     *   { instructions: "I need a few key facts about honey pot ants." },
-     *   {
-     *     schema: {
-     *       type: "object",
-     *       required: ["scientificName", "primaryRegions"],
-     *       properties: {
-     *         scientificName: { type: "string" },
-     *         primaryRegions:  { type: "string" },
-     *       },
-     *     },
-     *   },
-     * );
-     */
-    researchTask(input: {
-        instructions: string;
-    }, output: {
-        schema: JSONSchema;
-    }): Promise<ResearchTaskResponse>;
+    private parseSSEStream;
 }
 
-export { type AnswerOptions, type AnswerResponse, type AnswerStreamChunk, type AnswerStreamResponse, type BaseSearchOptions, type ContentsOptions, type ContentsResultComponent, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, type CreateEnrichmentParameters, CreateEnrichmentParametersFormat, type CreateWebhookParameters, type CreateWebsetParameters, type CreateWebsetSearchParameters, CreateWebsetSearchParametersBehaviour, type Default, type EnrichmentResult, type Event, EventType, Exa, ExaError, type ExtrasOptions, type ExtrasResponse, type FindSimilarOptions, type GetWebsetResponse, type HighlightsContentsOptions, type HighlightsResponse, HttpStatusCode, type JSONSchema, type ListEventsResponse, type ListWebhooksOptions, type ListWebhooksResponse, type ListWebsetItemResponse, type ListWebsetsOptions, type ListWebsetsResponse, type LivecrawlOptions, type RegularSearchOptions, ResearchStatus, type ResearchTaskResponse, type SearchResponse, type SearchResult, type SubpagesResponse, type SummaryContentsOptions, type SummaryResponse, type TextContentsOptions, type TextResponse, type UpdateWebhookParameters, type UpdateWebsetRequest, type Webhook, WebhookStatus, type Webset, type WebsetEnrichment, WebsetEnrichmentFormat, WebsetEnrichmentStatus, WebsetEnrichmentsClient, type WebsetItem, WebsetItemEvaluationSatisfied, WebsetItemSource, WebsetItemsClient, type WebsetSearch, WebsetSearchCanceledReason, WebsetSearchStatus, WebsetSearchesClient, WebsetStatus, WebsetWebhooksClient, WebsetsClient, Exa as default };
+export { type AnswerOptions, type AnswerResponse, type AnswerStreamChunk, type AnswerStreamResponse, type BaseSearchOptions, type ContentsOptions, type ContentsResultComponent, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, type CreateEnrichmentParameters, CreateEnrichmentParametersFormat, type CreateWebhookParameters, type CreateWebsetParameters, type CreateWebsetSearchParameters, CreateWebsetSearchParametersBehaviour, type Default, type EnrichmentResult, type Event, EventType, Exa, ExaError, type ExtrasOptions, type ExtrasResponse, type FindSimilarOptions, type GetWebsetResponse, type HighlightsContentsOptions, type HighlightsResponse, HttpStatusCode, type JSONSchema, type ListEventsResponse, type ListWebhooksOptions, type ListWebhooksResponse, type ListWebsetItemResponse, type ListWebsetsOptions, type ListWebsetsResponse, type LivecrawlOptions, type RegularSearchOptions, ResearchClient, ResearchStatus, type ResearchTask, type SearchResponse, type SearchResult, type SubpagesResponse, type SummaryContentsOptions, type SummaryResponse, type TextContentsOptions, type TextResponse, type UpdateWebhookParameters, type UpdateWebsetRequest, type Webhook, WebhookStatus, type Webset, type WebsetEnrichment, WebsetEnrichmentFormat, WebsetEnrichmentStatus, WebsetEnrichmentsClient, type WebsetItem, WebsetItemEvaluationSatisfied, WebsetItemSource, WebsetItemsClient, type WebsetSearch, WebsetSearchCanceledReason, WebsetSearchStatus, WebsetSearchesClient, WebsetStatus, WebsetWebhooksClient, WebsetsClient, Exa as default };