From 7cf9bbac090f436fcb8e28cb03216626bb615fe9 Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Wed, 27 May 2026 17:51:29 +0000 Subject: [PATCH 1/2] feat(api): search_context_size, background tasks, reasoning effort xhigh + responses.retrieve API-2610: add search_context_size to Search API (low/medium/high, default low) API-2621: add background tasks (background:true + GET /v1/responses/{id} polling) + add 'minimal' and 'xhigh' to reasoning.effort enum + add 'queued' and 'cancelled' to Status enum --- .stats.yml | 8 +-- api.md | 2 + src/client.ts | 2 + src/resources/index.ts | 1 + src/resources/responses.ts | 91 ++++++++++++++++++++++++--- src/resources/search.ts | 6 ++ tests/api-resources/responses.test.ts | 15 ++++- tests/api-resources/search.test.ts | 1 + 8 files changed, 113 insertions(+), 13 deletions(-) diff --git a/.stats.yml b/.stats.yml index 18e9f23..aa3b4f6 100644 --- a/.stats.yml +++ b/.stats.yml @@ -1,4 +1,4 @@ -configured_endpoints: 10 -openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/perplexity-ai/perplexity-fcf27eaa172b35187bd87aa80b4d18e2b05c5a8544734d56bd4079064bec4bb4.yml -openapi_spec_hash: 35a516eefbd34cf6620a114bf28c27a5 -config_hash: 86d643a5df0d7478c095d3efa13438dd +configured_endpoints: 11 +openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/perplexity-ai/perplexity-fff71875865f090e567436080392bfe633cefac2a82f5eba143ca6fcfed86a56.yml +openapi_spec_hash: 2cb780b456c70cbdcb1ba0182f424c9b +config_hash: 059988c88f0dc18e9e393daed94b5eb6 diff --git a/api.md b/api.md index 24eafe8..2231022 100644 --- a/api.md +++ b/api.md @@ -54,10 +54,12 @@ Types: - ResponsesCreateParams - ResponsesUsage - ResponseCreateResponse +- ResponseRetrieveResponse Methods: - client.responses.create({ ...params }) -> ResponseCreateResponse +- client.responses.retrieve(responseID) -> ResponseRetrieveResponse # Embeddings diff --git a/src/client.ts b/src/client.ts index cf2129d..5ff98d5 100644 --- a/src/client.ts +++ b/src/client.ts @@ -35,6 +35,7 @@ import { ResponseCreateParamsNonStreaming, ResponseCreateParamsStreaming, ResponseCreateResponse, + ResponseRetrieveResponse, ResponseStreamChunk, Responses, ResponsesCreateParams, @@ -799,6 +800,7 @@ export declare namespace Perplexity { type ResponsesCreateParams as ResponsesCreateParams, type ResponsesUsage as ResponsesUsage, type ResponseCreateResponse as ResponseCreateResponse, + type ResponseRetrieveResponse as ResponseRetrieveResponse, type ResponseCreateParams as ResponseCreateParams, type ResponseCreateParamsNonStreaming as ResponseCreateParamsNonStreaming, type ResponseCreateParamsStreaming as ResponseCreateParamsStreaming, diff --git a/src/resources/index.ts b/src/resources/index.ts index 29654c9..15f32b6 100644 --- a/src/resources/index.ts +++ b/src/resources/index.ts @@ -23,6 +23,7 @@ export { type ResponsesCreateParams, type ResponsesUsage, type ResponseCreateResponse, + type ResponseRetrieveResponse, type ResponseCreateParams, type ResponseCreateParamsNonStreaming, type ResponseCreateParamsStreaming, diff --git a/src/resources/responses.ts b/src/resources/responses.ts index c26b693..eae32c0 100644 --- a/src/resources/responses.ts +++ b/src/resources/responses.ts @@ -7,6 +7,7 @@ import { APIPromise } from '../core/api-promise'; import { Stream } from '../core/streaming'; import { RequestOptions } from '../internal/request-options'; import { addOutputText } from '../lib/add-output-text'; +import { path } from '../internal/utils/path'; export class Responses extends APIResource { /** @@ -43,6 +44,13 @@ export class Responses extends APIResource { return promise as APIPromise>; } + + /** + * Retrieve a response by its ID. Use this to poll the status of background tasks. + */ + retrieve(responseID: string, options?: RequestOptions): APIPromise { + return this._client.get(path`/v1/responses/${responseID}`, options); + } } /** @@ -97,7 +105,7 @@ export interface FunctionCallOutputItem { /** * Status of a response or output item */ - status: 'completed' | 'failed' | 'in_progress' | 'requires_action'; + status: 'completed' | 'failed' | 'in_progress' | 'queued' | 'cancelled' | 'requires_action'; type: 'function_call'; @@ -227,7 +235,7 @@ export namespace OutputItem { /** * Status of a response or output item */ - status: 'completed' | 'failed' | 'in_progress' | 'requires_action'; + status: 'completed' | 'failed' | 'in_progress' | 'queued' | 'cancelled' | 'requires_action'; type: 'message'; } @@ -346,7 +354,12 @@ export namespace ResponseStreamChunk { /** * Status of a response or output item */ - status: 'completed' | 'failed' | 'in_progress' | 'requires_action'; + status: 'completed' | 'failed' | 'in_progress' | 'queued' | 'cancelled' | 'requires_action'; + + /** + * Whether the response was created in background mode. + */ + background?: boolean; error?: ResponsesAPI.ErrorInfo; @@ -396,7 +409,12 @@ export namespace ResponseStreamChunk { /** * Status of a response or output item */ - status: 'completed' | 'failed' | 'in_progress' | 'requires_action'; + status: 'completed' | 'failed' | 'in_progress' | 'queued' | 'cancelled' | 'requires_action'; + + /** + * Whether the response was created in background mode. + */ + background?: boolean; error?: ResponsesAPI.ErrorInfo; @@ -445,7 +463,12 @@ export namespace ResponseStreamChunk { /** * Status of a response or output item */ - status: 'completed' | 'failed' | 'in_progress' | 'requires_action'; + status: 'completed' | 'failed' | 'in_progress' | 'queued' | 'cancelled' | 'requires_action'; + + /** + * Whether the response was created in background mode. + */ + background?: boolean; error?: ResponsesAPI.ErrorInfo; @@ -706,6 +729,13 @@ export interface ResponsesCreateParams { */ input: string | Array; + /** + * Run the response asynchronously. When true, the request is queued and the + * response object's `status` will be `queued` or `in_progress`. Poll GET + * /v1/responses/{response_id} to retrieve the final result. + */ + background?: boolean | null; + /** * System instructions for the model */ @@ -778,7 +808,7 @@ export namespace ResponsesCreateParams { /** * How much effort the model should spend on reasoning */ - effort?: 'low' | 'medium' | 'high'; + effort?: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'; } export interface WebSearchTool { @@ -936,7 +966,44 @@ export interface ResponseCreateResponse { /** * Status of a response or output item */ - status: 'completed' | 'failed' | 'in_progress' | 'requires_action'; + status: 'completed' | 'failed' | 'in_progress' | 'queued' | 'cancelled' | 'requires_action'; + + /** + * Whether the response was created in background mode. + */ + background?: boolean; + + error?: ErrorInfo; + + usage?: ResponsesUsage; +} + +/** + * Non-streaming response returned when stream is false + */ +export interface ResponseRetrieveResponse { + id: string; + + created_at: number; + + model: string; + + /** + * Object type in API responses + */ + object: 'response'; + + output: Array; + + /** + * Status of a response or output item + */ + status: 'completed' | 'failed' | 'in_progress' | 'queued' | 'cancelled' | 'requires_action'; + + /** + * Whether the response was created in background mode. + */ + background?: boolean; error?: ErrorInfo; @@ -957,6 +1024,13 @@ export interface ResponseCreateParamsBase { */ input: string | Array; + /** + * Run the response asynchronously. When true, the request is queued and the + * response object's `status` will be `queued` or `in_progress`. Poll GET + * /v1/responses/{response_id} to retrieve the final result. + */ + background?: boolean | null; + /** * System instructions for the model */ @@ -1029,7 +1103,7 @@ export namespace ResponseCreateParams { /** * How much effort the model should spend on reasoning */ - effort?: 'low' | 'medium' | 'high'; + effort?: 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'; } export interface WebSearchTool { @@ -1149,6 +1223,7 @@ export declare namespace Responses { type ResponsesCreateParams as ResponsesCreateParams, type ResponsesUsage as ResponsesUsage, type ResponseCreateResponse as ResponseCreateResponse, + type ResponseRetrieveResponse as ResponseRetrieveResponse, type ResponseCreateParams as ResponseCreateParams, type ResponseCreateParamsNonStreaming as ResponseCreateParamsNonStreaming, type ResponseCreateParamsStreaming as ResponseCreateParamsStreaming, diff --git a/src/resources/search.ts b/src/resources/search.ts index 44b743e..a2e9a8f 100644 --- a/src/resources/search.ts +++ b/src/resources/search.ts @@ -56,6 +56,12 @@ export interface SearchCreateParams { search_before_date_filter?: string | null; + /** + * Controls how much search context is retrieved. Higher values return more content + * per result. + */ + search_context_size?: 'low' | 'medium' | 'high' | null; + search_domain_filter?: Array | null; search_language_filter?: Array | null; diff --git a/tests/api-resources/responses.test.ts b/tests/api-resources/responses.test.ts index cf715c9..00bc2f4 100644 --- a/tests/api-resources/responses.test.ts +++ b/tests/api-resources/responses.test.ts @@ -24,6 +24,7 @@ describe('resource responses', () => { test.skip('create: required and optional params', async () => { const response = await client.responses.create({ input: 'string', + background: true, instructions: 'instructions', language_preference: 'language_preference', max_output_tokens: 1, @@ -31,7 +32,7 @@ describe('resource responses', () => { model: 'model', models: ['string'], preset: 'preset', - reasoning: { effort: 'low' }, + reasoning: { effort: 'minimal' }, response_format: { type: 'json_schema', json_schema: { @@ -66,4 +67,16 @@ describe('resource responses', () => { ], }); }); + + // Mock server tests are disabled + test.skip('retrieve', async () => { + const responsePromise = client.responses.retrieve('response_id'); + const rawResponse = await responsePromise.asResponse(); + expect(rawResponse).toBeInstanceOf(Response); + const response = await responsePromise; + expect(response).not.toBeInstanceOf(Response); + const dataAndResponse = await responsePromise.withResponse(); + expect(dataAndResponse.data).toBe(response); + expect(dataAndResponse.response).toBe(rawResponse); + }); }); diff --git a/tests/api-resources/search.test.ts b/tests/api-resources/search.test.ts index 009f0df..55a676a 100644 --- a/tests/api-resources/search.test.ts +++ b/tests/api-resources/search.test.ts @@ -33,6 +33,7 @@ describe('resource search', () => { max_tokens_per_page: 0, search_after_date_filter: 'search_after_date_filter', search_before_date_filter: 'search_before_date_filter', + search_context_size: 'low', search_domain_filter: ['string'], search_language_filter: ['string'], search_mode: 'web', From e6caf811deb8991311af3434dea75e43ef497742 Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Wed, 27 May 2026 17:52:19 +0000 Subject: [PATCH 2/2] release: 0.30.0 --- .release-please-manifest.json | 2 +- CHANGELOG.md | 8 ++++++++ package.json | 2 +- src/version.ts | 2 +- 4 files changed, 11 insertions(+), 3 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 712789e..716d004 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,3 @@ { - ".": "0.29.1" + ".": "0.30.0" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 43f1303..6f5a2f5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,13 @@ # Changelog +## 0.30.0 (2026-05-27) + +Full Changelog: [v0.29.1...v0.30.0](https://github.com/perplexityai/perplexity-node/compare/v0.29.1...v0.30.0) + +### Features + +* **api:** search_context_size, background tasks, reasoning effort xhigh + responses.retrieve ([7cf9bba](https://github.com/perplexityai/perplexity-node/commit/7cf9bbac090f436fcb8e28cb03216626bb615fe9)) + ## 0.29.1 (2026-05-27) Full Changelog: [v0.29.0...v0.29.1](https://github.com/perplexityai/perplexity-node/compare/v0.29.0...v0.29.1) diff --git a/package.json b/package.json index 4111570..f34d9be 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@perplexity-ai/perplexity_ai", - "version": "0.29.1", + "version": "0.30.0", "description": "The official TypeScript library for the Perplexity API", "author": "Perplexity ", "types": "dist/index.d.ts", diff --git a/src/version.ts b/src/version.ts index b8b7a27..91a9bb6 100644 --- a/src/version.ts +++ b/src/version.ts @@ -1 +1 @@ -export const VERSION = '0.29.1'; // x-release-please-version +export const VERSION = '0.30.0'; // x-release-please-version