feat: Add optional url parameter to proxy check endpoint

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 104
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-403eadeddcd92ecf5c0ada739fb59d73d829a9b463788a81ac3ed97d0cd3a64b.yml
-openapi_spec_hash: 8fdd3a5bd5e035f0adeb72329c215ad7
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/kernel%2Fkernel-f7024f4171c7c4ec558de1c27f338b1089ffddd0d2dbfdb9bb9f9c2abe8f47bf.yml
+openapi_spec_hash: ced43682b49e73a2862f99b49abb4fcd
 config_hash: 16e4457a0bb26e98a335a1c2a572290a

api.md

@@ -245,7 +245,7 @@ Methods:
 - <code title="get /proxies/{id}">client.proxies.<a href="./src/resources/proxies.ts">retrieve</a>(id) -> ProxyRetrieveResponse</code>
 - <code title="get /proxies">client.proxies.<a href="./src/resources/proxies.ts">list</a>() -> ProxyListResponse</code>
 - <code title="delete /proxies/{id}">client.proxies.<a href="./src/resources/proxies.ts">delete</a>(id) -> void</code>
-- <code title="post /proxies/{id}/check">client.proxies.<a href="./src/resources/proxies.ts">check</a>(id) -> ProxyCheckResponse</code>
+- <code title="post /proxies/{id}/check">client.proxies.<a href="./src/resources/proxies.ts">check</a>(id, { ...params }) -> ProxyCheckResponse</code>
 
 # Extensions
 

src/client.ts

@@ -92,6 +92,7 @@ import {
 import { ProfileCreateParams, ProfileListParams, Profiles } from './resources/profiles';
 import {
   Proxies,
+  ProxyCheckParams,
   ProxyCheckResponse,
   ProxyCreateParams,
   ProxyCreateResponse,
@@ -1021,6 +1022,7 @@ export declare namespace Kernel {
     type ProxyListResponse as ProxyListResponse,
     type ProxyCheckResponse as ProxyCheckResponse,
     type ProxyCreateParams as ProxyCreateParams,
+    type ProxyCheckParams as ProxyCheckParams,
   };
 
   export {

src/resources/index.ts

@@ -103,4 +103,5 @@ export {
   type ProxyListResponse,
   type ProxyCheckResponse,
   type ProxyCreateParams,
+  type ProxyCheckParams,
 } from './proxies';

src/resources/proxies.ts

@@ -42,10 +42,19 @@ export class Proxies extends APIResource {
   }
 
   /**
-   * Run a health check on the proxy to verify it's working.
+   * Run a health check on the proxy to verify it's working. Optionally specify a URL
+   * to test reachability against a specific target. For ISP and datacenter proxies,
+   * this reliably tests whether the target site is reachable from the proxy's stable
+   * exit IP. For residential and mobile proxies, the exit node varies between
+   * requests, so this validates proxy configuration and connectivity rather than
+   * guaranteeing site-specific reachability.
    */
-  check(id: string, options?: RequestOptions): APIPromise<ProxyCheckResponse> {
-    return this._client.post(path`/proxies/${id}/check`, options);
+  check(
+    id: string,
+    body: ProxyCheckParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<ProxyCheckResponse> {
+    return this._client.post(path`/proxies/${id}/check`, { body, ...options });
   }
 }
 
@@ -1183,12 +1192,29 @@ export namespace ProxyCreateParams {
   }
 }
 
+export interface ProxyCheckParams {
+  /**
+   * An optional URL to test reachability against. If provided, the proxy check will
+   * test connectivity to this URL instead of the default test URLs. Only HTTP and
+   * HTTPS schemes are allowed, and the URL must resolve to a public IP address. For
+   * ISP and datacenter proxies, the exit IP is stable, so a successful check
+   * reliably indicates that subsequent browser sessions will reach the target site
+   * with the same IP. For residential and mobile proxies, the exit node changes
+   * between requests, so a successful check validates proxy configuration but does
+   * not guarantee that a subsequent browser session will use the same exit IP or
+   * reach the same site — it is useful for verifying credentials and connectivity,
+   * not for predicting site-specific behavior.
+   */
+  url?: string;
+}
+
 export declare namespace Proxies {
   export {
     type ProxyCreateResponse as ProxyCreateResponse,
     type ProxyRetrieveResponse as ProxyRetrieveResponse,
     type ProxyListResponse as ProxyListResponse,
     type ProxyCheckResponse as ProxyCheckResponse,
     type ProxyCreateParams as ProxyCreateParams,
+    type ProxyCheckParams as ProxyCheckParams,
   };
 }

tests/api-resources/proxies.test.ts

@@ -78,4 +78,12 @@ describe('resource proxies', () => {
     expect(dataAndResponse.data).toBe(response);
     expect(dataAndResponse.response).toBe(rawResponse);
   });
+
+  // Mock server tests are disabled
+  test.skip('check: request options and params are passed correctly', async () => {
+    // ensure the request options are being passed correctly by passing an invalid HTTP method in order to cause an error
+    await expect(
+      client.proxies.check('id', { url: 'url' }, { path: '/_stainless_unknown_path' }),
+    ).rejects.toThrow(Kernel.NotFoundError);
+  });
 });