> ## 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. # Create a new event > Create a new event (span) within a session trace. The request body is a bare event object (no `event` wrapper). **Required properties:** - `event_type` (string): Must be one of: `chain`, `model`, `tool`, `session`. - `inputs` (object): Input data for the event. **Auto-generated properties** (provided by the server when omitted): - `event_id` (string, UUID): Unique identifier for the event. - `session_id` (string, UUID): Session/trace identifier. - `parent_id` (string, UUID): Parent event ID. Defaults to `session_id`. **Optional properties with defaults:** - `event_name` (string): Name of the event. Defaults to `"unknown"`. - `source` (string): Source of the event (e.g. `sdk-python`). Defaults to `"unknown"`. **Optional properties:** - `config` (object): Configuration data (e.g. model parameters, prompt templates). - `outputs` (object): Output data from the event. - `error` (string or null): Error message if the event failed. - `children_ids` (array of strings): IDs of child events. - `duration` (number): Duration of the event in milliseconds. - `start_time` (number): Unix timestamp in milliseconds for event start. - `end_time` (number): Unix timestamp in milliseconds for event end. - `metadata` (object): Additional metadata (e.g. token counts, cost). - `metrics` (object): Custom metrics. - `feedback` (object): Feedback data (e.g. ratings, ground truth). - `user_properties` (object): User properties associated with the event. ## OpenAPI ````yaml https://raw.githubusercontent.com/honeyhiveai/honeyhive-openapi/main/openapi.yaml post /v1/events 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/events: post: tags: - Events summary: Create a new event description: > Create a new event (span) within a session trace. The request body is a bare event object (no `event` wrapper). **Required properties:** - `event_type` (string): Must be one of: `chain`, `model`, `tool`, `session`. - `inputs` (object): Input data for the event. **Auto-generated properties** (provided by the server when omitted): - `event_id` (string, UUID): Unique identifier for the event. - `session_id` (string, UUID): Session/trace identifier. - `parent_id` (string, UUID): Parent event ID. Defaults to `session_id`. **Optional properties with defaults:** - `event_name` (string): Name of the event. Defaults to `"unknown"`. - `source` (string): Source of the event (e.g. `sdk-python`). Defaults to `"unknown"`. **Optional properties:** - `config` (object): Configuration data (e.g. model parameters, prompt templates). - `outputs` (object): Output data from the event. - `error` (string or null): Error message if the event failed. - `children_ids` (array of strings): IDs of child events. - `duration` (number): Duration of the event in milliseconds. - `start_time` (number): Unix timestamp in milliseconds for event start. - `end_time` (number): Unix timestamp in milliseconds for event end. - `metadata` (object): Additional metadata (e.g. token counts, cost). - `metrics` (object): Custom metrics. - `feedback` (object): Feedback data (e.g. ratings, ground truth). - `user_properties` (object): User properties associated with the event. operationId: createEvent requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PostEventRequest' responses: '200': description: Event created successfully content: application/json: schema: $ref: '#/components/schemas/PostEventResponse' example: event_id: 7f22137a-6911-4ed3-bc36-110f1dde6b66 success: true '400': description: Bad request (invalid event data or missing required fields) components: schemas: PostEventRequest: type: object properties: project_id: type: string description: Project ID source: type: string description: Source of the event (e.g., sdk-python) event_name: type: string description: Name of the event event_type: type: string enum: - model - tool - chain - session description: Type of event (model, tool, chain, or session) event_id: type: string description: Unique event identifier session_id: type: string description: Session this event belongs to parent_id: type: string description: Parent event ID in the trace hierarchy children_ids: type: array items: type: string description: Child event IDs in the trace hierarchy config: type: object additionalProperties: {} description: Configuration used for this event inputs: type: object additionalProperties: {} description: Input data for the event outputs: type: object additionalProperties: {} description: Output data from the event error: type: - string - 'null' description: Error message if the event failed start_time: type: number description: Event start time as Unix milliseconds end_time: type: number description: Event end time as Unix milliseconds duration: type: number description: Event duration in milliseconds metadata: type: object additionalProperties: {} description: Arbitrary metadata for the event feedback: type: object additionalProperties: {} description: Feedback data associated with the event metrics: type: object additionalProperties: {} description: Metric values computed for the event user_properties: type: object additionalProperties: {} description: User properties associated with the event required: - event_type - inputs additionalProperties: false description: Request body for POST /v1/events (bare event object) PostEventResponse: type: object properties: success: type: boolean event_id: type: string required: - success - event_id description: Response after creating an event securitySchemes: BearerAuth: type: http scheme: bearer ````