Halo Connect Registered Queries API

openapi: 3.2.0
info:
  title: Halo Connect Registered Queries API
  version: 26.619.10213
  license:
    name: Copyright © Halo Connect 2023
    url: http://haloconnect.io
  x-logo:
    url: https://20496383.fs1.hubspotusercontent-na1.net/hubfs/20496383/halo_logo%20(1).png
    altText: Halo Connect Logo
  description: 'Operations tagged Registered Queries across 2 of this provider''s published API definitions: halo-connect-desktop-openapi.json, halo-connect-integrator-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://api.haloconnect.io
  description: Production
- url: https://api.stage.haloconnect.io
  description: Stage
tags:
- name: Registered Queries
paths:
  /desktop/sites/{siteId}/queries/registered:
    post:
      tags:
      - Registered Queries
      summary: Create registered query
      description: Create a registered query to be queued for execution.
      operationId: createRegisteredQuery
      parameters:
      - name: siteId
        in: path
        description: Halo GUID of the site.
        required: true
        schema:
          type: string
      responses:
        '201':
          description: Accept Registered Query
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                properties:
                  id:
                    type: string
                    format: uuid
                    description: Unique identifier of the entity.
              example:
                id: 785f1ae1-1234-abcd-56ef-8679258f4aee
        '400':
          description: Invalid request path parameter or body.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      status:
                        type: integer
                        format: httpStatus
                      statusText:
                        type: string
                        format: httpStatusPhrase
                      message:
                        type: string
              example:
                error:
                  status: 400
                  statusText: Bad Request
                  message: Malformed SQL
        '401':
          description: Unauthorized request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      status:
                        type: integer
                        format: httpStatus
                      statusText:
                        type: string
                        format: httpStatusPhrase
                      message:
                        type: string
              example:
                error:
                  status: 401
                  statusText: Unauthorized
                  message: Access denied due to missing subscription key. Make sure to include subscription key when making requests to an API.
        '403':
          description: Access to resource is forbidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      status:
                        type: integer
                        format: httpStatus
                      statusText:
                        type: string
                        format: httpStatusPhrase
                      message:
                        type: string
              example:
                error:
                  status: 403
                  statusText: Forbidden
                  message: Access denied due to missing subscription key. Make sure to include subscription key when making requests to an API.
        '404':
          description: The server cannot find the requested resource.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      status:
                        type: integer
                        format: httpStatus
                      statusText:
                        type: string
                        format: httpStatusPhrase
                      message:
                        type: string
              example:
                error:
                  status: 404
                  statusText: Not Found
                  message: The server cannot find the requested resource.
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      status:
                        type: integer
                        format: httpStatus
                      statusText:
                        type: string
                        format: httpStatusPhrase
                      message:
                        type: string
              example:
                error:
                  status: 500
                  statusText: Internal Server Error
                  message: Failed to create query container in CosmosDB.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - name
              - registeredQueryType
              - frequency
              - duration
              - registerCommand
              properties:
                name:
                  type: string
                  description: Customer set identifier for this registered query.
                registeredQueryType:
                  type: string
                  enum:
                  - query
                frequency:
                  type: integer
                  description: Seconds between each query execution.
                  example: 300
                duration:
                  type: integer
                  description: Duration in seconds the query will run for. Up to 86400 seconds (24 hours).
                  example: 43200
                registerCommand:
                  type: object
                  description: Command to be executed by the registered query.
                  properties:
                    command:
                      type: object
                      properties:
                        text:
                          type: string
                          example: GetPatientID
                          description: The SQL statement to execute or the name of the stored procedure to run.
                        executionMode:
                          description: Selects between fetching data or writing to the database. `reader` executes the command (e.g. SELECT) and returns rows of data. `nonQuery` executes the command (e.g. UPDATE, INSERT, or DELETE) and does not return data.  `scalar` returns first value of first row of query results.  For Querys using RETURN @values please use `returnValue` Parameters.
                          type: string
                          enum:
                          - reader
                          - nonQuery
                          - scalar
                          default: reader
                        type:
                          description: Indicates how the text property is to be interpreted. `text` executes the SQL contained within the text property. `storedProcedure` calls the stored procedure named in the text property. `storedProcedure` is currently experimental.
                          type: string
                          enum:
                          - text
                          - storedProcedure
                          default: text
                        parameters:
                          type: array
                          description: Parameters are used to supply data to, or read outputs from, a stored procedure.
                          items:
                            type: object
                            properties:
                              name:
                                type: string
                                example: '@siteid'
                                description: The name of the parameter.
                              direction:
                                description: A value that indicates whether the parameter is input-only, output-only, bidirectional, or a stored procedure return value parameter.
                                type: string
                                enum:
                                - output
                                - input
                                - inputOutput
                                - returnValue
                              type:
                                description: Specifies SQL Server-specific data type of a field, property.
                                type: string
                                enum:
                                - BigInt
                                - Binary
                                - Bit
                                - Char
                                - String
                                - Date
                                - DateTime
                                - DateTime2
                                - DateTimeOffset
                                - Decimal
                                - Float
                                - Image
                                - Int
                                - Money
                                - NChar
                                - NText
                                - NVarChar
                                - Real
                                - SmallDateTime
                                - SmallInt
                                - SmallMoney
                                - Structured
                                - Text
                                - Time
                                - Timestamp
                                - TinyInt
                                - Udt
                                - UniqueIdentifier
                                - VarBinary
                                - VarChar
                                - Variant
                                - Xml
                              value:
                                description: Gets or sets the value of the parameter.
                                type:
                                - string
                                - 'null'
                                format: base64 (output)
                                example: '66'
                              size:
                                description: The maximum size, in bytes, of the data within the column.
                                type: integer
                                example: 43
                      required:
                      - text
      security:
      - AuthorizationHeader: []
        DeviceIdHeader: []
    get:
      tags:
      - Registered Queries
      summary: List registered queries
      description: List all registered queries that are currently active and queued for execution.
      operationId: getRegisteredQueries
      parameters:
      - name: siteId
        in: path
        description: Halo GUID of the site.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: List of Registered Queries
          content:
            application/json:
              schema:
                type: object
                properties:
                  registeredQueries:
                    type: array
                    items:
                      type: object
                      required:
                      - id
                      - name
                      - registeredQueryType
                      - status
                      - frequency
                      - duration
                      - createdAt
                      - metrics
                      properties:
                        id:
                          type: string
                          format: uuid
                          description: Unique identifier of the entity.
                        name:
                          type: string
                          description: Customer set identifier for this registered query.
                        registeredQueryType:
                          type: string
                          enum:
                          - query
                        status:
                          type: string
                          enum:
                          - initialisationFailedCacheError
                          - enabled
                          - cancelled
                          - completed
                        frequency:
                          type: integer
                          description: Seconds between each query execution.
                          example: 300
                        duration:
                          type: integer
                          description: Duration in seconds the query will run for. Up to 86400 seconds (24 hours).
                          example: 43200
                        lastHash:
                          type: string
                          description: Hash of the last successful query result. Present only when the run completes successfully; otherwise empty.
                        lastErrorDetails:
                          description: Details of the last error thrown by running the registered query. Only populated if the query errors.
                          type: object
                          properties:
                            errorType:
                              type: string
                              enum:
                              - http
                              - mssql
                              - fbsql
                              - haloLink
                            errorCode:
                              type: integer
                            errorMessage:
                              type: string
                        metrics:
                          type: object
                          properties:
                            lastSucceededAt:
                              type: string
                            lastFailedAt:
                              type: string
                            lastExecutionDuration:
                              type: integer
                            executionSucceededCount:
                              type: integer
                            executionFailedCount:
                              type: integer
                            resultSizeSum:
                              type: integer
                            requestSize:
                              type: integer
                        createdAt:
                          description: When the registered query was created.
                          type: string
                          format: date-time
                        completedAt:
                          description: When the registered query completed. Only populated on completion.
                          type: string
                          format: date-time
              example:
                registeredQueries:
                - id: d8d667d9-1234-abcd-56ef-1234567890ab
                  name: Test
                  registeredQueryType: query
                  status: enabled
                  frequency: 60
                  duration: 120
                  createdAt: '2025-05-27T05:23:40.983Z'
                  lastHash: dOFA...
                  metrics:
                    lastExecutionDuration: 15
                    executionSucceededCount: 1
                    executionFailedCount: 0
                    resultSizeSum: 8
                    requestSize: 180
                    lastSucceededAt: '2025-05-27T05:23:46.836Z'
                - id: 6cf4e9be-1234-abcd-56ef-1234567890ab
                  name: Test
                  registeredQueryType: query
                  status: completed
                  frequency: 60
                  duration: 120
                  createdAt: '2025-05-27T04:57:48.791Z'
                  completedAt: '2025-05-27T04:59:54.226Z'
                  lastErrorDetails:
                    errorType: mssql
                    errorCode: 2812
                    errorMessage: Could not find stored procedure 'selct'.
                  metrics:
                    lastExecutionDuration: 0
                    executionSucceededCount: 0
                    executionFailedCount: 3
                    resultSizeSum: 0
                    requestSize: 179
                    lastFailedAt: '2025-05-27T04:59:54.226Z'
        '400':
          description: Invalid request path parameter or body.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      status:
                        type: integer
                        format: httpStatus
                      statusText:
                        type: string
                        format: httpStatusPhrase
                      message:
                        type: string
              example:
                error:
                  status: 400
                  statusText: Bad Request
                  message: Malformed SQL
        '401':
          description: Unauthorized request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      status:
                        type: integer
                        format: httpStatus
                      statusText:
                        type: string
                        format: httpStatusPhrase
                      message:
                        type: string
              example:
                error:
                  status: 401
                  statusText: Unauthorized
                  message: Access denied due to missing subscription key. Make sure to include subscription key when making requests to an API.
        '403':
          description: Access to resource is forbidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      status:
                        type: integer
                        format: httpStatus
                      statusText:
                        type: string
                        format: httpStatusPhrase
                      message:
                        type: string
              example:
                error:
                  status: 403
                  statusText: Forbidden
                  message: Access denied due to missing subscription key. Make sure to include subscription key when making requests to an API.
        '404':
          description: The server cannot find the requested resource.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      status:
                        type: integer
                        format: httpStatus
                      statusText:
                        type: string
                        format: httpStatusPhrase
                      message:
                        type: string
              example:
                error:
                  status: 404
                  statusText: Not Found
                  message: The server cannot find the requested resource.
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      status:
                        type: integer
                        format: httpStatus
                      statusText:
                        type: string
                        format: httpStatusPhrase
                      message:
                        type: string
              example:
                error:
                  status: 500
                  statusText: Internal Server Error
                  message: Failed to create query container in CosmosDB.
      security:
      - AuthorizationHeader: []
        DeviceIdHeader: []
    servers:
    - url: https://api.haloconnect.io
      description: Production
    - url: https://api.stage.haloconnect.io
      description: Stage
  /desktop/sites/{siteId}/queries/registered/{queryId}:
    get:
      tags:
      - Registered Queries
      summary: Get registered query details
      description: Get the details of a registered query.
      operationId: getRegisteredQuery
      parameters:
      - name: siteId
        in: path
        description: Halo GUID of the site.
        required: true
        schema:
          type: string
      - name: queryId
        in: path
        description: Id of the query.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Registered Query
          content:
            application/json:
              schema:
                type: object
                required:
                - id
                - name
                - registeredQueryType
                - status
                - frequency
                - duration
                - createdAt
                - metrics
                properties:
                  id:
                    type: string
                    format: uuid
                    description: Unique identifier of the entity.
                  name:
                    type: string
                    description: Customer set identifier for this registered query.
                  registeredQueryType:
                    type: string
                    enum:
                    - query
                  status:
                    type: string
                    enum:
                    - initialisationFailedCacheError
                    - enabled
                    - cancelled
                    - completed
                  frequency:
                    type: integer
                    description: Seconds between each query execution.
                    example: 300
                  duration:
                    type: integer
                    description: Duration in seconds the query will run for. Up to 86400 seconds (24 hours).
                    example: 43200
                  lastHash:
                    type: string
                    description: Hash of the last successful query result. Present only when the run completes successfully; otherwise empty.
                  lastErrorDetails:
                    description: Details of the last error thrown by running the registered query. Only populated if the query errors.
                    type: object
                    properties:
                      errorType:
                        type: string
                        enum:
                        - http
                        - mssql
                        - fbsql
                        - haloLink
                      errorCode:
                        type: integer
                      errorMessage:
                        type: string
                  metrics:
                    type: object
                    properties:
                      lastSucceededAt:
                        type: string
                      lastFailedAt:
                        type: string
                      lastExecutionDuration:
                        type: integer
                      executionSucceededCount:
                        type: integer
                      executionFailedCount:
                        type: integer
                      resultSizeSum:
                        type: integer
                      requestSize:
                        type: integer
                  createdAt:
                    description: When the registered query was created.
                    type: string
                    format: date-time
                  completedAt:
                    description: When the registered query completed. Only populated on completion.
                    type: string
                    format: date-time
              examples:
                Successful ongoing query:
                  value:
                    id: d8d667d9-1234-abcd-56ef-1234567890ab
                    name: Test
                    registeredQueryType: query
                    status: enabled
                    frequency: 60
                    duration: 120
                    createdAt: '2025-05-27T05:23:40.983Z'
                    lastHash: dOFA...
                    metrics:
                      lastExecutionDuration: 15
                      executionSucceededCount: 1
                      executionFailedCount: 0
                      resultSizeSum: 8
                      requestSize: 180
                      lastSucceededAt: '2025-05-27T05:23:46.836Z'
                Failed completed query:
                  value:
                    id: 6cf4e9be-1234-abcd-56ef-1234567890ab
                    name: Test
                    registeredQueryType: query
                    status: completed
                    frequency: 60
                    duration: 120
                    createdAt: '2025-05-27T04:57:48.791Z'
                    completedAt: '2025-05-27T04:59:54.226Z'
                    lastErrorDetails:
                      errorType: mssql
                      errorCode: 2812
                      errorMessage: Could not find stored procedure 'selct'.
                    metrics:
                      lastExecutionDuration: 0
                      executionSucceededCount: 0
                      executionFailedCount: 3
                      resultSizeSum: 0
                      requestSize: 179
                      lastFailedAt: '2025-05-27T04:59:54.226Z'
        '400':
          description: Invalid request path parameter or body.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      status:
                        type: integer
                        format: httpStatus
                      statusText:
                        type: string
                        format: httpStatusPhrase
                      message:
                        type: string
              example:
                error:
                  status: 400
                  statusText: Bad Request
                  message: Malformed SQL
        '401':
          description: Unauthorized request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      status:
                        type: integer
                        format: httpStatus
                      statusText:
                        type: string
                        format: httpStatusPhrase
                      message:
                        type: string
              example:
                error:
                  status: 401
                  statusText: Unauthorized
                  message: Access denied due to missing subscription key. Make sure to include subscription key when making requests to an API.
        '403':
          description: Access to resource is forbidden.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      status:
                        type: integer
                        format: httpStatus
                      statusText:
                        type: string
                        format: httpStatusPhrase
                      message:
                        type: string
              example:
                error:
                  status: 403
                  statusText: Forbidden
                  message: Access denied due to missing subscription key. Make sure to include subscription key when making requests to an API.
        '404':
          description: The server cannot find the requested resource.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      status:
                        type: integer
                        format: httpStatus
                      statusText:
                        type: string
                        format: httpStatusPhrase
                      message:
                        type: string
              example:
                error:
                  status: 404
                  statusText: Not Found
                  message: The server cannot find the requested resource.
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      status:
                        type: integer
                        format: httpStatus
                      statusText:
                        type: string
                        format: httpStatusPhrase
                      message:
                        type: string
              example:
                error:
                  status: 500
                  statusText: Internal Server Error
                  message: Failed to create query container in CosmosDB.
      security:
      - AuthorizationHeader: []
        DeviceIdHeader: []
    delete:
      tags:
      - Registered Queries
      summary: Cancel registered query
      description: Cancel a registered query that is currently queued for execution.
      operationId: cancelRegisteredQuery
      parameters:
      - name: siteId
        in: path
        description: Halo GUID of the site.
        required: true
        schema:
          type: string
      - name: queryId
        in: path
        description: Id of the query.
        required: true
        schema:
          type: string
      responses:
        '204':
          description: Registered Query Delete
        '400':
          description: Invalid request path parameter or body.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      status:
                        type: integer
                        format: httpStatus
                      statusText:
                        type: string
                        format: httpStatusPhrase
                      message:
                        type: string
              example:
                error:
                  status: 400
                  statusText: Bad Request
                  message: Malformed SQL
        '401':
          description: Unauthorized request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
           

# --- truncated at 32 KB (86 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/halo-connect/refs/heads/main/openapi/halo-connect-registered-queries-api-openapi.yml