npm package: @honeyhive/api-client
Description: Client for interacting with the HoneyHive REST API
Author: HoneyHive
Latest version: 2.0.0-rc2

`@honeyhive/api-client` is a fully autogenerated TypeScript client for the HoneyHive REST API. It provides a typed, one-to-one mapping of methods to REST API endpoints, organized into namespaces: `client.sessions`, `client.events`, `client.metrics`, 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 can provide full autocompletion and type checking for every API call.

For more information about HoneyHive, visit the [HoneyHive documentation](https://docs.honeyhive.ai/v2/).

## Installation

```sh
npm install @honeyhive/api-client
```

## Example: Logging a Trace

The following example traces an OpenAI chat completion call, mirroring what the [Python SDK's](https://honeyhiveai.github.io/python-sdk/) `@trace` decorator does under the hood. It starts a session, creates a model event for the LLM call, and updates it with the response.

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

// The API key is read from the HH_API_KEY environment variable.
const client = new Client();

// The API key is read from the OPENAI_API_KEY environment variable.
const openai = new OpenAI();

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

// 2. Create a model event for the OpenAI call
const startTime = Date.now();
const event = await client.events.createEvent({
  body: {
    event: {
      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
await client.events.updateEvent({
  body: {
    event_id: event.event_id,
    outputs: { content },
    duration: Date.now() - startTime,
    metadata: {
      model: completion.model,
      usage: completion.usage,
    },
  },
});
```

## 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
const client = new Client();
```

### apiKey option

Pass the key directly in `ClientConfig`. **Never hard-code the key or commit it to source control** — always read it from a secret store or environment variable:

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

### Custom middleware

For advanced scenarios (rotating keys, fetching tokens at request time, etc.), 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 — it 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
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 and additional use cases.