Hex

Hex Threads API

The Threads API from Hex — 4 operation(s) for threads.

GitHub OpenAPI

Documentation

📖
Authentication
https://raw.githubusercontent.com/api-evangelist/hex/refs/heads/main/authentication/hex-authentication.yml

Specifications

⚙
OpenAPI
https://raw.githubusercontent.com/api-evangelist/hex/refs/heads/main/openapi/hex-threads-api-openapi.yml

Other Resources

🔗
ErrorCatalog
https://raw.githubusercontent.com/api-evangelist/hex/refs/heads/main/errors/hex-problem-types.yml
🔗
Conventions
https://raw.githubusercontent.com/api-evangelist/hex/refs/heads/main/conventions/hex-conventions.yml
🔗
DataModel
https://raw.githubusercontent.com/api-evangelist/hex/refs/heads/main/data-model/hex-data-model.yml
🔗
Conformance
https://raw.githubusercontent.com/api-evangelist/hex/refs/heads/main/conformance/hex-conformance.yml

OpenAPI Specification

hex-threads-api-openapi.yml Raw ↑ 
openapi: 3.0.3
info:
  title: Hex Cells Threads 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: Threads
paths:
  /v1/threads:
    post:
      operationId: CreateThread
      summary: CreateThread
      description: "Start an agent thread with a prompt. The Hex agent will analyze data and respond to the prompt. The thread runs asynchronously — poll its status or visit the returned URL to view progress.\n\nAvailability of this endpoint varies by organization. Contact Hex support to request access.\n\nThis endpoint is subject to the following rate limits:\n- `hex-send-thread-message`: Rate limits for sending messages to threads\n  - Max requests per minute may vary\n  - Max requests per hour may vary"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                prompt:
                  type: string
                  minLength: 1
                attachments:
                  type: object
                  properties:
                    dataConnectionId:
                      type: string
                      nullable: true
                      description: Data connection referenced by the prompt
                    tableIds:
                      type: array
                      items:
                        type: string
                      description: Tables referenced by the prompt
                    semanticDatasetIds:
                      type: array
                      items:
                        type: string
                      description: Semantic datasets referenced by the prompt
                    semanticViewIds:
                      type: array
                      items:
                        type: string
                      description: Semantic views referenced by the prompt
                    projectIds:
                      type: array
                      items:
                        type: string
                      description: Projects referenced by the prompt
                  description: Entities referenced by the prompt
                previewId:
                  type: string
                  nullable: true
                projectId:
                  type: string
                  nullable: true
                  description: Run the thread against an existing project. Mutually exclusive with `newProject`
                newProject:
                  type: boolean
                  nullable: true
                  description: Create a new project for the thread to work on. Mutually exclusive with `projectId`
                muted:
                  type: boolean
                  nullable: true
                  description: If true, the thread will not be shown in any aggregated UI surfaces and will not contribute to user-facing statistics. The thread is still individually viewable. Only applies for non-project-backed threads (ignored when `projectId` or `newProject` is set). This is distinct from a `sensitive` thread.
              required:
              - prompt
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  threadId:
                    type: string
                  url:
                    type: string
                  createdAt:
                    type: string
                  projectId:
                    type: string
                    nullable: true
                required:
                - threadId
                - url
                - createdAt
                - projectId
        '400':
          description: Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.BAD_REQUEST'
        '401':
          description: Authorization not provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.UNAUTHORIZED'
        '403':
          description: Insufficient access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.FORBIDDEN'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.INTERNAL_SERVER_ERROR'
      tags:
      - Threads
    get:
      operationId: ListThreads
      summary: ListThreads
      description: "List agent threads in the workspace, sorted by most recently created first. Requires Manager org role or higher. Workspace admins receive every non-private thread; managers receive threads they created plus Threads-type threads on projects they have access to. Threads marked private are returned with their title redacted.\n\nThis endpoint is subject to the following rate limits:\n- `hex-api`: Default rate limit group for the Hex API\n  - Max requests per minute may vary (default: 30)\n  - Max requests per hour may vary (default: 1800)"
      parameters:
      - in: query
        name: after
        schema:
          type: string
          nullable: true
          default: null
      - in: query
        name: before
        schema:
          type: string
          nullable: true
          default: null
      - in: query
        name: limit
        schema:
          type: number
          minimum: 1
          maximum: 100
          default: 25
      - in: query
        name: source
        schema:
          type: string
          nullable: true
          enum:
          - HEX
          - SLACK
          - MCP
          - PUBLIC_API
          - null
      - in: query
        name: userId
        schema:
          type: string
          nullable: true
      - in: query
        name: type
        schema:
          type: string
          nullable: true
          enum:
          - THREADS
          - NOTEBOOK
          - MODELING
          - null
      - in: query
        name: numDays
        schema:
          type: integer
          nullable: true
          minimum: 0
          exclusiveMinimum: true
      - in: query
        name: hasFeedback
        schema:
          type: boolean
          nullable: true
      - in: query
        name: roles
        description: Comma-separated list of user org roles to filter by (ADMIN, MANAGER, EDITOR, EXPLORER, MEMBER, GUEST)
        schema:
          type: string
          nullable: true
          description: Comma-separated list of user org roles to filter by (ADMIN, MANAGER, EDITOR, EXPLORER, MEMBER, GUEST)
      - in: query
        name: warnings
        description: Comma-separated list of warning types to filter by (DATA_LIMITATION, USER_DOUBT, MISSING_CONTEXT, OTHER)
        schema:
          type: string
          nullable: true
          description: Comma-separated list of warning types to filter by (DATA_LIMITATION, USER_DOUBT, MISSING_CONTEXT, OTHER)
      - in: query
        name: topicIds
        description: Comma-separated list of topic IDs to filter by
        schema:
          type: string
          nullable: true
          description: Comma-separated list of topic IDs to filter by
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  threads:
                    type: array
                    items:
                      type: object
                      properties:
                        title:
                          type: string
                          nullable: true
                          description: Title of the thread, when available. Null for private threads
                        creditsUsed:
                          type: number
                          nullable: true
                          description: The total credits used by the thread
                        topics:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                              name:
                                type: string
                            required:
                            - id
                            - name
                        warnings:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                              type:
                                type: string
                              summary:
                                type: string
                            required:
                            - id
                            - type
                            - summary
                        feedback:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                              userFeedback:
                                type: string
                              type:
                                type: string
                                enum:
                                - THUMBS
                                - FLAG
                              selectedReason:
                                type: string
                                nullable: true
                              userLiked:
                                type: boolean
                            required:
                            - id
                            - userFeedback
                            - type
                            - userLiked
                        warningsGeneratedAt:
                          type: string
                          nullable: true
                        threadSummary:
                          type: string
                          nullable: true
                        threadIntent:
                          type: string
                          nullable: true
                        model:
                          type: string
                        userId:
                          type: string
                          nullable: true
                        type:
                          type: string
                          description: User-facing label for the type of agent thread
                        source:
                          type: string
                          description: The source of where the thread was created
                        createdAt:
                          type: string
                        sensitive:
                          type: boolean
                          description: Whether the thread has been marked as sensitive. When true, the thread's contents (such as title) are hidden from callers other than the thread author
                        id:
                          type: string
                        orgId:
                          type: string
                        url:
                          type: string
                      required:
                      - userId
                      - type
                      - source
                      - createdAt
                      - sensitive
                      - id
                      - orgId
                      - url
                  pagination:
                    type: object
                    properties:
                      before:
                        type: string
                        nullable: true
                        default: null
                      after:
                        type: string
                        nullable: true
                        default: null
                    required:
                    - before
                    - after
                required:
                - threads
                - pagination
        '400':
          description: Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.BAD_REQUEST'
        '401':
          description: Authorization not provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.UNAUTHORIZED'
        '403':
          description: Insufficient access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.FORBIDDEN'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.NOT_FOUND'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.INTERNAL_SERVER_ERROR'
      tags:
      - Threads
  /v1/threads/{id}:
    get:
      operationId: GetThread
      summary: GetThread
      description: "Get the response of an agent thread. Returns the current status (RUNNING, IDLE, or ERROR) and the agent's response content when available.\n\nThis endpoint is subject to the following rate limits:\n- `hex-api`: Default rate limit group for the Hex API\n  - Max requests per minute may vary (default: 30)\n  - Max requests per hour may vary (default: 1800)"
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  title:
                    type: string
                    nullable: true
                    description: Title of the thread, when available. Null for private threads
                  creditsUsed:
                    type: number
                    nullable: true
                    description: The total credits used by the thread
                  topics:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                      required:
                      - id
                      - name
                  warnings:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        type:
                          type: string
                        summary:
                          type: string
                      required:
                      - id
                      - type
                      - summary
                  feedback:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        userFeedback:
                          type: string
                        type:
                          type: string
                          enum:
                          - THUMBS
                          - FLAG
                        selectedReason:
                          type: string
                          nullable: true
                        userLiked:
                          type: boolean
                      required:
                      - id
                      - userFeedback
                      - type
                      - userLiked
                  warningsGeneratedAt:
                    type: string
                    nullable: true
                  threadSummary:
                    type: string
                    nullable: true
                  threadIntent:
                    type: string
                    nullable: true
                  model:
                    type: string
                  userId:
                    type: string
                    nullable: true
                  type:
                    type: string
                    description: User-facing label for the type of agent thread
                  source:
                    type: string
                    description: The source of where the thread was created
                  createdAt:
                    type: string
                  sensitive:
                    type: boolean
                    description: Whether the thread has been marked as sensitive. When true, the thread's contents (such as title) are hidden from callers other than the thread author
                  threadId:
                    type: string
                  status:
                    type: string
                    enum:
                    - IDLE
                    - RUNNING
                    - ERROR
                  url:
                    type: string
                  error:
                    type: object
                    nullable: true
                    properties:
                      type:
                        type: string
                        enum:
                        - NO_CONTEXT
                        - BAD_DATA
                        - AGENT_ERROR
                        - AGENT_OVERLOADED
                        - GENERIC_ERROR
                        - POSSIBLE_PROMPT_INJECTION
                        - OVER_LIMIT
                        - NO_DATA
                        - INVALID_RESPONSE
                        - HALLUCINATED_SCHEMA_ELEMENT
                        - NON_EXPRESSIBLE
                        - INVALID_JOIN
                        - EXPLORE_TIMED_OUT
                        - EXPLORE_ERRORED
                        - EXPLORE_TABLE_SWAPPED
                        - UNSUPPORTED_QUERY_ELEMENTS
                        - EXPLORE_NO_DATA
                        - CHART_ROW_LIMIT_EXCEEDED
                        - BYOK_AUTHENTICATION
                        - AGENT_COMPRESSION_ERROR
                        - TOKEN_COUNTING_FAILURE
                        - REQUEST_CANCELLED
                        - INVALID_MESSAGE_HISTORY
                        - INVALID_REQUEST
                        - DATA_CONNECTION_NOT_AUTHORIZED
                        - JOIN_VALIDATION_TIMEOUT
                      message:
                        type: string
                    required:
                    - type
                    - message
                  response:
                    type: array
                    nullable: true
                    items:
                      oneOf:
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                            - text
                          text:
                            type: string
                        required:
                        - type
                        - text
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                            - cell
                          id:
                            type: string
                          staticId:
                            type: string
                          label:
                            type: string
                            nullable: true
                        required:
                        - type
                        - id
                        - staticId
                        - label
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                            - project
                          id:
                            type: string
                          title:
                            type: string
                            nullable: true
                        required:
                        - type
                        - id
                        - title
                      - type: object
                        properties:
                          type:
                            type: string
                            enum:
                            - task
                          title:
                            type: string
                        required:
                        - type
                        - title
                required:
                - title
                - creditsUsed
                - topics
                - warnings
                - feedback
                - model
                - userId
                - type
                - source
                - createdAt
                - sensitive
                - threadId
                - status
                - url
                - response
        '400':
          description: Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.BAD_REQUEST'
        '401':
          description: Authorization not provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.UNAUTHORIZED'
        '403':
          description: Insufficient access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.FORBIDDEN'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.NOT_FOUND'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.INTERNAL_SERVER_ERROR'
      tags:
      - Threads
  /v1/threads/{threadId}/messages:
    get:
      operationId: GetThreadMessages
      summary: GetThreadMessages
      description: "List the messages in an agent thread, rendered as a single flat list of text blocks. Within a page messages are chronological (oldest first); each text block is prefixed with the authoring role, and thinking and error blocks are tagged. Tool-call, tool-result, and mention blocks are omitted, and inline references are left as raw tags. By default the most recent page is returned (matching the MCP get_thread tool); pass the `before` cursor to fetch older messages and `after` to fetch newer ones. Supports cursor pagination with a maximum page size of 50.\n\nThis endpoint is subject to the following rate limits:\n- `hex-api`: Default rate limit group for the Hex API\n  - Max requests per minute may vary (default: 30)\n  - Max requests per hour may vary (default: 1800)"
      parameters:
      - in: path
        name: threadId
        schema:
          type: string
        required: true
      - in: query
        name: after
        schema:
          type: string
          nullable: true
          default: null
      - in: query
        name: before
        schema:
          type: string
          nullable: true
          default: null
      - in: query
        name: limit
        schema:
          type: number
          minimum: 1
          maximum: 50
          default: 25
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  content:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          enum:
                          - text
                        text:
                          type: string
                      required:
                      - type
                      - text
                      description: A rendered text block from the thread
                    description: The thread's messages rendered as a single flat, ordered list of content blocks
                  pagination:
                    type: object
                    properties:
                      before:
                        type: string
                        nullable: true
                        default: null
                      after:
                        type: string
                        nullable: true
                        default: null
                    required:
                    - before
                    - after
                required:
                - content
                - pagination
        '400':
          description: Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.BAD_REQUEST'
        '401':
          description: Authorization not provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.UNAUTHORIZED'
        '403':
          description: Insufficient access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.FORBIDDEN'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.NOT_FOUND'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.INTERNAL_SERVER_ERROR'
      tags:
      - Threads
  /v1/threads/{id}/followup:
    post:
      operationId: ContinueThread
      summary: ContinueThread
      description: "Continue an existing agent thread with a follow-up prompt. This endpoint does not support queuing: the thread must be idle before a follow-up can be sent.\n\nAvailability of this endpoint varies by organization. Contact Hex support to request access.\n\nThis endpoint is subject to the following rate limits:\n- `hex-send-thread-message`: Rate limits for sending messages to threads\n  - Max requests per minute may vary\n  - Max requests per hour may vary"
      parameters:
      - in: path
        name: id
        schema:
          type: string
        required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                prompt:
                  type: string
                  minLength: 1
                attachments:
                  type: object
                  properties:
                    dataConnectionId:
                      type: string
                      nullable: true
                      description: Data connection referenced by the prompt
                    tableIds:
                      type: array
                      items:
                        type: string
                      description: Tables referenced by the prompt
                    semanticDatasetIds:
                      type: array
                      items:
                        type: string
                      description: Semantic datasets referenced by the prompt
                    semanticViewIds:
                      type: array
                      items:
                        type: string
                      description: Semantic views referenced by the prompt
                    projectIds:
                      type: array
                      items:
                        type: string
                      description: Projects referenced by the prompt
                  description: Entities referenced by the prompt
              required:
              - prompt
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  threadId:
                    type: string
                  url:
                    type: string
                required:
                - threadId
                - url
        '400':
          description: Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.BAD_REQUEST'
        '401':
          description: Authorization not provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.UNAUTHORIZED'
        '403':
          description: Insufficient access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.FORBIDDEN'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.INTERNAL_SERVER_ERROR'
      tags:
      - Threads
components:
  schemas:
    error.BAD_REQUEST:
      type: object
      properties:
        message:
          type: string
          description: The error message
          example: Invalid input data
        code:
          type: string
          description: The error code
          example: BAD_REQUEST
        issues:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
            required:
            - message
          description: An array of issues that were responsible for the error
          example: []
      required:
      - message
      - code
      title: Invalid input data error (400)
      description: The error information
      example:
        code: BAD_REQUEST
        message: Invalid input data
        issues: []
    error.UNAUTHORIZED:
      type: object
      properties:
        message:
          type: string
          description: The error message
          example: Authorization not provided
        code:
          type: string
          description: The error code
          example: UNAUTHORIZED
        issues:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
            required:
            - message
          description: An array of issues that were responsible for the error
          example: []
      required:
      - message
      - code
      title: Authorization not provided error (401)
      description: The error information
      example:
        code: UNAUTHORIZED
        message: Authorization not provided
        issues: []
    error.NOT_FOUND:
      type: object
      properties:
        message:
          type: string
          description: The error message
          example: Not found
        code:
          type: string
          description: The error code
          example: NOT_FOUND
        issues:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
            required:
            - message
          description: An array of issues that were responsible for the error
          example: []
      required:
      - message
      - code
      title: Not found error (404)
      description: The error information
      example:
        code: NOT_FOUND
        message: Not found
        issues: []
    error.INTERNAL_SERVER_ERROR:
      type: object
      properties:
        message:
          type: string
          description: The error message
          example: Internal server error
        code:
          type: string
          description: The error code
          example: INTERNAL_SERVER_ERROR
        issues:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
            required:
            - message
          description: An array of issue

# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hex/refs/heads/main/openapi/hex-threads-api-openapi.yml