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 Tickets API
  version: v1
security:
- ApiKeyAuth: []
tags:
- description: Workspace ticket inventory, ticket detail, comments, and linked chat filters.
  name: Tickets
paths:
  /v1/tickets:
    get:
      description: Returns workspace tickets with first-class filters for status, assignment, creator, search, and linked Telegram chat id.
      operationId: list-tickets
      parameters:
      - description: Number of tickets to return per page.
        explode: false
        in: query
        name: limit
        schema:
          default: 50
          description: Number of tickets to return per page.
          examples:
          - 50
          format: int64
          maximum: 200
          minimum: 1
          type: integer
      - description: Zero-based offset for pagination.
        explode: false
        in: query
        name: offset
        schema:
          default: 0
          description: Zero-based offset for pagination.
          examples:
          - 0
          format: int64
          minimum: 0
          type: integer
      - description: Optional exact status filter.
        explode: false
        in: query
        name: status
        schema:
          description: Optional exact status filter.
          examples:
          - OPEN
          type: string
      - description: Optional exact priority filter.
        explode: false
        in: query
        name: priority
        schema:
          description: Optional exact priority filter.
          examples:
          - HIGH
          type: string
      - description: Filter by assigned workspace member id.
        explode: false
        in: query
        name: assigned_to_id
        schema:
          description: Filter by assigned workspace member id.
          examples:
          - user_demo_123
          type: string
      - description: Filter by ticket creator user id.
        explode: false
        in: query
        name: created_by_id
        schema:
          description: Filter by ticket creator user id.
          examples:
          - user_demo_123
          type: string
      - description: Return only tickets linked to the given Telegram chat id.
        explode: false
        in: query
        name: linked_chat_id
        schema:
          description: Return only tickets linked to the given Telegram chat id.
          examples:
          - '-1000001234567'
          type: string
      - description: Case-insensitive text search across title, description, and comment.
        explode: false
        in: query
        name: search
        schema:
          description: Case-insensitive text search across title, description, and comment.
          examples:
          - onboarding
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketsEnvelope'
          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 tickets for the current workspace
      tags:
      - Tickets
      x-required-scopes:
      - tickets.read
    post:
      description: Creates a workspace-scoped ticket. The authenticated API key creator becomes the ticket actor and initial creator.
      operationId: create-ticket
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTicketBody'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketEnvelope'
          description: Created
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Bad Request
        '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: Create a ticket
      tags:
      - Tickets
      x-required-scopes:
      - tickets.write
  /v1/tickets/{ticket_id}:
    delete:
      description: Removes the ticket and its dependent relations from the workspace.
      operationId: delete-ticket
      parameters:
      - description: Ticket identifier.
        in: path
        name: ticket_id
        required: true
        schema:
          description: Ticket identifier.
          examples:
          - ticket_demo_123
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketDeletedEnvelope'
          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: Delete a ticket
      tags:
      - Tickets
      x-required-scopes:
      - tickets.write
    get:
      description: Returns ticket metadata, linked chat ids, workspace custom fields, counts, and actor summaries.
      operationId: get-ticket
      parameters:
      - description: Ticket identifier.
        in: path
        name: ticket_id
        required: true
        schema:
          description: Ticket identifier.
          examples:
          - ticket_demo_123
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketEnvelope'
          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 a single ticket
      tags:
      - Tickets
      x-required-scopes:
      - tickets.read
    patch:
      description: Applies a partial update to an existing ticket. `linkedChatIds` replaces the full linked-chat set, and `customFields` behaves as a partial patch.
      operationId: update-ticket
      parameters:
      - description: Ticket identifier.
        in: path
        name: ticket_id
        required: true
        schema:
          description: Ticket identifier.
          examples:
          - ticket_demo_123
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTicketBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketEnvelope'
          description: OK
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Bad Request
        '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: Update a ticket
      tags:
      - Tickets
      x-required-scopes:
      - tickets.write
  /v1/tickets/{ticket_id}/comments:
    get:
      description: Returns ticket comments in ascending chronological order.
      operationId: list-ticket-comments
      parameters:
      - description: Ticket identifier.
        in: path
        name: ticket_id
        required: true
        schema:
          description: Ticket identifier.
          examples:
          - ticket_demo_123
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketCommentsEnvelope'
          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: List ticket comments
      tags:
      - Tickets
      x-required-scopes:
      - tickets.read
    post:
      description: Creates a plain-text comment authored by the API key creator.
      operationId: create-ticket-comment
      parameters:
      - description: Ticket identifier.
        in: path
        name: ticket_id
        required: true
        schema:
          description: Ticket identifier.
          examples:
          - ticket_demo_123
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommentBody'
        required: true
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketCommentEnvelope'
          description: Created
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Bad Request
        '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: Create a ticket comment
      tags:
      - Tickets
      x-required-scopes:
      - tickets.write
  /v1/tickets/{ticket_id}/comments/{comment_id}:
    delete:
      description: Deletes a ticket comment. The author can delete their own comments, and workspace admins can delete any ticket comment.
      operationId: delete-ticket-comment
      parameters:
      - description: Ticket identifier.
        in: path
        name: ticket_id
        required: true
        schema:
          description: Ticket identifier.
          examples:
          - ticket_demo_123
          type: string
      - description: Ticket comment identifier.
        in: path
        name: comment_id
        required: true
        schema:
          description: Ticket comment identifier.
          examples:
          - ticket_comment_demo_123
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketDeletedEnvelope'
          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: Delete a ticket comment
      tags:
      - Tickets
      x-required-scopes:
      - tickets.write
    patch:
      description: Updates a ticket comment. Only the comment author can edit an existing comment.
      operationId: update-ticket-comment
      parameters:
      - description: Ticket identifier.
        in: path
        name: ticket_id
        required: true
        schema:
          description: Ticket identifier.
          examples:
          - ticket_demo_123
          type: string
      - description: Ticket comment identifier.
        in: path
        name: comment_id
        required: true
        schema:
          description: Ticket comment identifier.
          examples:
          - ticket_comment_demo_123
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CommentBody'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TicketCommentEnvelope'
          description: OK
        '400':
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/ErrorModel'
          description: Bad Request
        '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: Update a ticket comment
      tags:
      - Tickets
      x-required-scopes:
      - tickets.write
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
    TicketCustomFieldSummary:
      additionalProperties: false
      properties:
        columnKey:
          description: Stable custom field key.
          examples:
          - source_campaign
          type: string
        value:
          description: Raw JSON value stored for the custom field.
      required:
      - columnKey
      - value
      type: object
    TicketsList:
      additionalProperties: false
      properties:
        items:
          items:
            $ref: '#/components/schemas/TicketSummary'
          type:
          - array
          - 'null'
        pagination:
          $ref: '#/components/schemas/Pagination'
      required:
      - items
      - pagination
      type: object
    TicketUserSummary:
      additionalProperties: false
      properties:
        displayName:
          description: Preferred display name for the member.
          examples:
          - Alex Example
          type:
          - string
          - 'null'
        email:
          description: Workspace member email when available.
          examples:
          - alex@example.test
          type:
          - string
          - 'null'
        id:
          description: Workspace member identifier.
          examples:
          - user_demo_123
          type: string
      required:
      - id
      - displayName
      - email
      type: object
    TicketCommentsEnvelope:
      additionalProperties: false
      properties:
        data:
          $ref: '#/components/schemas/TicketCommentsList'
      required:
      - data
      type: object
    CommentBody:
      additionalProperties: false
      properties:
        body:
          description: Markdown-free plain text comment body.
          examples:
          - Sent a follow-up message and waiting for confirmation.
          minLength: 1
          type: string
      required:
      - body
      type: object
    TicketCommentsList:
      additionalProperties: false
      properties:
        items:
          items:
            $ref: '#/components/schemas/TicketCommentSummary'
          type:
          - array
          - 'null'
      required:
      - items
      type: object
    UpdateTicketBody:
      additionalProperties: false
      properties:
        assignedToId:
          description: Updated assignee. Send an empty string to unassign.
          examples:
          - user_demo_123
          type: string
        comment:
          description: Updated short note. Send an empty string to clear it.
          examples:
          - Waiting for sample approval
          type: string
        customFields:
          additionalProperties: {}
          description: Partial custom-field patch keyed by columnKey. Null or empty-string values delete a field.
          type: object
        date:
          description: Updated RFC3339 timestamp. Send an empty string to clear it.
          examples:
          - '2026-04-02T09:30:00Z'
          format: date-time
          type: string
        description:
          description: Updated description. Send an empty string to clear it.
          examples:
          - Synthetic customer moved the follow-up to Friday.
          type: string
        linkedChatIds:
          description: Full replacement of linked Telegram chat ids. Send an empty array to unlink all chats.
          items:
            type: string
          type: array
        priority:
          description: Updated priority.
          examples:
          - LOW
          type: string
        status:
          description: Updated status. Setting any non-CLOSED value clears closedAt/closedBy.
          examples:
          - IN_PROGRESS
          type: string
        title:
          description: Updated title. Empty string is rejected.
          examples:
          - Confirm onboarding checklist
          type: string
      type: object
    TicketEnvelope:
      additionalProperties: false
      properties:
        data:
          $ref: '#/components/schemas/TicketSummary'
      required:
      - data
      type: object
    TicketCommentEnvelope:
      additionalProperties: false
      properties:
        data:
          $ref: '#/components/schemas/TicketCommentSummary'
      required:
      - data
      type: object
    TicketCommentSummary:
      additionalProperties: false
      properties:
        author:
          $ref: '#/components/schemas/TicketUserSummary'
          description: Author of the comment.
        body:
          description: Comment body.
          examples:
          - Sent a follow-up message and waiting for confirmation.
          type: string
        createdAt:
          description: Comment creation timestamp.
          format: date-time
          type: string
        id:
          description: Ticket comment identifier.
          examples:
          - ticket_comment_demo_123
          type: string
        ticketId:
          description: Owning ticket identifier.
          examples:
          - ticket_demo_123
          type: string
        updatedAt:
          description: Comment last update timestamp.
          format: date-time
          type: string
      required:
      - id
      - ticketId
      - body
      - createdAt
      - updatedAt
      - author
      type: object
    TicketDeletedResource:
      additionalProperties: false
      properties:
        id:
          description: Deleted resource identifier.
          examples:
          - ticket_demo_123
          type: string
      required:
      - id
      type: object
    TicketsEnvelope:
      additionalProperties: false
      properties:
        data:
          $ref: '#/components/schemas/TicketsList'
      required:
      - data
      type: object
    TicketSummary:
      additionalProperties: false
      properties:
        assignedTo:
          $ref: '#/components/schemas/TicketUserSummary'
          description: Workspace member assigned to the ticket.
        attachmentCount:
          description: Total number of ticket attachments.
          examples:
          - 1
          format: int64
          type: integer
        closedAt:
          description: Closing timestamp when the ticket is completed.
          format: date-time
          type:
          - string
          - 'null'
        closedBy:
          $ref: '#/components/schemas/TicketUserSummary'
          description: Workspace member who closed the ticket.
        comment:
          description: Optional short operator note stored directly on the ticket.
          examples:
          - Sample escalation note
          type:
          - string
          - 'null'
        commentCount:
          description: Total number of ticket comments.
          examples:
          - 3
          format: int64
          type: integer
        createdAt:
          description: Ticket creation timestamp.
          format: date-time
          type: string
        createdBy:
          $ref: '#/components/schemas/TicketUserSummary'
          description: Workspace member that created the ticket.
        customFields:
          description: Workspace ticket custom field values.
          items:
            $ref: '#/components/schemas/TicketCustomFieldSummary'
          type:
          - array
          - 'null'
        date:
          description: Optional business date associated with the ticket.
          format: date-time
          type:
          - string
          - 'null'
        description:
          description: Long-form ticket description.
          examples:
          - Synthetic customer asked for a follow-up next week.
          type:
          - string
          - 'null'
        displayId:
          description: Human-facing numbered ticket identifier.
          examples:
          - '#42'
          type: string
        id:
          description: Ticket identifier.
          examples:
          - ticket_demo_123
          type: string
        legacyTicketHash:
          description: Previous random ticket hash retained for lookup compatibility.
          examples:
          - '#TKT-001'
          type: string
        linkedChatIds:
          description: Telegram chat identifiers currently linked to the ticket.
          items:
            type: string
          type:
          - array
          - 'null'
        priority:
          description: Priority label.
          examples:
          - HIGH
          type: string
        status:
          description: Current workflow status.
          examples:
          - OPEN
          type: string
        ticketHash:
          description: Deprecated compatibility alias for displayId.
          examples:
          - '#42'
          type:
          - string
          - 'null'
        ticketNumber:
          description: Workspace-scoped human-facing ticket number.
          examples:
          - 42
          format: int64
          type: integer
        title:
          description: Ticket title.
          examples:
          - Review onboarding request
          type: string
        updatedAt:
          description: Ticket last update timestamp.
          format: date-time
          type: string
        userId:
          description: Owner user identifier in the frontend database.
          examples:
          - user_demo_123
          type: string
        workspaceId:
          description: Workspace identifier owning the ticket.
          examples:
          - workspace_demo_123
          type:
          - string
          - 'null'
      required:
      - id
      - ticketNumber
      - displayId
      - ticketHash
      - title
      - description
      - status
      - priority
      - comment
      - date
      - createdAt
      - updatedAt
      - closedAt
      - userId
      - workspaceId
      - commentCount
      - attachmentCount
      - linkedChatIds
      - customFields
      - createdBy
      - assignedTo
      - closedBy
      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
    TicketDeletedEnvelope:
      additionalProperties: false
      properties:
        data:
          $ref: '#/components/schemas/TicketDeletedResource'
      required:
      - data
      type: object
    CreateTicketBody:
      additionalProperties: false
      properties:
        assignedToId:
          description: Optional workspace member id to assign immediately.
          examples:
          - user_demo_123
          type: string
        comment:
          description: Optional short operator note stored directly on the ticket.
          examples:
          - Escalate if no response within 48h
          type: string
        customFields:
          additionalProperties: {}
          description: Workspace ticket custom fields keyed by columnKey.
          type: object
        date:
          description: Optional RFC3339 timestamp stored in the ticket date field.
          examples:
          - '2026-03-30T10:00:00Z'
          format: date-time
          type: string
        description:
          description: Optional long-form description.
          examples:
          - Synthetic customer asked for a walkthrough next week.
          type: string
        linkedChatIds:
          description: Telegram chat ids to link on creation.
          items:
            type: string
          type:
          - array
          - 'null'
        priority:
          description: Initial priority. Defaults to MEDIUM.
          examples:
          - HIGH
          type: string
        status:
          description: Initial status. Defaults to OPEN.
          examples:
          - OPEN
          type: string
        title:
          description: Ticket title shown in operator UI and API responses.
          examples:
          - Review onboarding request
          minLength: 1
          type: string
      required:
      - title
      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