---
openapi: 3.0.0
info:
    title: Humio Query API
    description: TODO
    termsOfService: http://humio.com/terms-and-conditions/
    contact:
        name: Humio Support
        url: http://www.humio.com/support
        email: support@humio.com
    license:
        name: Apache 2.0
        url: https://github.com/OAI/OpenAPI-Specification/blob/master/https://www.apache.org/licenses/LICENSE-2.0.html
    version: 1.0.0

paths:
    /api/v1/queryjobs:
        post:
            operationId: submitQuery
            summary: Submit query
            responses:
                '200':
                    description: OK
                    content:
                        'application/json':
                            schema:
                                $ref: "#/components/schemas/QueryJobStartedResult"
                '500':
                    description: Internal Server Error
    /api/v1/queryjobs/{id}:
        get:
            operationId: getQueryResult
            responses:
                '200':
                    description: OK
                    content:
                        'application/json':
                            schema:
                                $ref: "#/components/schemas/QueryResult"
                '500':
                    description: Internal Server Error

components:
    schemas:
        QueryJobStartedResult:
            type: object
            required:
                - id
            properties:
                id:
                    type: string
                    description: "The id of the started queryjob. This can be used to poll results."
                queryOnView:
                    type: string
                    description: "A string representation of the optimized query (the \"query plan\"). For advanced users."
                hashedQueryOnView:
                    type: string
                    description: "A string hash of the optimized query (the \"query plan\"). For advanced users."
                staticMetaData:
                    type: object
                    x-class-name: StaticQueryMetaData
                    properties:
                        executionMode:
                            $ref: "#/components/schemas/ExecutionMode"
        ExecutionMode:
            type: object
            required:
                - runMode
            properties:
                runMode:
                    type: string
                    description: The mode in which the query runs.
                details:
                    type: string
                    description: |- 
                        Details related to the run mode, e.g., why the query
                        runs that way.
            description: |-
                If provided, indicates that the backend is running the query in 
                a special mode, and may include information about the reason for 
                selecting that mode.
        QueryResult:
            type: object
            required:
                - done
                - cancelled
                - metaData
                - events
            properties:
                warnings:
                    type: array
                    items:
                        $ref: "#/components/schemas/WarningJson"
                done:
                    type: boolean
                cancelled:
                    type: boolean
                events:
                    type: array
                    items:
                        type: object
                        x-class-name: Event
                        properties:
                            "@timestamp":
                                type: integer
                                format: int64
                        additionalProperties:
                            type: string
                queryEventDistribution:
                    $ref: "#/components/schemas/QueryEventDistributionJson"
                metaData:
                    $ref: "#/components/schemas/QueryMetaDataJson"
                filterMatches:
                    type: array
                    items:
                        type: object
                        x-class-name: EventFieldMatches
                        additionalProperties:
                            type: array
                            items:
                                type: object
                                x-class-name: FilterMatch
                                required:
                                    - filterId
                                    - ranges
                                properties:
                                    filterId:
                                        type: integer
                                    ranges:
                                        type: array
                                        items:
                                            type: object
                                            x-class-name: FilterMatchRange
                                            required:
                                                - start
                                                - length
                                            properties:
                                                start:
                                                    type: integer
                                                length:
                                                    type: integer


        WarningJson:
            type: object
            required:
                - code
                - message
                - category
            properties:
                classification:
                    type: string
                code:
                    description: A stable message code that can be used to compare error types or look up error descriptions.
                    type: string
                message:
                    description: A Human readable text describing the warning.
                    type: string
                category:
                    type: string
                    description: |-
                        A category that allows clients to deal with warnings more broadly.
                        Rather than have to switch on each error code, categories allow you
                        to deal with a whole set of warnings the same way.
                        
                        - QUERY_STATE - indicates the query is producing a problem on the cluster, e.g. result sets that are too large.
                        - CLUSTER - indicates the cluster is under maintenance or is performing slowly in a non-fatal way.
                        - ACCOUNT - indicates the user's quota or permissions are impacting the results in some way.
                        - REPOSITORY - indicates that settings or the state of a searched repository is impacting results.
                        - UNSPECIFIED - an uncategoried error.
                        
                        Other values may be returned if cluster nodes are out of sync, using a newer or older version
                        of Humio.
        QueryEventDistributionJson:
            type: object
            required:
                - events
                - extraData
            properties:
                events:
                    type: array
                    items:
                        type: object
                        x-class-name: EventDistributionBucket
                        required:
                            - _count
                            - _bucket
                        properties:
                            _count:
                                type: string
                            _bucket:
                                type: string
                extraData:
                    type: object
                    x-class-name: EventDistributionExtraData
                    properties:
                        bucket_first_bucket:
                            type: string
                        bucket_last_bucket:
                            type: string
                        bucket_span_humanized:
                            type: string
                        bucket_span_millis:
                            type: string
        QueryMetaDataJson:
            type: object
            required:
                - eventCount
                - warnings
                - isAggregate
                - extraData
                - queryStart
                - queryEnd
                - processedBytes
                - processedEvents
                - timeMillis
                - totalWork
                - resultBufferSize
                - workDone
                - costs
                - querySpent
                - quotaTotalSpent
            properties:
                eventCount:
                    type: integer
                warning:
                    type: string
                    deprecated: true
                    description: "Use 'warnings' in the message root instead"
                warnings:
                    type: array
                    deprecated: true
                    description: "Use 'warnings' in the message root instead"
                    items:
                        type: string
                isAggregate:
                    type: boolean
                fieldOrder:
                    type: array
                    items:
                        type: string
                extraData:
                    $ref: "#/components/schemas/QueryExtraData"
                queryStart:
                    type: integer
                queryEnd:
                    type: integer
                processedBytes:
                    type: integer
                processedEvents:
                    type: integer
                timeMillis:
                    type: integer
                queuedMillis:
                    type: integer
                totalWork:
                    type: integer
                resultBufferSize:
                    type: integer
                workDone:
                    type: integer
                filterQuery:
                    $ref: "#/components/schemas/QueryJobInput"
                pollAfter:
                    type: integer
                costs:
                    $ref: "#/components/schemas/QueryCostMetadata"
                querySpent:
                    $ref: "#/components/schemas/QueryQuotaMeta"
                quotaTotalSpent:
                    $ref: "#/components/schemas/QueryQuotaMeta"
                responderVHost:
                    type: integer
                    format: int32
                digestFlow:
                    $ref: "#/components/schemas/DigestFlowMeta"
        QueryExtraData:
            type: object
            properties:
                sortOrder:
                    type: array
                    items:
                        type: object
                        required:
                            - field
                            - type
                            - order
                        x-class-name: SortOrderItem
                        properties:
                            field:
                                type: string
                            type:
                                type: string
                            order:
                                type: string
            additionalProperties:
                type: string
        QueryJobInput:
            type: object
            required:
                - queryString
            properties:
                queryString:
                    type: string
                languageVersion:
                    type: string
                start:
                    $ref: "#/components/schemas/IntOrString"
                    default: "24hours"
                end:
                    $ref: "#/components/schemas/IntOrString"
                    default: "now"
                ingestStart:
                    $ref: "#/components/schemas/IntOrString"
                ingestEnd:
                    $ref: "#/components/schemas/IntOrString"
                isInteractive:
                    type: boolean
                    default : false
                showQueryEventDistribution:
                    type: boolean
                    default: false
                    deprecated: true
                    description: |
                        If true Humio will return an additional resultset containing a histogram of the number of events over the time interval.
                        This field is deprecated. Use "results" instead. If both this field an "results" is specified, "results" takes precedence.
                allowEventSkipping:
                    type: boolean
                    default: false
                # TODO: Private
                includeDeletedEvents:
                    type: boolean
                    default : false
                # TODO: Private
                noResultUntilDone:
                    type: boolean
                    default : false
                isLive:
                    type: boolean
                    default : false
                # TODO: Private
                isRepeatingSubquery:
                    type: boolean
                    default : false
                around:
                    type: object
                    x-class-name: Around
                    required:
                        - eventId
                        - timestamp
                    properties:
                        eventId:
                            type: string
                        timestamp:
                            type: integer
                        numberOfEventsBefore:
                            type: integer
                            default: 100
                            format: int32
                        numberOfEventsAfter:
                            type: integer
                            default: 100
                            format: int32
                autobucketCount:
                    type: integer
                    format: int32
                useIngestTime:
                    type: boolean
                    default: false
                arguments:
                    type: object
                    x-class-name: QueryArguments
                    additionalProperties:
                        type: string
                timeZone:
                    type: string
                timeZoneOffsetMinutes:
                    type: integer
                    format: int32
                isAlertQuery:
                    type: boolean
                    default: false
                    description: |
                        Indicates whether the query comes from an alert or not.
        QueryCostMetadata:
            type: object
            required:
                - liveCost
                - staticCost
                - liveCostRate
                - staticCostRate
            properties:
                liveCost:
                    type: number
                    format: double
                staticCost:
                    type: number
                    format: double
                liveCostRate:
                    type: number
                    format: double
                staticCostRate:
                    type: number
                    format: double
        DigestFlowMeta:
            type: object
            required:
                - minIngestTimeIncluded
                - ingestTimeKnownGood
                - maxIngestLatency
            properties:
                minIngestTimeIncluded:
                    type: integer
                ingestTimeKnownGood:
                    type: integer
                maxIngestLatency:
                    type: integer
        QueryQuotaMeta:
            type: object
            required:
                - oneMinute
                - tenMinutes
                - hour
                - day
            properties:
                oneMinute:
                    $ref: "#/components/schemas/QueryQuotaSpent"
                tenMinutes:
                    $ref: "#/components/schemas/QueryQuotaSpent"
                hour:
                    $ref: "#/components/schemas/QueryQuotaSpent"
                day:
                    $ref: "#/components/schemas/QueryQuotaSpent"
        QueryQuotaSpent:
            type: object
            required:
                - queryCount
                - staticCost
                - liveCost
            properties:
                queryCount:
                    type: integer
                    format: int32
                staticCost:
                    type: integer
                liveCost:
                    type: integer
        IntOrString:
            oneOf:
                - type: integer
                  x-class-name: IntOrStringInt
                - type: string
                  x-class-name: IntOrStringString
