Skip to main content

​
Schema introspection

Every command below with arguments supports two read-only flags for tooling and AI agents:
  • --show-file-schema: print the JSON Schema for the full request object (the format --filename accepts).
  • --show-argument-schema <flag-name>: print the JSON Schema for one argument’s value. Pass the kebab flag name without the leading -- (e.g. session-id, not --session-id).
Both write pure JSON to stdout and never call the API. They cannot be combined with any other command-specific flag.

​
create

Start a new session Start a new session. The request body is a bare session object (no session wrapper). The server creates a session event and returns it. No required properties. Every field has a server-side fallback. Auto-generated properties (provided by the server when omitted):
  • session_id (string, UUID): Server generates a UUIDv4 if omitted or if the supplied value is not a valid UUID.
Optional properties with defaults:
  • event_name (string): Falls back to session_name when not provided; defaults to "unknown" if both are absent.
  • source (string): Defaults to "unknown".
Optional properties:
  • session_name (string): Display name for the session.
  • start_time (number): Session start time as Unix milliseconds. The session normalizer uses getInt64() which only accepts numeric types; if a string is passed, the server silently falls back to the current time.
  • end_time (number): Session end time as Unix milliseconds (same numeric-only caveat as start_time).
  • duration (number): Session duration in milliseconds.
  • config (object): Configuration associated with the session.
  • inputs (object): Input data for the session.
  • outputs (object): Output data from the session.
  • metadata (object): Arbitrary metadata.
  • user_properties (object): User properties.
  • children_ids (array of strings): IDs of child events.
Idempotent on session_id: posting twice with the same session_id merges metadata/user_properties into the existing session and returns the existing event.

​
Usage

honeyhive sessions create [options]

​
Options

FlagTypeRequiredDescription
--children-idsjsonnoIDs of child events in this session
--configjsonnoConfiguration associated with the session
--durationnumbernoSession duration in milliseconds
--end-timenumbernoSession end time as Unix milliseconds
--event-namestringnoFallback name if session_name is not provided
--inputsjsonnoInput data for the session
--metadatajsonnoArbitrary metadata for the session
--outputsjsonnoOutput data from the session
--session-idstringnoClient-provided session ID (server generates one if omitted)
--session-namestringnoDisplay name for the session
--sourcestringnoSource of the session (e.g., sdk-python)
--start-timenumbernoSession start time as Unix milliseconds
--user-propertiesjsonnoUser properties associated with the session
Also supports --show-file-schema, --show-argument-schema <flag-name>, and --filename. See Schema introspection for details.

​
create-event-batch

Add a batch of events to a session Add a batch of events to an existing session. Each event in the batch is stored with session_id set from the URL path, overriding any session_id in the event body. Each event must include event_type (one of chain, model, tool, session) and inputs. Unknown top-level fields and unknown per-event fields are rejected. Events are processed sequentially. For higher-throughput ingestion across sessions, use POST /v1/events/batch instead.

​
Usage

honeyhive sessions create-event-batch [options]

​
Options

FlagTypeRequiredDescription
--eventsjsonyesEvents to add to the session
--session-idstringyesSession ID to add events to
Also supports --show-file-schema, --show-argument-schema <flag-name>, and --filename. See Schema introspection for details.

​
Example response

{
  "success": true
}