openapi: 3.0.0
info:
  title: TalentLMS Public Batch Actions Group API
  description: "TalentLMS offers a range of API endpoints and resources designed to integrate TalentLMS with your internal systems seamlessly. It is organized around Representational State Transfer (REST) and is built to leverage standard HTTP features such as HTTP authentication and HTTP response codes, ensuring seamless integration. All API responses, including error messages, are consistently formatted in JSON for easy parsing and handling.\n\nIf your TalentLMS domain is called “samples”, then the API endpoint for your domain is [<code>https://samples.talentlms.com/api/v2</code>](https://samples.talentlms.com/api).\n\nThe current version of the API consumes data – information about users, courses, categories, groups, branches, and general details about your domain. Apart from that, via the API you can log in / sign up a user in your domain, enroll a user in a course, and much more. Please make sure, that you are accessing the URLs below, under HTTPs connections, otherwise, you will receive an error.\n\n## \U0001F680 **Getting Started Guide**\n\nTo start using the TalentLMS API, you must first [enable the API and generate a valid API](https://help.talentlms.com/hc/en-us/articles/9651527213468-Can-I-integrate-my-site-with-TalentLMS-Do-you-offer-an-API) key from the portal's settings (Account & Settings > Integrations > API).\n\n**Keep in mind:**\n\n- The pagination limit of each request is 100.\n    \n- The API has rate and usage limits (e.g. 2000 requests per hour).\n    \n- The API returns request responses in JSON format. When an API request returns an error, it is sent in the JSON response as an error key (All calls must have an Accept: application/json header value).\n    \n- In each request you must add the desired version of the API by adding the header option with the key `X-API-Version` and value (the format of the version must be `YYYY-MM-DD`).\n    \n## \U0001F510 Authentication\n\nAll of the requests require authentication. Our API uses the `API Key` authorization method, with key `X-API-Key` and value `your_api_key`. You can always fill these fields in the global variables or create an environment and insert them there.\n\n### ⛔️ Authentication error response\n\nYou will receive an HTTP 401 Unauthorized response code if the API key is missing, incorrectly formatted, or invalid.\n\n### ✅ API Responses\n\nTalentLMS API uses HTTP response codes to indicate the success or failure of requests. Specifically, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided arguments (e.g. instead of an integer a string is supplied), and the 500 error code indicates an internal TalentLMS error. Please be aware that you will receive an error too, in case you try to access an endpoint via non HTTPs connection.\n\nAll errors return JSON consisting of a type (invalid_request_error or api_error) and a message describing the error.\n\n| **Code** | **Description** |\n| --- | --- |\n| 200 | The request was executed properly and a JSON response is returned. |\n| 204 | No content, and the operation was executed successfully. |\n| 400 | A required parameter is missing or an invalid type (e.g. a string) was supplied instead of an integer. |\n| 401 | Invalid API key provided. |\n| 403 | API is not enabled for the specified domain or the domain is currently inactive. |\n| 404 | The requested resource (e.g. user) does not exist. |\n| 422 | Malformed response. |\n| 429 | The API request rate limit has been exceeded. |\n| 500 | Internal server error. |\n\n### \U0001F6D1 Rate Limits\n\nRate limits represent the maximum number of API requests that are permitted to be made  \nper hour. These limits depend on your subscription plan and are as follows:\n\n| **Plan** | **Limit** |\n| --- | --- |\n| Core | 2.000 |\n| Grow | 10.000 |\n| Pro | 10.000 |\n| Small | 2.000 |\n| Basic | 2.000 |\n| Plus | 10.000 |\n| Premium | 10.000 |\n| Custom | Contact us so we can create a plan that fits your needs |\n\nRegardless of the total API requests per hour provisioned per customer, each customer's API requests should not exceed the rate of 200 API calls per 5 seconds. The following headers are included in API responses to help manage rate limits:\n\n- **`X-RateLimit-Limit`**: The maximum number of requests allowed in the current time window\n    \n- **`X-RateLimit-Remaining`**: The number of requests left in the current window before hitting the limit\n    \n### \U0001F4C4 Pagination\n\nOur API supports pagination, splitting responses into size-customizable chunks of up to 100 items per request. You can navigate to the first, last, previous, or next page. The endpoints that support pagination return a list formatted as shown below:\n\n``` json\n{\n        \"self\": \"https://example.talentlms.com/api/v2/users?page[number]=1&page[size]=10\",\n        \"first\": \"https://example.talentlms.com/api/v2/users?page[number]=1&page[size]=10\",\n        \"last\": \"https://example.talentlms.com/api/v2/users?page[number]=4&page[size]=10\",\n        \"prev\": \"https://example.talentlms.com/api/v2/users?page[number]=1&page[size]=10\",\n        \"next\": \"https://example.talentlms.com/api/v2/users?page[number]=2&page[size]=10\"\n}\n\n ```"
  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: {}
    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: {}
  /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: {}
    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: {}
  /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: {}
    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: {}
  /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: {}
    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: {}
  /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:
    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
    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
          example: ADV-101
          nullable: true
      type: object
  securitySchemes:
    apikeyAuth:
      type: apiKey
      in: header
      name: X-API-Key