TalentLMS Group API

openapi: 3.2.0
info:
  title: TalentLMS Public Group API
  description: TalentLMS offers a range of API endpoints and resources designed to integrate TalentLMS with your internal systems seamlessly.
  version: 1.0.0
servers:
- url: https://your-domain.talentlms.com
security:
- apikeyAuth: []
tags:
- name: Group
paths:
  /api/v2/groups:
    get:
      tags:
      - Group
      summary: List all groups
      description: '### List all groups


        Retrieves a paginated list of all groups in your TalentLMS account. Upon a successful request, the API returns a JSON response containing group objects, including their associated metadata and configuration details. Results are delivered in a paginated format to ensure efficient handling of large datasets.'
      parameters:
      - name: X-API-Version
        in: header
        schema:
          type: string
        example: '{{apiVersion}}'
      responses:
        200:
          description: Successful response
          content:
            application/json: {}
      operationId: getApiV2Groups
      x-operation-id-source: derived
    post:
      tags:
      - Group
      summary: Create a group
      description: '### Create a group


        Creates a new group in your TalentLMS account. To successfully create a group, provide the required group attributes in the request body. If the request is valid, the API creates the group and returns the newly created group object, including its unique ID.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                name: <string>
                description: <string>
                key: <string>
                max_key_redemptions: <integer>
                price: <float>
      parameters:
      - name: X-API-Version
        in: header
        schema:
          type: string
        example: '{{apiVersion}}'
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      responses:
        200:
          description: Successful response
          content:
            application/json: {}
      operationId: postApiV2Groups
      x-operation-id-source: derived
  /api/v2/groups/:id:
    get:
      tags:
      - Group
      summary: Get a group
      description: '### Get a group


        Retrieves the full details of a specific group. To successfully fetch a group, include the group’s unique ID as a path parameter in the request URL. If the request is valid and the group exists, the API returns detailed information about the group, including its metadata, assigned users, and related configuration settings (where applicable).'
      parameters:
      - name: X-API-Version
        in: header
        schema:
          type: string
        example: '{{apiVersion}}'
      responses:
        200:
          description: Successful response
          content:
            application/json: {}
      operationId: getApiV2Groups:id
      x-operation-id-source: derived
    delete:
      tags:
      - Group
      summary: Delete a group
      description: '### Delete a group


        Permanently deletes a specific group from your TalentLMS account. To successfully remove a group, include the group’s unique ID as a path parameter in the request URL. If the request is valid and the group exists, the API deletes the group and returns a **204 No Content** response upon success.'
      parameters:
      - name: X-API-Version
        in: header
        schema:
          type: string
        example: '{{apiVersion}}'
      responses:
        200:
          description: Successful response
          content:
            application/json: {}
      operationId: deleteApiV2Groups:id
      x-operation-id-source: derived
  /api/v2/group-memberships:
    post:
      tags:
      - Group
      summary: Add a user to a group
      description: '### Add a user to a group


        Adds a user to a specific group. To create a group membership, provide the user’s unique ID using the user_id attribute and the group’s unique ID using the group_id attribute in the request body. If the request is valid and both the user and group exist, the API creates the membership and returns the corresponding group membership details.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                group_id: <integer>
                user_id: <integer>
      parameters:
      - name: X-API-Version
        in: header
        schema:
          type: string
        example: '{{apiVersion}}'
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      responses:
        200:
          description: Successful response
          content:
            application/json: {}
      operationId: postApiV2GroupMemberships
      x-operation-id-source: derived
    delete:
      tags:
      - Group
      summary: Remove user from a group
      description: '### Remove user from a group


        Removes a user from a specific group. To delete a group membership, provide the user’s unique ID using the user_id attribute and the group’s unique ID using the group_id attribute. If the request is valid and the membership exists, the API removes the user from the specified group and returns a **204 No Content** response upon success.'
      parameters:
      - name: X-API-Version
        in: header
        schema:
          type: string
        example: '{{apiVersion}}'
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      responses:
        200:
          description: Successful response
          content:
            application/json: {}
      operationId: deleteApiV2GroupMemberships
      x-operation-id-source: derived
  /api/v2/group-courses:
    post:
      tags:
      - Group
      summary: Add a course to a group
      description: '### Add a course to a group


        Associates a course with a specific group. To assign a course to a group, provide the course’s unique ID using the course_id attribute and the group’s unique ID using the group_id attribute in the request body. If the request is valid and both the course and group exist, the API creates the association and returns the corresponding group-course relationship details.'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              example:
                group_id: <integer>
                course_id: <integer>
      parameters:
      - name: X-API-Version
        in: header
        schema:
          type: string
        example: '{{apiVersion}}'
      - name: Content-Type
        in: header
        schema:
          type: string
        example: application/json
      responses:
        200:
          description: Successful response
          content:
            application/json: {}
      operationId: postApiV2GroupCourses
      x-operation-id-source: derived
    delete:
      tags:
      - Group
      summary: Remove course from group
      description: '### Remove course from group


        Removes a course from a specific group. To successfully remove a course from a group, provide the group''s unique ID using the `group_id` attribute and the course''s unique ID using the `course_id` attribute in the request body. If the request is valid and the association exists, the API deletes the group-course relationship and returns a 204 No Content response upon success.'
      responses:
        200:
          description: Successful response
          content:
            application/json: {}
      operationId: deleteApiV2GroupCourses
      x-operation-id-source: derived
  /api/v2/groups/{id}/courses:
    get:
      tags:
      - Group
      summary: Get group courses
      description: Returns a paginated list of courses assigned to a group.
      operationId: getGroupCourses
      parameters:
      - name: id
        in: path
        description: The ID of the group
        required: true
        schema:
          type: integer
      - name: X-API-Version
        in: header
        required: false
        schema:
          type: string
        example: '{{apiVersion}}'
      responses:
        404:
          description: Group not found
        200:
          description: Successful response
          content:
            application/json:
              schema:
                properties:
                  _data:
                    type: array
                    items:
                      $ref: '#/components/schemas/GroupCourseItem'
                  _links:
                    $ref: '#/components/schemas/PaginationLinks'
                  _meta:
                    $ref: '#/components/schemas/PaginationMeta'
                type: object
components:
  schemas:
    PaginationLinks:
      properties:
        self:
          type: string
        first:
          type: string
        last:
          type: string
        prev:
          type: string
        next:
          type: string
      type: object
    GroupCourseItem:
      properties:
        id:
          type: integer
          example: 1
        name:
          type: string
          example: Introduction to LMS
        code:
          type:
          - string
          - 'null'
          example: ADV-101
      type: object
    PaginationMeta:
      properties:
        pagination:
          properties:
            page:
              type: integer
              example: 1
            page_size:
              type: integer
              example: 25
            total_items:
              type: integer
            total_pages:
              type: integer
            total_results:
              type: integer
          type: object
      type: object
  securitySchemes:
    apikeyAuth:
      type: apiKey
      in: header
      name: X-API-Key