HoneyHive TypeScript API SDK

@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.datasets, client.datapoints, client.experiments, etc.

Built on 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.

Installation

npm install @honeyhive/api-client
Copy

Example: Creating and logging a trace

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

// The API key is read from the HH_API_KEY environment variable.
// The Server URL is read from the HH_API_URL environment variable and defaults
// to https://api.dp1.us.honeyhive.ai
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.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 (span) with the response, if we got content back from OpenAI
if (content) {
  await client.events.update({
    event_id: event.event_id,
    outputs: { content },
    duration: Date.now() - startTime,
    metadata: {
      model: completion.model,
      usage: completion.usage,
    },
  });
}
Copy

Example: Creating and Populating a Dataset

The following example creates a dataset, appends a datapoint to it, lists the datasets in the project, and deletes the dataset when finished.

import { Client } from '@honeyhive/api-client';

// The API key is read from the HH_API_KEY environment variable.
// The Server URL is read from the HH_API_URL environment variable and defaults
// to https://api.dp1.us.honeyhive.ai
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,
});
Copy

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:

const client = new Client();
Copy

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:

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

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>.

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],
});
Copy

See the openapi-fetch middleware documentation for more details on the Middleware interface and additional use cases.

Verbose logging

Set verbose: true (or the HH_VERBOSE environment variable to true) to log the resolved API 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 — particularly when debugging "is this hitting prod or staging?" or "did HH_API_KEY actually get picked up?".

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

HH_VERBOSE=true node my-script.js
Copy

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.