> ## Documentation Index > Fetch the complete documentation index at: https://docs.honeyhive.ai/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml https://raw.githubusercontent.com/honeyhiveai/honeyhive-openapi/main/openapi.yaml post /v1/sessions openapi: 3.1.0 info: title: HoneyHive Data Plane API license: name: MIT url: https://opensource.org/licenses/MIT version: 1.2.1 servers: - url: https://api.honeyhive.ai security: - BearerAuth: [] tags: - name: Charts description: > Define and manage saved charts. Charts are visualizations that aggregate metrics over time with bucketing, filters, and groupings. - name: Configurations description: > Manage prompt configurations, i.e. model parameters, message templates, and response settings that can be versioned and deployed without code changes. - name: Datapoints description: > Manage individual records inside datasets, including batch creation and mapping to source events. - name: Datasets description: > Curate collections of datapoints used as test sets for evaluations and experiments. - name: Events description: > Read and write trace events. Events are the spans that capture every step of an AI application's execution. - name: Experiments description: > Run, retrieve, and compare evaluation runs to measure how prompt or configuration changes affect agent performance. - name: Metric Versions description: > Snapshot, list, and deploy versions of a metric's definition so changes can be reviewed and rolled back without losing history. - name: Metrics description: > Define and run evaluators, i.e. automated quality checks that score traces against criteria like accuracy, safety, or correctness. - name: Queues description: > Manage annotation queues for human review of traces, turning expert feedback into labeled datasets. - name: Sessions description: > Group related trace events into sessions, the top-level container for a multi-step or multi-service AI interaction. paths: /v1/sessions: post: tags: - Sessions summary: Start a new session description: | 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. operationId: createSession requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StartSessionRequest' responses: '200': description: Session successfully started content: application/json: schema: $ref: '#/components/schemas/PostSessionStartResponse' '400': description: Bad request (invalid session data) components: schemas: StartSessionRequest: type: object properties: session_id: type: string description: Client-provided session ID (server generates one if omitted) session_name: type: string description: Display name for the session event_name: type: string description: Fallback name if session_name is not provided source: type: string description: Source of the session (e.g., sdk-python) start_time: type: number description: Session start time as Unix milliseconds end_time: type: number description: Session end time as Unix milliseconds duration: type: number description: Session duration in milliseconds config: type: object additionalProperties: {} description: Configuration associated with the session inputs: type: object additionalProperties: {} description: Input data for the session outputs: type: object additionalProperties: {} description: Output data from the session metadata: type: object additionalProperties: {} description: Arbitrary metadata for the session user_properties: type: object additionalProperties: {} description: User properties associated with the session children_ids: type: array items: type: string description: IDs of child events in this session additionalProperties: false description: Request body for POST /v1/sessions (bare session object) PostSessionStartResponse: type: object properties: event_id: type: string session_id: type: string parent_id: type: - string - 'null' children_ids: type: array items: type: string event_type: type: - string - 'null' event_name: type: - string - 'null' config: {} inputs: {} outputs: {} error: type: - string - 'null' source: type: - string - 'null' duration: type: - number - 'null' user_properties: {} metrics: {} feedback: {} metadata: {} org_id: type: string workspace_id: type: string project_id: type: string start_time: type: - number - 'null' end_time: type: - number - 'null' required: - event_id - session_id - org_id - workspace_id - project_id additionalProperties: {} description: Full session event object returned after starting a new session securitySchemes: BearerAuth: type: http scheme: bearer ````