Add /voice/:segment_id/events endpoint

specs/signalwire-rest/voice-api/_spec_.yaml

@@ -282,3 +282,64 @@ paths:
                       created_at:
                         type: string
                         format: date-time
+  /logs/{id}/events:
+    get:
+      operationId: Logs_listEvents
+      summary: List Log Events
+      description: |-
+        List all events for a specific log.
+
+        #### Permissions
+
+        The API token must include the following scopes: _Voice_.
+      tags:
+        - Logs
+      parameters:
+        - name: id
+          in: path
+          description: >-
+            Unique ID of the log. This is the segment_id you can find in Relay
+            call details in your Dashboard UI or in return objects when using
+            the SDK.
+          required: true
+          schema:
+            type: string
+            format: uuid
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: array
+                    items:
+                      allOf:
+                        - type: object
+                          properties:
+                            event_at:
+                              type: string
+                              format: date-time
+                              description: Timestamp when the event occurred
+                            level:
+                              type: string
+                              description: The log level of the event
+                              example: "info"
+                            name:
+                              type: string
+                              description: The name of the event
+                              example: "calling_call_initiated"
+                            details:
+                              type: object
+                              description: Additional details about the event if present. Structure varies by event type.
+                              example: {}
+                            log_id:
+                              type: string
+                              format: uuid
+                              description: A unique identifier for the log
+                            project_id:
+                              type: string
+                              format: uuid
+                              description: A unique identifier for the project.

specs/signalwire-rest/voice-api/logs/main.tsp

@@ -31,15 +31,30 @@ namespace VoiceAPI.Logs {
     @summary("Find a Log by ID")
     @doc("""
       Find a log by ID.
-      
+
       #### Permissions
-      
+
       The API token must include the following scopes: _Voice_.
       """)
     retrieve(...LogPathID):
       | LogRetrieveResponse
       | StatusCode401
       | StatusCode404
       | StatusCode500;
+
+    @summary("List Log Events")
+    @doc("""
+      List all events for a specific log.
+
+      #### Permissions
+
+      The API token must include the following scopes: _Voice_.
+      """)
+    @route("/{id}/events")
+    listEvents(...LogPathID):
+      | LogEventsListResponse
+      | StatusCode401
+      | StatusCode404
+      | StatusCode500;
   }
 }

specs/signalwire-rest/voice-api/logs/models/core.tsp

@@ -85,3 +85,32 @@ model VoiceLog {
   @example(null)
   parent_id: string | null;
 }
+
+@doc("Event entry for a voice log")
+model LogEvent {
+  @doc("Timestamp when the event occurred.")
+  @example(UTC_TIME_EXAMPLE)
+  event_at: utcDateTime;
+
+  @doc("Log level of the event.")
+  @example("info")
+  level: "info" | "warning" | "error" | "debug";
+
+  @doc("Name of the event.")
+  @example("calling_call_initiated")
+  name: string;
+
+  @doc("Additional details about the event. Structure varies by event type.")
+  @example(#{})
+  details: {};
+
+  @format("uuid")
+  @doc("Unique identifier for the project.")
+  @example("b7182dc2-00f3-40e4-a5ce-20f164b329df")
+  project_id: uuid;
+
+  @format("uuid")
+  @doc("Unique identifier for the log.")
+  @example("b7182dc2-00f3-40e4-a5ce-20f164b329df")
+  log_id: uuid;
+}

specs/signalwire-rest/voice-api/logs/models/responses.tsp

@@ -26,3 +26,9 @@ model LogListResponse {
 
 @doc("Response model for voice log retrieve endpoint")
 model LogRetrieveResponse is VoiceLog;
+
+@doc("Response model for log events list endpoint")
+model LogEventsListResponse {
+  @doc("Array of event entries for the log")
+  data: LogEvent[];
+}

specs/signalwire-rest/voice-api/tsp-output/@typespec/openapi3/openapi.yaml

@@ -103,6 +103,45 @@ paths:
                 $ref: '#/components/schemas/Types.StatusCodes.StatusCode500'
       tags:
         - Logs
+  /logs/{id}/events:
+    get:
+      operationId: Logs_listEvents
+      summary: List Log Events
+      description: |-
+        List all events for a specific log.
+
+        #### Permissions
+
+        The API token must include the following scopes: _Voice_.
+      parameters:
+        - $ref: '#/components/parameters/LogPathID'
+      responses:
+        '200':
+          description: The request has succeeded.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/LogEventsListResponse'
+        '401':
+          description: Access is unauthorized.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Types.StatusCodes.StatusCode401'
+        '404':
+          description: The server cannot find the requested resource.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Types.StatusCodes.StatusCode404'
+        '500':
+          description: Server error
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Types.StatusCodes.StatusCode500'
+      tags:
+        - Logs
 security:
   - BasicAuth: []
 components:
@@ -173,6 +212,62 @@ components:
           description: Charged amount.
           example: 0.121176
       description: Details on charges associated with this log.
+    LogEvent:
+      type: object
+      required:
+        - event_at
+        - level
+        - name
+        - details
+        - project_id
+        - log_id
+      properties:
+        event_at:
+          type: string
+          format: date-time
+          description: Timestamp when the event occurred.
+          example: '2024-05-06T12:20:00Z'
+        level:
+          type: string
+          enum:
+            - info
+            - warning
+            - error
+            - debug
+          description: Log level of the event.
+          example: info
+        name:
+          type: string
+          description: Name of the event.
+          example: calling_call_initiated
+        details:
+          type: object
+          description: Additional details about the event. Structure varies by event type.
+          example: {}
+        project_id:
+          allOf:
+            - $ref: '#/components/schemas/uuid'
+          format: uuid
+          description: Unique identifier for the project.
+          example: b7182dc2-00f3-40e4-a5ce-20f164b329df
+        log_id:
+          allOf:
+            - $ref: '#/components/schemas/uuid'
+          format: uuid
+          description: Unique identifier for the log.
+          example: b7182dc2-00f3-40e4-a5ce-20f164b329df
+      description: Event entry for a voice log
+    LogEventsListResponse:
+      type: object
+      required:
+        - data
+      properties:
+        data:
+          type: array
+          items:
+            $ref: '#/components/schemas/LogEvent'
+          description: Array of event entries for the log
+      description: Response model for log events list endpoint
     LogListResponse:
       type: object
       required: