> ## Documentation Index
> Fetch the complete documentation index at: https://docs.honeyhive.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript API SDK

> Type-safe TypeScript client for the HoneyHive REST API

`@honeyhive/api-client` is a type-safe TypeScript client for the HoneyHive REST API. It provides a one-to-one mapping of methods to API endpoints, organized into namespaces: `client.datasets`, `client.datapoints`, `client.experiments`, etc.

Built on [openapi-fetch](https://openapi-ts.dev/openapi-fetch/), the client handles response parsing, query serialization, and error handling automatically. All request and response types are generated from the OpenAPI specification, so your editor provides full autocompletion and type checking for every API call.

If you're coming from the legacy `@honeyhive/logger` package, see the [migration guide](/v2/sdk-reference/typescript-logger-to-api-sdk-migration).

## Installation

```sh theme={null}
npm install @honeyhive/api-client
```

## Quick start

Create a session (trace) and log an OpenAI call:

```typescript theme={null}
import { Client } from '@honeyhive/api-client';
import OpenAI from 'openai';

// The API key is read from the HH_API_KEY environment variable.
// The data plane URL is read from the HH_DATA_PLANE_URL environment variable
// and defaults to https://api.dp1.us.honeyhive.ai
const client = new Client();
const openai = new OpenAI();

// 1. Start a session (trace)
const session = await client.sessions.create({
  session_name: 'openai-example',
  source: 'dev',
});

// 2. Create a model event for the OpenAI call
const startTime = Date.now();
const event = await client.events.create({
  session_id: session.session_id,
  event_type: 'model',
  event_name: 'chat-completion',
  config: { model: 'gpt-4o-mini' },
  inputs: {
    messages: [{ role: 'user', content: 'What is the meaning of life?' }],
  },
});

// 3. Make the OpenAI call
const completion = await openai.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'What is the meaning of life?' }],
});
const { content } = completion.choices[0].message;
console.log(content);

// 4. Update the event with the response
if (content) {
  await client.events.update({
    event_id: event.event_id,
    outputs: { content },
    duration: Date.now() - startTime,
    metadata: {
      model: completion.model,
      usage: completion.usage,
    },
  });
}
```

## Example: Creating and populating a dataset

```typescript theme={null}
import { Client } from '@honeyhive/api-client';

const client = new Client();

// 1. Create a dataset
const created = await client.datasets.create({
  name: 'qa-eval-set',
  description: 'Question/answer pairs for evaluation',
});
const datasetId = created.result.insertedId;

// 2. Append a datapoint linked to the new dataset
await client.datapoints.create({
  inputs: { question: 'What is the capital of France?' },
  ground_truth: { answer: 'Paris' },
  linked_datasets: [datasetId],
});

// 3. List datasets in the current project
const { datasets } = await client.datasets.list();
console.log(datasets.map((d) => d.name));

// 4. Delete the dataset
await client.datasets.delete({
  dataset_id: datasetId,
});
```

## Authorization

The HoneyHive API authenticates requests using an API key sent as a Bearer token in the `Authorization` header. There are three ways to provide it.

### Environment variable (recommended)

Set the `HH_API_KEY` environment variable. The client reads it automatically when no `apiKey` option is provided:

```typescript theme={null}
const client = new Client();
```

### apiKey option

Pass the key directly in `ClientConfig`.

<Note>
  Never hard-code the key or commit it to source control. Always read it from a secret store or environment variable.
</Note>

```typescript theme={null}
const client = new Client({
  apiKey: process.env.MY_HONEYHIVE_KEY,
});
```

### Custom middleware

For advanced scenarios (rotating keys, fetching tokens at request time), you can supply custom middleware that sets the `Authorization` header on each request. Middleware runs after the initial headers are set, so it will override any API key provided via `apiKey` or `HH_API_KEY`.

When middleware is provided without an API key, the client skips the missing-key error and assumes the middleware handles authentication. If both are provided, the API key sets the initial header and the middleware can override it per-request.

The required header format is `Authorization: Bearer <api-key>`.

```typescript theme={null}
import { Client, type Middleware } from '@honeyhive/api-client';

const authMiddleware: Middleware = {
  async onRequest({ request }) {
    const key = await fetchApiKeyFromVault();
    request.headers.set('Authorization', `Bearer ${key}`);
    return request;
  },
};

const client = new Client({
  middleware: [authMiddleware],
});
```

See the [openapi-fetch middleware documentation](https://openapi-ts.dev/openapi-fetch/middleware-auth) for more details on the `Middleware` interface.

## Data plane URL

By default the client talks to `https://api.dp1.us.honeyhive.ai`. To point at a self-hosted deployment or a staging environment, set the `HH_DATA_PLANE_URL` environment variable or pass `dataPlaneUrl`:

```sh theme={null}
export HH_DATA_PLANE_URL=https://honeyhive.example.com
```

```typescript theme={null}
const client = new Client({
  dataPlaneUrl: 'https://honeyhive.example.com',
});
```

<Warning>
  The `serverUrl` constructor option and the `HH_API_URL` environment variable are deprecated and will be removed in the next major version. Using either logs a deprecation warning to stderr on client construction. Migrate to `dataPlaneUrl` / `HH_DATA_PLANE_URL`.
</Warning>

## Verbose logging

Set `verbose: true` (or the `HH_VERBOSE` environment variable to `true`) to log the resolved data plane URL, a masked API key, and the SDK package + version when the client is constructed. Useful for confirming which environment and credential the client is configured with.

```typescript theme={null}
const client = new Client({ verbose: true });
// Data plane URL: https://api.dp1.us.honeyhive.ai
// API Key: hh_****5Qrg
// Package: @honeyhive/api-client v1.0.0
```

```sh theme={null}
HH_VERBOSE=true node my-script.js
```

Output is written via `console.error` (stderr in Node, devtools in the browser) and only fires once per client construction. An explicit `verbose: false` overrides `HH_VERBOSE`. The masked API key keeps the recognized prefix (`hh_`, `hh_org_`, `hh_ws_`, `hh_cp_`, `hh_dp_`) and the last 4 characters; anything else renders as 8 fixed-width asterisks.