Implementation:Helicone Helicone Jawn Swagger Spec

Knowledge Sources	Helicone
Domains	API Specification, Backend
Last Updated	2026-02-14 06:32 GMT

Overview

Auto-generated OpenAPI 3.0 specification for the Jawn backend API, containing 254 endpoints across 25+ controller groups with full request/response type definitions.

Description

This is the comprehensive Swagger/OpenAPI specification for Helicone's Jawn backend service, auto-generated from TSOA controller decorators. At 26,694 lines, it defines every REST endpoint, request body schema, response type, and authentication scheme used by the Jawn Express.js server. The spec covers all backend functionality including request management, metrics, experiments, prompts, evals, sessions, webhooks, billing (Stripe), user management, and more. It uses the Result<T, string> pattern throughout, where responses are either ResultSuccess (with data) or ResultError (with error string). The spec is referenced by docs/docs.json to power the auto-generated API reference documentation on the Helicone docs site.

Usage

This specification is consumed by the Mintlify documentation system to generate interactive API documentation. It also serves as the definitive API contract for frontend-backend type consistency and can be used for client SDK generation.

Code Reference

Source Location

• Repository: Helicone
• File: docs/swagger.json

Spec Metadata

{
  "openapi": "3.0.0",
  "components": {
    "schemas": { ... },
    "examples": {},
    "headers": {},
    "parameters": {},
    "requestBodies": {},
    "responses": {}
  },
  "paths": { ... }
}

Controller Groups

The 254 endpoints are organized into the following controller groups:

Controller	Endpoints	Description
experiment	47	Experiment CRUD, hypothesis management, runs, scoring, datasets
prompt-2025	23	Prompt v2025 management (create, version, tag, rename, environment, query)
stripe	22	Subscription management, checkout, invoices, usage, billing
metrics	20	Analytics queries (total requests, cost, latency, TTFT, tokens, time series)
prompt	17	Legacy prompt management (query, create, versions, inputs)
public	17	Public endpoints (model registry, stats, waitlist, shared resources)
evaluator	10	Evaluator CRUD, online evaluators, experiment associations
request	9	Request queries (ClickHouse, PostgreSQL), feedback, scoring, properties
agent	8	AI agent threads, messaging, escalation
property	8	Property queries, hide/restore, key-value management
helicone-dataset	7	Dataset CRUD, mutation, querying, random sampling
helicone-sql	7	HQL schema, execute, download, saved queries
api-keys	6	Provider key and proxy key management
credits	6	Credit balance, payments, spend breakdown, invoices
integration	6	Integrations management, Slack settings
session	6	Session queries, metrics, feedback, request retrieval
pi	5	Partner/PI analytics (sessions, org names, costs, requests)
trace	5	Custom trace logging (typed, untyped, Python)
evals	4	Eval queries, scoring, score distributions
vault	4	Secret vault (add, list, get, update provider keys)
webhooks	3	Webhook CRUD and testing
user	3	User metrics overview, metrics query, user query
customer	2	Customer usage and query
models	2	Model listing and multimodal model listing
playground	2	Playground generation and request-through-Helicone
wrapped	2	Year-in-review wrapped data
providers	1	Provider listing
dashboard	1	Dashboard scores query
test	1	Gateway request testing

Key Schema Patterns

Result Type Pattern

All API responses follow the discriminated union pattern:

// Success case
interface ResultSuccess<T> {
  data: T;
  error: null;
}

// Error case
interface ResultError {
  data: null;
  error: string;
}

// Combined
type Result<T> = ResultSuccess<T> | ResultError;

Common Schemas

Schema	Description
CreateProviderKeyRequest	Provider key creation with name, secret, config, BYOK flag
DecryptedProviderKey	Full provider key details including secret
ProviderKeyRow	Provider key list item (without secret)
UpdateProviderKeyRequest	Provider key update fields
Record_string.string_	Generic string-to-string record type
Record_string.any_	Generic string-to-any record type

I/O Contract

Inputs

Name	Type	Required	Description
TSOA controllers	TypeScript	Yes	Decorated controller classes in /valhalla/jawn/src/controllers/

Outputs

Name	Type	Description
swagger.json	JSON	OpenAPI 3.0 specification with all endpoints and schemas

Spec Statistics

• Total Lines: 26,694
• Total Endpoints: 254
• Controller Groups: 25+
• OpenAPI Version: 3.0.0
• Generation: Auto-generated from TSOA decorators

Related Pages

• Principle:Helicone_Helicone_API_Specification