openapi: 3.0.3
info:
  title: Hex Cells Groups API
  version: 1.0.0
  description: API specification for the Hex External API
  license:
    name: UNLICENSED
  contact: {}
servers:
- url: https://app.hex.tech/api
security:
- bearerAuth: []
tags:
- name: Groups
paths:
  /v1/groups/{groupId}:
    get:
      operationId: GetGroup
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupApiResource'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
      parameters:
      - in: path
        name: groupId
        required: true
        schema:
          $ref: '#/components/schemas/GroupId'
      tags:
      - Groups
    delete:
      operationId: DeleteGroup
      responses:
        '204':
          description: ''
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
      parameters:
      - in: path
        name: groupId
        required: true
        schema:
          $ref: '#/components/schemas/GroupId'
      tags:
      - Groups
    patch:
      operationId: EditGroup
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupApiResource'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
      parameters:
      - in: path
        name: groupId
        required: true
        schema:
          $ref: '#/components/schemas/GroupId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                members:
                  properties:
                    remove:
                      $ref: '#/components/schemas/GroupMembers'
                    add:
                      $ref: '#/components/schemas/GroupMembers'
                  type: object
                name:
                  $ref: '#/components/schemas/Name'
              type: object
      tags:
      - Groups
  /v1/groups:
    get:
      operationId: ListGroups
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListGroupsResponse'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
      parameters:
      - in: query
        name: after
        required: false
        schema:
          default: null
      - in: query
        name: before
        required: false
        schema:
          default: null
      - in: query
        name: limit
        required: false
        schema:
          $ref: '#/components/schemas/LargerPageSize'
      - in: query
        name: sortBy
        required: false
        schema:
          $ref: '#/components/schemas/ListGroupsSortByEnum'
      - in: query
        name: sortDirection
        required: false
        schema:
          $ref: '#/components/schemas/SortDirectionEnum'
      tags:
      - Groups
    post:
      operationId: CreateGroup
      responses:
        '201':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateGroupResponse'
        '400':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '403':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
        '500':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TsoaErrorResponsePayload'
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                members:
                  $ref: '#/components/schemas/GroupMembers'
                name:
                  $ref: '#/components/schemas/Name'
              required:
              - name
              type: object
      tags:
      - Groups
components:
  schemas:
    PaginationApiResource:
      properties:
        after:
          allOf:
          - $ref: '#/components/schemas/ApiPaginationCursor'
          nullable: true
        before:
          allOf:
          - $ref: '#/components/schemas/ApiPaginationCursor'
          nullable: true
      required:
      - after
      - before
      type: object
      additionalProperties: false
    ApiPaginationCursor:
      type: string
      description: 'A cursor string used with `before` and `after` parameters to paginate through a list

        of items on the API.'
    ListGroupsResponse:
      properties:
        values:
          items:
            $ref: '#/components/schemas/GroupApiResource'
          type: array
        pagination:
          $ref: '#/components/schemas/PaginationApiResource'
      required:
      - values
      - pagination
      type: object
      additionalProperties: false
    TsoaErrorResponsePayload:
      properties:
        details:
          type: string
        traceId:
          $ref: '#/components/schemas/TraceId'
        reason:
          type: string
      required:
      - reason
      type: object
    GroupMembers:
      properties:
        users:
          items:
            properties:
              id:
                $ref: '#/components/schemas/UserId'
            required:
            - id
            type: object
          type: array
          maxItems: 100
      type: object
      additionalProperties: false
    SortDirectionEnum:
      $ref: '#/components/schemas/EnumValues_typeofSortDirectionEnum_'
    ListGroupsSortByEnum:
      $ref: '#/components/schemas/EnumValues_typeofListGroupsSortByEnum_'
    GroupId:
      type: string
      format: uuid
      description: Unique ID for a group. This can be found from the groups page (in Settings).
      pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
    GroupApiResource:
      properties:
        id:
          $ref: '#/components/schemas/GroupId'
        name:
          type: string
        createdAt:
          $ref: '#/components/schemas/Timestamp'
      required:
      - id
      - name
      - createdAt
      type: object
      additionalProperties: false
    EnumValues_typeofSortDirectionEnum_:
      type: string
      enum:
      - DESC
      - ASC
    Name:
      type: string
      minLength: 1
    CreateGroupResponse:
      properties:
        id:
          $ref: '#/components/schemas/GroupId'
        name:
          $ref: '#/components/schemas/Name'
        members:
          $ref: '#/components/schemas/GroupMembers'
      required:
      - id
      - name
      - members
      type: object
      additionalProperties: false
    LargerPageSize:
      type: integer
      format: int32
      default: '25'
      description: Number of results to fetch per page for paginated requests
      minimum: 1
      maximum: 500
    Timestamp:
      type: string
      format: timestamp
      description: An ISO 8601 timestamp with timezone like 1970-01-01T00:00:00Z.
    TraceId:
      type: string
      description: A unique identifier for this API request. The Hex Support team may request this value when debugging an issue.
    UserId:
      type: string
      format: uuid
      description: Unique ID for a user. This can be found from the users page (in Settings).
      pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
    EnumValues_typeofListGroupsSortByEnum_:
      type: string
      enum:
      - CREATED_AT
      - NAME
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer