openapi: 3.2.0
info:
  contact:
    email: hello@entergram.com
    name: Entergram
  description: Secure, workspace-scoped API for Entergram PRO. Use API keys created in Settings > Developers to access workspace metadata, accounts, contacts, groups, chats, custom fields, and tickets through a stable, documented contract.
  title: Entergram Public Members API
  version: v1
security:
- ApiKeyAuth: []
tags:
- description: Safe workspace member identity, role, permissions, and seat assignment metadata.
  name: Members
paths:
  /v1/members:
    get:
      description: Returns safe member identity, role, permissions and seat allocation fields. Use items[].userId for ticket assignment filters and writes.
      operationId: list-workspace-members
      parameters:
      - description: Number of members to return per page.
        explode: false
        in: query
        name: limit
        schema:
          default: 50
          description: Number of members to return per page.
          examples:
          - 50
          format: int64
          maximum: 200
          minimum: 1
          type: integer
      - description: Zero-based pagination offset.
        explode: false
        in: query
        name: offset
        schema:
          default: 0
          description: Zero-based pagination offset.
          examples:
          - 0
          format: int64
          minimum: 0
          type: integer
      - description: Optional exact workspace role filter.
        explode: false
        in: query
        name: role
        schema:
          description: Optional exact workspace role filter.
          enum:
          - OWNER
          - ADMIN
          - MEMBER
          examples:
          - MEMBER
          type: string
      - description: Case-insensitive search over alias, profile name and email.
        explode: false
        in: query
        name: search
        schema:
          description: Case-insensitive search over alias, profile name and email.
          examples:
          - alex
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MembersEnvelope'
          description: OK
        '401':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unauthorized
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Forbidden
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unprocessable Entity
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal Server Error
      summary: List workspace members
      tags:
      - Members
      x-required-scopes:
      - members.read
  /v1/members/{user_id}:
    get:
      description: Returns one workspace member by user id without exposing private location, billing or authentication data.
      operationId: get-workspace-member
      parameters:
      - description: Workspace member user id. This is the identifier accepted by ticket assigned_to_id fields.
        in: path
        name: user_id
        required: true
        schema:
          description: Workspace member user id. This is the identifier accepted by ticket assigned_to_id fields.
          examples:
          - 00000000-0000-0000-0000-000000000001
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MemberEnvelope'
          description: OK
        '401':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unauthorized
        '403':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Forbidden
        '404':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Not Found
        '422':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Unprocessable Entity
        '500':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Internal Server Error
      summary: Get one workspace member
      tags:
      - Members
      x-required-scopes:
      - members.read
components:
  schemas:
    ErrorDetail:
      additionalProperties: false
      properties:
        location:
          description: Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id'
          type: string
        message:
          description: Error message text
          type: string
        value:
          description: The value at the given location
      type: object
    MemberEnvelope:
      additionalProperties: false
      properties:
        data:
          $ref: '#/components/schemas/WorkspaceMemberSummary'
      required:
      - data
      type: object
    MembersList:
      additionalProperties: false
      properties:
        items:
          items:
            $ref: '#/components/schemas/WorkspaceMemberSummary'
          type:
          - array
          - 'null'
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
      - items
      - pagination
      type: object
    MembersEnvelope:
      additionalProperties: false
      properties:
        data:
          $ref: '#/components/schemas/MembersList'
      required:
      - data
      type: object
    WorkspaceMemberSummary:
      additionalProperties: false
      properties:
        canManageCustomColumns:
          description: Whether the member may manage custom columns.
          examples:
          - true
          type: boolean
        canViewGroupManagementInfo:
          description: Whether the member may view group-management details.
          examples:
          - true
          type: boolean
        canViewGroupMembersInfo:
          description: Whether the member may view group-member details.
          examples:
          - true
          type: boolean
        displayAlias:
          description: Workspace-local display alias.
          examples:
          - Support Lead
          type:
          - string
          - 'null'
        id:
          description: Workspace membership identifier.
          examples:
          - member_demo_123
          type: string
        joinedAt:
          description: Membership creation timestamp.
          format: date-time
          type: string
        role:
          description: Workspace role.
          examples:
          - MEMBER
          type: string
        seat:
          $ref: '#/components/schemas/WorkspaceMemberSeatSummary'
          description: Assigned workspace seat when one exists.
        user:
          $ref: '#/components/schemas/WorkspaceMemberUserSummary'
          description: Safe user profile fields for the workspace member.
        userId:
          description: User identifier used by ticket assignment fields.
          examples:
          - 00000000-0000-0000-0000-000000000001
          type: string
      required:
      - id
      - userId
      - role
      - displayAlias
      - canManageCustomColumns
      - canViewGroupMembersInfo
      - canViewGroupManagementInfo
      - joinedAt
      - user
      - seat
      type: object
    WorkspaceMemberSeatSummary:
      additionalProperties: false
      properties:
        analyticsEnabled:
          description: Whether analytics is enabled for this seat.
          examples:
          - true
          type: boolean
        extraTgCount:
          description: Additional Telegram account allowance on this seat.
          examples:
          - 1
          format: int64
          type: integer
        id:
          description: Workspace seat identifier.
          examples:
          - seat_demo_123
          type: string
        seatNumber:
          description: Human-facing seat number.
          examples:
          - 2
          format: int64
          type: integer
        status:
          description: Current seat billing/allocation status.
          examples:
          - ACTIVE
          type: string
      required:
      - id
      - seatNumber
      - status
      - analyticsEnabled
      - extraTgCount
      type: object
    Pagination:
      additionalProperties: false
      properties:
        hasMore:
          type: boolean
        limit:
          format: int64
          type: integer
        nextOffset:
          format: int64
          type:
          - integer
          - 'null'
        offset:
          format: int64
          type: integer
        total:
          format: int64
          type: integer
      required:
      - limit
      - offset
      - total
      - hasMore
      - nextOffset
      type: object
    ErrorModel:
      additionalProperties: false
      properties:
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          examples:
          - Property foo is required but is missing.
          type: string
        errors:
          description: Optional list of individual error details
          items:
            $ref: '#/components/schemas/ErrorDetail'
          type:
          - array
          - 'null'
        instance:
          description: A URI reference that identifies the specific occurrence of the problem.
          examples:
          - https://example.com/error-log/abc123
          format: uri
          type: string
        status:
          description: HTTP status code
          examples:
          - 400
          format: int64
          type: integer
        title:
          description: A short, human-readable summary of the problem type. This value should not change between occurrences of the error.
          examples:
          - Bad Request
          type: string
        type:
          default: about:blank
          description: A URI reference to human-readable documentation for the error.
          examples:
          - https://example.com/errors/example
          format: uri
          type: string
      type: object
    WorkspaceMemberUserSummary:
      additionalProperties: false
      properties:
        avatarUrl:
          description: Profile avatar URL when available.
          examples:
          - https://cdn.example.test/avatar.png
          type:
          - string
          - 'null'
        displayName:
          description: Profile display name when available.
          examples:
          - Alex Example
          type:
          - string
          - 'null'
        email:
          description: Member email when available.
          examples:
          - alex@example.test
          type:
          - string
          - 'null'
        firstName:
          description: Profile first name when available.
          examples:
          - Alex
          type:
          - string
          - 'null'
        id:
          description: User identifier used by ticket assignment fields.
          examples:
          - 00000000-0000-0000-0000-000000000001
          type: string
        lastName:
          description: Profile last name when available.
          examples:
          - Example
          type:
          - string
          - 'null'
      required:
      - id
      - email
      - displayName
      - firstName
      - lastName
      - avatarUrl
      type: object
  securitySchemes:
    ApiKeyAuth:
      description: Workspace-scoped PRO API key created in Entergram Settings > Developers.
      in: header
      name: X-API-Key
      type: apiKey
x-entergram-scopes:
- workspace.read
- members.read
- accounts.read
- contacts.read
- chats.read
- chats.write
- messages.read
- messages.write
- custom_fields.read
- custom_fields.write
- tickets.read
- tickets.write
- events.read
- webhooks.read
- webhooks.write