Yoodli API

openapi: 3.1.0
info:
  title: Yoodli API spec
  version: 1.0.0
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: Organization User Management
  x-tag-expanded: false
  description: Operations on members of Organizations and their User Groups.
- name: User Group Management
  x-tag-expanded: false
  description: Operations on User Groups.
- name: Multi Org Management
  x-tag-expanded: false
  description: Operations on Multi Org feature.
- name: Speech
  x-tag-expanded: false
  description: Operations on recordings and their feedback exports.
paths:
  /v3/enterprises/{enterpriseId}:
    get:
      summary: Get Multi Org details
      tags:
      - Multi Org Management
      description: 'Retrieves detailed information about a Multi Org including administrators,

        member Organizations, and seat pool usage statistics.


        Rate limit category: Fast API'
      parameters:
      - name: enterpriseId
        in: path
        required: true
        description: Multi Org ID.
        schema:
          type: string
      responses:
        '200':
          description: Multi Org details retrieved successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetEnterpriseResponse'
        '403':
          description: Permission denied. The caller is not an administrator of this Multi Org.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Multi Org not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
  /v3/enterprises/{enterpriseId}/orgs/{orgId}:
    patch:
      summary: Update settings of an Organization in a Multi Org
      tags:
      - Multi Org Management
      description: 'Updates seat allocation of an Organization within a Multi Org.


        Rate limit category: Medium API'
      parameters:
      - name: enterpriseId
        in: path
        required: true
        description: Multi Org ID.
        schema:
          type: string
      - name: orgId
        in: path
        required: true
        description: Organization ID.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEnterpriseOrgRequest'
      responses:
        '200':
          description: Organization updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpdateEnterpriseOrgResponse'
        '400':
          description: Invalid request body or seat allocation exceeds Multi Org limit.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Permission denied or Organization does not belong to this Multi Org.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Multi Org or Organization not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Seat allocation is less than current usage.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
  /v3/orgs/{orgId}/hubs:
    post:
      summary: Create a User Group
      tags:
      - User Group Management
      description: 'Creates a new User Group within an Organization.


        Rate limit category: Slow API'
      parameters:
      - name: orgId
        in: path
        required: true
        description: Organization ID
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateHubRequest'
      responses:
        '201':
          description: The User Group was created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HubResponseItem'
        '400':
          description: Invalid request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The Organization's User Group quota has been exceeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The Organization not found or no access to the Organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
  /v3/orgs/{orgId}/hubs/{hubId}:
    delete:
      summary: Delete a User Group
      tags:
      - User Group Management
      description: 'Deletes a User Group from an Organization.


        The default User Group cannot be deleted.


        Members who belong only to the deleted User Group can either be:

        - Transferred to the default User Group (when `transfer=true`)

        - Removed from the Organization entirely (when `transfer=false` or omitted)


        Rate limit category: Medium API'
      parameters:
      - name: orgId
        in: path
        required: true
        description: Organization ID.
        schema:
          type: string
      - name: hubId
        in: path
        required: true
        description: User Group ID. Cannot be `default` as the default User Group cannot be deleted.
        schema:
          type: string
      - name: transfer
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/BooleanStringType'
        description: "Determine whether the users who belong only to the deleted User Group are transferred\n to the default\
          \ User Group or are removed from the Organization entirely.\n\nPossible values:\n- `true` – Represents a true boolean\
          \ value.\n- `false` – Represents a false boolean value."
      responses:
        '204':
          description: The User Group was deleted successfully.
        '400':
          description: Invalid query parameters or the User Group is managed by SCIM.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The caller does not have permission to delete the User Group or attempting to delete the default User
            Group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The Organization or User Group not found or no access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
    patch:
      summary: Update a User Group
      tags:
      - User Group Management
      description: 'Updates an existing User Group within an Organization.

        Currently supports updating the User Group name only.


        Rate limit category: Medium API'
      parameters:
      - name: orgId
        in: path
        required: true
        description: Organization ID
        schema:
          type: string
      - name: hubId
        in: path
        required: true
        description: User Group ID. Use `default` to refer to the default User Group of the Organization.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HubUpdateRequest'
      responses:
        '200':
          description: The User Group was updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HubResponseItem'
        '400':
          description: Invalid request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The caller does not have permission to update the User Group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The Organization or User Group not found or no access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
  /v3/orgs/{orgId}:
    get:
      summary: Get information about an Organization and its User Groups
      tags:
      - User Group Management
      description: 'Get information about an Organization and its User Groups.


        Rate limit category: Fast API'
      parameters:
      - name: orgId
        in: path
        required: true
        description: Organization ID.
        schema:
          type: string
      responses:
        '200':
          description: The Organization details.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgResponse'
        '404':
          description: The Organization not found or no access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
  /v3/orgs/{orgId}/users:
    post:
      summary: Add or invite Users to an Organization and its User Groups
      tags:
      - Organization User Management
      description: 'Add or invite Users, up to 20 at a time, to an Organization and its User Groups.


        If an invited user is already a member of the Organization,

        the user is added directly to the specified User Groups.


        If an invited user is not a member of the Organization,

        the user is invited to the Organization and the specified User Groups.

        The user is added to the org after accepting the invite.


        Rate limit category: Medium API'
      parameters:
      - name: orgId
        in: path
        required: true
        description: Organization ID.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddOrgUsersRequest'
      responses:
        '207':
          description: 'The request was processed. The results for individual users may be different.

            Response body includes results for each requested email.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddOrgUsersResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access denied or the resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
    get:
      summary: List Users in an Organization
      tags:
      - Organization User Management
      description: 'Returns Users in the Organization by the specified sorting order and filtering.

        Several filtering, sorting, and pagination options are available.


        Rate limit category: Fast API'
      parameters:
      - name: orgId
        in: path
        required: true
        description: Organization ID.
        schema:
          type: string
      - name: effective_role
        in: query
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/RTEffectiveRole'
        style: form
        explode: true
        description: 'Filter to limit the roles to be listed. If not specified, everyone is listed.


          Possible values:

          - `org_owner` – Organization Owner.

          - `org_admin` – Organization Administrator.

          - `space_admin` – Space Administrator.

          - `hub_admin` – User Group Administrator.

          - `hub_member` – User Group Member.'
      - name: sort
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/GetOrgMemberListSortOptionType'
        description: 'Sort option. If not specified, `name` is used.


          Possible values:

          - `name` – Sort by name in ascending order.

          - `-name` – Sort by name in descending order.

          - `email` – Sort by email in ascending order.

          - `-email` – Sort by email in descending order.

          - `date_last_activity` – Sort by date last activity in ascending order.

          - `-date_last_activity` – Sort by date last activity in descending order.

          - `date_joined` – Sort by date joined in ascending order.

          - `-date_joined` – Sort by date joined in descending order.

          - `num_started_speeches` – Sort by number of started speeches in ascending order.

          - `-num_started_speeches` – Sort by number of started speeches in descending order.'
      - name: start
        in: query
        required: false
        schema:
          type: string
        description: Start index of the list. If not specified, 0 is used.
      - name: limit
        in: query
        required: false
        schema:
          type: string
        description: "Maximum number of elements in paginated response. Maximum is 1000.\n If not specified, 20 is used as\
          \ the default value."
      - name: prefix
        in: query
        required: false
        schema:
          type: string
        description: "Filter to users who have this prefix for sorting field.\n This currently works only when `sort` is `email`\
          \ or `-email`.\n The primary usage is to search for a single user by email address."
      - name: field
        in: query
        required: false
        schema:
          type: array
          items:
            $ref: '#/components/schemas/GetOrgMemberListFieldType'
        style: form
        explode: true
        description: "Optional fields to output.\n Specify only when needed because additional fields increase response time.\n\
          \nPossible values:\n- `hubs` – Include the information of the User Groups which the user belongs to."
      responses:
        '200':
          description: The list of users in the Organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgMemberListResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The resource not found or no access to the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
  /v3/orgs/{orgId}/hubs/{hubId}/users/remove:
    post:
      summary: Remove Users and outstanding invites from a User Group
      tags:
      - Organization User Management
      description: 'Accepts up to 100 email addresses, removes the corresponding User Group memberships.


        If users would lose access to all User Groups of the Organization,

        they will be added to the fallback User Group.


        Rate limit category: Medium API'
      parameters:
      - name: orgId
        in: path
        required: true
        description: Organization ID.
        schema:
          type: string
      - name: hubId
        in: path
        required: true
        description: User Group ID.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteHubUsersInvitesByEmailRequest'
      responses:
        '207':
          description: Request processed. Individual email results are returned in the response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemoveHubUsersResponse'
        '400':
          description: Invalid request body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access denied or the resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
  /v3/orgs/{orgId}/users/remove:
    post:
      summary: Remove Users and outstanding invites from an Organization
      tags:
      - Organization User Management
      description: 'Accepts up to 100 email addresses and removes them from the Organization

        if they are members of the Organization or deletes their pending invites.


        Rate limit category: Medium API'
      parameters:
      - name: orgId
        in: path
        required: true
        description: Organization ID.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteOrgUsersInvitesByEmailRequest'
      responses:
        '207':
          description: Request processed. Individual email results are returned in the response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RemoveOrgUsersResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access denied or the resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
  /v3/orgs/{orgId}/invites:
    get:
      summary: List outstanding Invites for an Organization or a User Group
      tags:
      - Organization User Management
      description: 'Returns outstanding invites scoped to an Organization or a User Group.

        Several filtering, sorting, and pagination options are available.


        Rate limit category: Fast API'
      parameters:
      - name: orgId
        in: path
        required: true
        description: Organization ID.
        schema:
          type: string
      - name: sort
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/GetOrgInviteListSortOptionType'
        description: "Sort option.\n If not specified, invites are sorted by email in ascending order.\n\nPossible values:\n\
          - `email` – Sort by email in ascending order.\n- `-email` – Sort by email in descending order.\n- `date_invited`\
          \ – Sort by date invited in ascending order.\n- `-date_invited` – Sort by date invited in descending order."
      - name: start
        in: query
        required: false
        schema:
          type: string
        description: Start index of the list. If not specified, 0 is used.
      - name: limit
        in: query
        required: false
        schema:
          type: string
        description: "Maximum number of elements in paginated response.\n Maximum is 1000.\n If not specified, 20 is used\
          \ as the default value."
      - name: hub_id
        in: query
        required: false
        schema:
          type: string
        description: User Group ID. If specified, limit the response to invites for a specific User Group.
      - name: prefix
        in: query
        required: false
        schema:
          type: string
        description: "Filter invites matching a prefix for the selected sort field.\n Works only with `email` or `-email`\
          \ sort options."
      responses:
        '200':
          description: The list of outstanding invites for the Organization or User Group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrgInviteListResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The resource not found or no access to the resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
  /v3/orgs/{orgId}/members/expiration:
    patch:
      summary: Set, update, or clear expiration dates on organization memberships
      tags:
      - Organization User Management
      description: 'Accepts up to 100 email addresses per request. For each member, sets

        or updates the membership expiration to the supplied UTC timestamp,

        or clears it when `expiration_date` is `null`. Returns a per-email

        result for each address.


        Rate limit category: Medium API'
      parameters:
      - name: orgId
        in: path
        required: true
        description: Organization ID.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateMemberExpirationRequest'
      responses:
        '207':
          description: Request processed. Individual results are returned in the response body.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SetMemberExpirationResponse'
        '400':
          description: Invalid request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access denied or the resource not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
      - BearerAuth: []
  /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: []
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
  schemas:
    GetEnterpriseResponse:
      type: object
      properties:
        id:
          examples:
          - aBcD2345eFgH6789iJkm
          type: string
          description: ID of the Multi Org.
        name:
          examples:
          - Acme Enterprise
          type: string
          description: Name of the Multi Org.
        seat_pool_total:
          examples:
          - 500
          type: number
          description: Total number of seats in the Multi Org seat pool.
        seat_pool_allocated:
          examples:
          - 400
          type: number
          description: Number of seats currently allocated from the Multi Org seat pool across all member Organizations.
        seat_pool_used:
          examples:
          - 350
          type: number
          description: Number of seats currently in use across all member Organizations.
        admins:
          type: array
          items:
            type: object
            properties:
              user_id:
                examples:
                - aBcD2345eFgH6789iJkm
                type: string
                description: User ID.
              name:
                examples:
                - Jordan Lee
                type: string
                description: Display name of the user.
              email:
                examples:
                - admin@example.com
                type: string
                description: Email of the user.
            required:
            - user_id
            - name
            - email
          description: List of administrator users for the Multi Org.
        member_orgs:
          type: array
          items:
            type: object
            properties:
              org_id:
                examples:
                - aBcD2345eFgH6789iJkm
                type: string
                description: Organization ID.
              org_name:
                examples:
                - Acme Corp
                type: string
                description: Name of the Organization.
              seats_allocated:
                examples:
                - 50
                type: number
                description: Number of seats allocated to this Organization from the Multi Org seat pool.
              seats_used:
                examples:
                - 35
                type: number
                description: Number of seats currently in use by this Organization.
              member_count:
                examples:
                - 40
                type: number
                description: Total number of members in the Organization.
              pending_invite_count:
                examples:
                - 5
                type: number
                description: Number of pending invites to the Organization.
              created_date:
                examples:
                - '2024-01-15T10:30:00.000Z'
                type: string
                description: Date when the Organization was created in `YYYY-MM-DDTHH:mm:ss.sssZ` format.
            required:
            - org_id
            - org_name
            - seats_allocated
            - seats_used
            - member_count
            - pending_invite_count
            - created_date
          description: List of member Organizations and their seat usage details.
        home_org_id:
          examples:
          - aBcD2345eFgH6789iJkm
          - null
          oneOf:
          - type: string
          - type: 'null'
          description: ID of the home org for global content broadcast. Null if not configured.
      required:
      - id
      - name
      - seat_pool_total
      - seat_pool_allocated
      - seat_pool_used
      - admins
      - member_orgs
      - home_org_id
    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
    UpdateEnterpriseOrgRequest:
      type: object
      properties:
        seats_allocated:
          examples:
          - 50
          type: number
          description: "New number of seats to allocate to the Organization from the Multi Org seat pool.\n Must be a non-negative\
            \ integer and cannot be less than the current seat usage."
    UpdateEnterpriseOrgResponse:
      type: object
      properties:
        success:
          examples:
          - true
          type: boolean
          description: Whether the operation completed successfully.
      required:
      - success
    CreateHubRequest:
      type: object
      properties:
        name:
          examples:
          - Sales Team
          - Engineering
          type: string
          description: Name of the User Group to create.
      required:
      - name
    HubResponseItem:
      type: object
      properties:
        id:
          examples:
          - dE3f4gH5
          type: string
          description: ID of the User Group.
        name:
          examples:
          - Sales Team
          type: string
          description: Name of the User Group.
        org_default:
          examples:
          - false
          type: boolean
          description: Whether this User Group is the default User Group of the Organization.
        creation_date:
          examples:
          - '2024-01-15T10:30:00.000Z'
          type: string
          description: The date and time when the User Group was created in `YYYY-MM-DDTHH:mm:ss.sssZ` format.
      required:
      - id
      - name
      - org_default
      - creation_date
    BooleanStringType:
      type: string
      enum:
      - 'true'
      - 'false'
      description: 'Possible values:

        - `true` – Represents a true boolean value.

        - `false` – Represents a false boolean value.'
    HubUpdateRequest:
      type: object
      properties:
        name:
          examples:
          - Sales Team
          - Engineering
          type: string
          description: New name of the User Group.
      required:
      - name
    OrgResponse:
      type: object
      properties:
        id:
          examples:
          - aBcD2345eFgH6789iJkm
          type: string
          description: Organization ID.
        name:
          examples:
          - Acme Corporation
          type: string
          description: Organization name.
        default_hub_id:
          examples:
          - dE3f4gH5
          type: string
          description: ID of the default User Group for this Organization.
        hubs:
          type: array
          items:
            type: object
            properties:
              id:
                examples:
                - dE3f4gH5
                type: string
                description: ID of the User Group.
              name:
                examples:
                - Sales Team
                type: string
                description: Name of the User Group.
              org_default:
                examples:
                - false
                type: boolean
                description: Whether this User Group is the default User Group of the Organization.
              creation_date:
                examples:
                - '2024-01-15T10:30:00.000Z'
                type: string
                description: The date and time when the User Group was created in `YYYY-MM-DDTHH:mm:ss.sssZ` format.
    

# --- truncated at 32 KB (62 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/yoodli/refs/heads/main/openapi/yoodli-api-openapi.yml