TypeScript API SDK

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

Installation

npm install @honeyhive/api-client

Quick start

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

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

// The API key is read from the HH_PROJECT_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

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 a project API key, and an ingestion key has its own slot alongside it.

Environment variable (recommended)

Set the HH_PROJECT_API_KEY environment variable. The client reads it automatically when no projectApiKey option is provided:

const client = new Client();

The HH_API_KEY environment variable is deprecated and will be removed in the next major version. Using it logs a deprecation warning to stderr on client construction. Migrate to HH_PROJECT_API_KEY.

projectApiKey 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({
  projectApiKey: process.env.MY_HONEYHIVE_KEY,
});

The apiKey option is deprecated and will be removed in the next major version. Setting it logs a deprecation warning to stderr on client construction. Migrate to projectApiKey.

Ingestion API key

An ingestion API key (hh_ingst_) can be held alongside the project key, in the HH_INGESTION_API_KEY environment variable or the ingestionApiKey option. The methods that create sessions and create or update events (singly or in batches) send it when it is set, and fall back to the project key otherwise. Every other method uses the project key and never the ingestion key.

const client = new Client({
  projectApiKey: process.env.MY_HONEYHIVE_KEY,
  ingestionApiKey: process.env.MY_HONEYHIVE_INGESTION_KEY,
});

A client constructed with only an ingestion key works for those ingestion methods; any other method has no credential to send and gets a 404. Construction fails only when neither key is available and no middleware is supplied. The ingestion key’s value is checked at construction: anything that is not an hh_ingst_ key throws, naming where the value came from and the expected prefix.

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 projectApiKey or HH_PROJECT_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>.

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

export HH_DATA_PLANE_URL=https://honeyhive.example.com

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

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.

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.

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

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 project API key keeps the recognized prefix (hh_ for a project key, hh_ro_ for a read-only project key) and the last 4 characters; anything else renders as 8 fixed-width asterisks. An ingestion key renders as hh_ingst_<key id>_******, showing its id and none of its secret.

Python SDK

TypeScript Control Plane SDK

Semantic Conventions

OpenAPI Client

TypeScript API SDK

Installation

Quick start

Example: Creating and populating a dataset

Authorization

Environment variable (recommended)

projectApiKey option

Ingestion API key

Custom middleware

Data plane URL

Verbose logging

​Installation

​Quick start

​Example: Creating and populating a dataset

​Authorization

​Environment variable (recommended)

​projectApiKey option

​Ingestion API key

​Custom middleware

​Data plane URL

​Verbose logging

Installation

Quick start

Example: Creating and populating a dataset

Authorization

Environment variable (recommended)

projectApiKey option

Ingestion API key

Custom middleware

Data plane URL

Verbose logging