Yoodli Speech API

openapi: 3.2.0
info:
  title: Yoodli API spec Speech API
  version: 1.0.0
  description: Operations on recordings and their feedback exports.
servers:
- url: https://app.yoodli.ai/api
  description: Official API server
- url: http://localhost:3001/api
  description: (Yoodli internal use only) local server
tags:
- name: Speech
  x-tag-expanded: false
  description: Operations on recordings and their feedback exports.
paths:
  /v3/speeches/{speechId}/feedback:
    get:
      summary: Download speech feedback
      tags:
      - Speech
      description: 'Returns a recording''s feedback: rubric goal scores, coaching feedback, reviewer

        comments, and transcript.


        Rate limit category: Fast API'
      parameters:
      - name: speechId
        in: path
        required: true
        description: Speech ID
        schema:
          type: string
      - name: sections
        in: query
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/RTFeedbackExportSection'
        style: form
        explode: true
        description: "Sections to include. May be repeated (e.g. `?sections=goals§ions=coaching_feedback`).\n All sections are included when omitted.\n\nPossible values:\n- `goals` – Goal/rubric scores and their feedback.\n- `coaching_feedback` – Coaching feedback remarks.\n- `user_comments` – Reviewer/user comments.\n- `transcript` – Full transcript."
      responses:
        '200':
          description: The recording's AI Coaching feedback.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FeedbackJsonResponse'
        '400':
          description: Invalid query parameters.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Not authorized to download this recording's feedback.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Recording not found, or not accessible to the caller.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
      operationId: getV3SpeechesBySpeechIdFeedback
      x-operation-id-source: derived
components:
  schemas:
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Error message. This is for developers, and not for end users or translated.
        code:
          type: string
          description: "Error code.\n Some API provide this field to identify a known mode of failure.\n The user is Frontend is recommended to translate this error code into a user friendly error message."
      required:
      - error
    FeedbackJsonResponse:
      type: object
      properties:
        version:
          examples:
          - '2.0'
          type: string
          description: Schema version (`major.minor`; minor bumps are additive, major are breaking).
        exported_at:
          examples:
          - '2026-02-11T15:00:00.000Z'
          type: string
          description: ISO 8601 timestamp when the export was generated.
        recording:
          type: object
          properties:
            id:
              examples:
              - aBcD2345eFgH6789iJkm
              type: string
              description: Recording identifier (the speech slug).
            title:
              examples:
              - Q3 Sales Pitch Practice
              type: string
              description: Recording title.
            date:
              examples:
              - '2026-02-11T10:00:00.000Z'
              type: string
              description: ISO 8601 timestamp of the recording.
            duration_seconds:
              examples:
              - 184
              oneOf:
              - type: number
              - type: 'null'
              description: Recording duration in seconds, or null when unavailable.
            type:
              examples:
              - LIVE
              type: string
              description: Recording type.
          required:
          - id
          - title
          - date
          - duration_seconds
          - type
          description: Recording metadata.
        speakers:
          type: object
          description: "Everyone who spoke in the recording, keyed by speaker ID. Human speakers use a\n numeric ID (as a string, e.g. `\"0\"`) that matches the `speaker_id` on transcript\n lines and feedback entries; AI participants use an ID starting with `ai_`."
        coaching_feedback_hidden:
          type: boolean
          description: "True when AI feedback is hidden from caller; When true, the `goals`,\n `coaching_feedback`, and `user_comments` sections are then empty"
        coaching_feedback_override_message:
          oneOf:
          - type: string
          - type: 'null'
          description: Message shown in place of coaching feedback when it is hidden, or null.
        goals:
          type: array
          items:
            type: object
            properties:
              goal_id:
                examples:
                - pace_control
                type: string
                description: Stable identifier of the goal.
              goal_name:
                examples:
                - Pace Control
                type: string
                description: Human-readable goal name.
              goal_kind:
                type: string
                enum:
                - score
                - binary
                - compound
                - talking_points
                - unscored
                description: 'The goal type; determines which score fields are present.


                  Possible values:

                  - `score`

                  - `binary`

                  - `compound`

                  - `talking_points`

                  - `unscored`'
              speaker_id:
                oneOf:
                - type: number
                - type: 'null'
                description: "ID of the speaker the goal was evaluated for, matching a key in the `speakers` map,\n or null when the goal applies to the whole recording."
              short_feedback:
                examples:
                - You maintained a steady, confident pace throughout.
                oneOf:
                - type: string
                - type: 'null'
                description: One-line feedback, or null when unavailable.
              long_feedback:
                oneOf:
                - type: string
                - type: 'null'
                description: Detailed feedback, or null when unavailable.
              human_evaluation:
                oneOf:
                - type: string
                - type: 'null'
                description: Human reviewer's evaluation, or null when none.
              score_numerator:
                examples:
                - 4
                type: number
                description: Points scored. Present for `score`, `compound`, and `talking_points` goals.
              score_denominator:
                examples:
                - 5
                type: number
                description: Maximum score. Present for `score`, `compound`, and `talking_points` goals.
              score:
                examples:
                - 1
                type: number
                description: 'Whether the goal was met: 1 (met) or 0 (not met). Present for `binary` goals.'
              sub_scores:
                type: array
                items:
                  type: object
                  properties:
                    name:
                      type: string
                      description: Sub-score name.
                    score_numerator:
                      type: number
                      description: Points scored for this component.
                  required:
                  - name
                  - score_numerator
                description: Named component scores. Present for `compound` goals.
              talking_points_hit:
                type: array
                items:
                  type: string
                description: Talking points fully covered. Present for `talking_points` goals.
              talking_points_partial:
                type: array
                items:
                  type: string
                description: Talking points partially covered. Present for `talking_points` goals.
              talking_points_miss:
                type: array
                items:
                  type: string
                description: Talking points not covered. Present for `talking_points` goals.
            required:
            - goal_id
            - goal_name
            - goal_kind
            - speaker_id
            - short_feedback
            - long_feedback
            - human_evaluation
          description: Goal results. Present only when the `goals` section is requested.
        coaching_feedback:
          type: array
          items:
            type: object
            properties:
              remark_id:
                examples:
                - conciseness
                type: string
                description: Identifier of the coaching type.
              speaker_id:
                oneOf:
                - type: number
                - type: 'null'
                description: "ID of the speaker the feedback applies to, matching a key in the `speakers` map,\n or null when the feedback applies to the whole recording."
              short_feedback:
                examples:
                - Aim to get to your main point sooner.
                type: string
                description: One-line feedback.
              long_feedback:
                oneOf:
                - type: string
                - type: 'null'
                description: Detailed feedback, or null when unavailable.
              created_at:
                examples:
                - '2026-02-11T10:05:00.000Z'
                type: string
                description: ISO 8601 timestamp when the feedback was created.
            required:
            - remark_id
            - speaker_id
            - short_feedback
            - long_feedback
            - created_at
          description: Coaching feedback. Present only when the `coaching_feedback` section is requested.
        user_comments:
          type: array
          items:
            type: object
            properties:
              commenter_name:
                examples:
                - Jordan Lee
                type: string
                description: Display name of the commenter.
              date:
                examples:
                - '2026-02-11T14:22:00.000Z'
                type: string
                description: ISO 8601 timestamp when the comment was made.
              timestamp_seconds:
                examples:
                - 42.5
                oneOf:
                - type: number
                - type: 'null'
                description: Video position the comment is anchored to, in seconds, or null when not anchored.
              comment:
                examples:
                - Strong close — this landed well.
                type: string
                description: The comment text.
            required:
            - commenter_name
            - date
            - timestamp_seconds
            - comment
          description: Reviewer/user comments. Present only when the `user_comments` section is requested.
        transcript:
          type: array
          items:
            type: object
            properties:
              speaker_id:
                examples:
                - 0
                oneOf:
                - type: number
                - type: 'null'
                description: "ID of the person who said this line, matching a key in the `speakers` map, or null\n when the line was spoken by the AI. `speaker_name` always gives the display name."
              speaker_name:
                examples:
                - Alex Rivera
                type: string
                description: Display name of the speaker for this line.
              start_seconds:
                examples:
                - 12.3
                type: number
                description: Line start offset from the beginning of the recording, in seconds.
              end_seconds:
                examples:
                - 15.8
                type: number
                description: Line end offset from the beginning of the recording, in seconds.
              text:
                examples:
                - Thanks for taking the time to meet with me today.
                type: string
                description: Transcribed text of the line.
            required:
            - speaker_id
            - speaker_name
            - start_seconds
            - end_seconds
            - text
          description: Transcript lines. Present only when the `transcript` section is requested.
      required:
      - version
      - exported_at
      - recording
      - speakers
      - coaching_feedback_hidden
      - coaching_feedback_override_message
    RTFeedbackExportSection:
      type: string
      enum:
      - goals
      - coaching_feedback
      - user_comments
      - transcript
      description: 'Possible values:

        - `goals` – Goal/rubric scores and their feedback.

        - `coaching_feedback` – Coaching feedback remarks.

        - `user_comments` – Reviewer/user comments.

        - `transcript` – Full transcript.'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer