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';

// Ingestion uses HH_INGESTION_API_KEY, falling back to HH_PROJECT_API_KEY.
// 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. The client holds three credentials and selects one per operation:

Key	Environment variable	Constructor option	Used for
Data plane fine-grained	`HH_DATA_PLANE_API_KEY`	`dataPlaneApiKey`	Supported project-scoped operations
Ingestion	`HH_INGESTION_API_KEY`	`ingestionApiKey`	Creating sessions and writing events
Classic project	`HH_PROJECT_API_KEY`	`projectApiKey`	Other operations, and ingestion when no ingestion key is set

See API Keys to create the keys your workload needs.

Data plane API key

Set HH_DATA_PLANE_API_KEY to a complete hh_fgdp_ key, or pass dataPlaneApiKey. For supported methods, include project_id in the request, even when the key is rooted at that project:

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

const projectId = process.env.PROJECT_ID;
if (!projectId) throw new Error('Set PROJECT_ID to your HoneyHive project ID');

const client = new Client();
const charts = await client.charts.list({ project_id: projectId });
console.log(charts.data);

This example requires project.chart.list. Copy the project ID and data plane URL from Settings > Project > API Keys > Data Plane. Configure a non-default URL with HH_DATA_PLANE_URL or dataPlaneUrl. For a method with both legacy and scoped routes, omitting project_id selects the legacy route and project key, even if a data plane key is configured. The legacy chart, dataset, and datapoint calls are deprecated. Passing project_id selects the scoped route, which requires a data plane key and does not accept a project key. See the credential matrix. Data plane keys cannot send traces. Keep an ingestion key for telemetry and a project key for operations that still require it. The client validates typed key values at construction and rejects calls with missing credentials before sending them. Use client.dataPlaneApiKeys.create and client.ingestionApiKeys.create with an organization-rooted data plane key to issue project credentials. See How to create API keys programmatically.

Project API key

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 other keys, 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. Other methods never use the ingestion key.

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

With only an ingestion key configured, the client can call ingestion methods. Other methods fail before sending and name the required key. A client can be constructed without keys, but calls require a credential or custom authentication. At construction, the client validates typed keys supplied through options or environment variables. If a key has the wrong type or is incomplete, the error names its source and 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 can override the selected 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, each API key slot (masked, or (none) when unset), and the SDK package + version when the client is constructed. Useful for confirming which environment and credentials 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_******
// Data plane API key: (none)
// 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. All three credential slots are logged, with (none) for any unset credential. A classic project API key shows a recognized prefix and the last 4 characters. Ingestion and data plane fine-grained keys show their prefix and key id with the secret replaced by ******, matching the masked forms shown in the HoneyHive app. A typed key with a missing or malformed key id is replaced entirely with asterisks.

Python SDK

TypeScript Control Plane SDK

Semantic Conventions

OpenAPI Client

TypeScript API SDK

Installation

Quick start

Example: Creating and populating a dataset

Authorization

Data plane API key

Project API key

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

​Data plane API key

​Project API key

​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

Data plane API key

Project API key

Environment variable (recommended)

projectApiKey option

Ingestion API key

Custom middleware

Data plane URL

Verbose logging