openapi: 3.0.3
info:
  title: Accredible Analytics Groups API
  description: The Accredible API issues, manages, and verifies digital credentials - certificates and Open Badges - programmatically. Credentials are issued to a recipient against a Group (a course or achievement) and rendered with a reusable Design. The API also manages Evidence Items and References attached to credentials, generates credential PDFs and blockchain-verifiable records, returns engagement analytics, administers Departments and Team Members, and generates recipient SSO links. All requests are authenticated with an API key sent in the Authorization header using the scheme `Token token=YOUR_API_KEY`. Production base URL is https://api.accredible.com/v1; a sandbox is available at https://sandbox.api.accredible.com/v1. Endpoints and paths are grounded in Accredible's published API reference; request and response schemas are modeled and simplified.
  version: '1.0'
  contact:
    name: Accredible
    url: https://www.accredible.com
  license:
    name: Proprietary
    url: https://www.accredible.com/terms-of-service
servers:
- url: https://api.accredible.com/v1
  description: Production
- url: https://sandbox.api.accredible.com/v1
  description: Sandbox
security:
- tokenAuth: []
tags:
- name: Groups
  description: Course or achievement containers that credentials are issued against.
paths:
  /issuer/groups:
    post:
      operationId: createGroup
      tags:
      - Groups
      summary: Create a group
      description: Creates a new Group (course or achievement) under the issuer account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                group:
                  $ref: '#/components/schemas/GroupInput'
      responses:
        '200':
          description: The created group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /issuer/groups/{group_id}:
    parameters:
    - $ref: '#/components/parameters/GroupId'
    get:
      operationId: getGroup
      tags:
      - Groups
      summary: View a group
      description: Retrieves a single Group by ID.
      responses:
        '200':
          description: The requested group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupEnvelope'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateGroup
      tags:
      - Groups
      summary: Update a group
      description: Updates an existing Group.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                group:
                  $ref: '#/components/schemas/GroupInput'
      responses:
        '200':
          description: The updated group.
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteGroup
      tags:
      - Groups
      summary: Delete a group
      description: Deletes a Group by ID.
      responses:
        '200':
          description: The group was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /issuer/all_groups:
    get:
      operationId: listAllGroups
      deprecated: true
      tags:
      - Groups
      summary: View all groups (deprecated)
      description: Lists all Groups under the issuer account. Deprecated in favor of search.
      parameters:
      - name: name
        in: query
        schema:
          type: string
      - name: page
        in: query
        schema:
          type: integer
      - name: page_size
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: A list of groups.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /issuer/groups/search:
    post:
      operationId: searchGroups
      tags:
      - Groups
      summary: Search for groups
      description: Searches Groups by name and other attributes with pagination.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                page:
                  type: integer
                page_size:
                  type: integer
      responses:
        '200':
          description: Matching groups.
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    GroupEnvelope:
      type: object
      properties:
        group:
          $ref: '#/components/schemas/Group'
    Group:
      allOf:
      - $ref: '#/components/schemas/GroupInput'
      - type: object
        properties:
          id:
            type: integer
            description: The unique group ID.
    Error:
      type: object
      properties:
        error:
          type: string
          description: A human-readable error message.
        errors:
          type: array
          items:
            type: string
    GroupInput:
      type: object
      properties:
        name:
          type: string
          description: The internal name of the group.
        course_name:
          type: string
          description: The course/achievement name shown to recipients.
        course_description:
          type: string
          description: The course/achievement description.
        design_id:
          type: integer
          description: The Design used to render credentials in this group.
        language:
          type: string
          description: The language code for the group.
  responses:
    Unauthorized:
      description: Invalid or missing API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    GroupId:
      name: group_id
      in: path
      required: true
      description: The unique ID of the group.
      schema:
        type: integer
  securitySchemes:
    tokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: API key sent in the Authorization header using the scheme `Token token=YOUR_API_KEY`.