profound

This library provides convenient access to the profound REST API from TypeScript or JavaScript.

The full API of this library can be found in api.md.

Contents

• Installation
• Usage
• API Reference
• Streaming
• Authentication
• Errors
• Client Options
• Request Options
• Retries and Timeouts
• Helpers
• Logging
• Requirements

Installation

npm install @profoundai/client

Usage

import Profound from '@profoundai/client';

const client = new Profound({
  apiKey: process.env['PROFOUND_API_KEY'], // defaults to the PROFOUND_API_KEY env var
  environment: 'production',
});

const category = await client.organizations.categories.list();

console.log(category);

The examples in the following sections assume a client configured as shown above.

See the API reference for every available operation.

Streaming

Streaming endpoints return an async iterator that yields results as the server emits them.

const stream = await client.prompts.streamAnswersV2({
  category_id: '7c9e6679-7425-40de-944b-e07fc1f90ae7',
  start_date: '',
  end_date: '',
});

for await (const event of stream) {
  console.log(event);
}

Authentication

Pass credentials to the generated client constructor. Environment variables are read automatically when supported by the target runtime.

| Option | Type | Default | Description | | --- | --- | --- | --- | | accessToken | string \| provider | - | Credential for the BearerAuth scheme. Defaults to PROFOUND_ACCESS_TOKEN. | | apiKey | string \| provider | - | Credential for the APIKeyHeader scheme. Defaults to PROFOUND_API_KEY. |

Declared schemes:

• APIKeyHeader API key in header X-API-Key
• BearerAuth bearer token

Errors

Non-success responses throw generated API errors. Error objects expose status, headers, response body, and request metadata where the target runtime supports it.

import { APIError } from '@profoundai/client';

try {
  const category = await client.organizations.categories.list();
} catch (err) {
  if (err instanceof APIError) {
    console.log(err.status, err.name, err.headers);
  }
  throw err;
}

Documented error statuses: 422.

Client Options

Configure the generated client by setting any of these options when you create it.

import Profound from '@profoundai/client';

const client = new Profound({
  timeout: 60000,
  maxRetries: 2,
  logLevel: 'debug',
});

| Option | Type | Default | Description | | --- | --- | --- | --- | | accessToken | string \| AuthTokenProvider | process.env["PROFOUND_ACCESS_TOKEN"] | Credential for the BearerAuth scheme. | | apiKey | string \| AuthTokenProvider | process.env["PROFOUND_API_KEY"] | Credential for the APIKeyHeader scheme. | | environment | Environment | - | Select one of the configured API environments. | | baseURL | string \| null | process.env["PROFOUND_BASE_URL"] | Override the default API base URL. Pass null when selecting a configured environment. | | timeout | number | 60000 | Maximum time in milliseconds to wait for a response before aborting a request. | | maxRetries | number | 2 | Number of retries for temporary failures. | | defaultHeaders | HeadersInit | - | Headers sent with every request. | | defaultQuery | Record<string, string \| undefined> | - | Query parameters sent with every request. | | fetchOptions | RequestInit | - | Additional fetch options sent with every request. | | fetch | Fetch | - | Custom fetch implementation. | | logLevel | "off" \| "error" \| "warn" \| "info" \| "debug" \| null | process.env["PROFOUND_LOG"] | Controls request and retry debug logging. | | logger | Logger \| null | console | Custom logger implementation. |

Request Options

| Option | Type | Default | Description | | --- | --- | --- | --- | | headers | HeadersInit | - | Per-request headers. | | query | Record<string, unknown> | - | Per-request query parameters. | | body | unknown | - | Override the generated request body. | | timeout | number | - | Per-request timeout in milliseconds. | | maxRetries | number | - | Per-request retry count. | | signal | AbortSignal | - | Abort an in-flight request. | | fetchOptions | RequestInit | - | Per-request fetch options. | | idempotencyKey | string | - | Idempotency key for retry-safe operations. Applies to this request and its retries. |

Retries and Timeouts

Generated clients support request timeouts and retry temporary failures such as network errors, 408, 409, 429, and 5xx responses. Retry delays honor Retry-After headers when present. Tune the retry and timeout client options shown above, or override them per request.

Helpers

• Use .withResponse() on any request to inspect both parsed data and the raw Response object.
• Every operation returns an APIPromise, so you can await it directly or chain .withResponse().

Logging

• Set logLevel: "debug" to log request URLs, options, response status, response headers, and retry attempts.
• Pass a custom logger to route logs into your own observability pipeline.
• Set logLevel: null to disable environment-driven logging.

Requirements

• Node.js 20+, a modern browser, or any runtime with fetch support

Powered by Scalar.