openapi: 3.1.0
info:
  title: Cribl Search API
  description: >-
    The Cribl Search API provides programmatic access to Cribl Search, a
    tool for exploring and querying both live and stored observability data
    in real time. Developers can use the API to execute search queries,
    manage datasets, configure search jobs, and integrate federated search
    capabilities into their own applications and workflows. Cribl Search
    supports federated search across multiple data sources, enabling
    organizations to gain insights without needing to move or duplicate
    data into a single location.
  version: '1.0'
  contact:
    name: Cribl Support
    url: https://cribl.io/support/
  termsOfService: https://cribl.io/terms-of-service/
externalDocs:
  description: Cribl Search Documentation
  url: https://docs.cribl.io/search/
servers:
  - url: https://{workspaceName}-{organizationId}.cribl.cloud/api/v1
    description: Cribl Cloud
    variables:
      workspaceName:
        default: default
        description: The name of the Cribl Cloud workspace
      organizationId:
        default: org-id
        description: The Cribl Cloud organization identifier
  - url: https://{hostname}:{port}/api/v1
    description: On-Premises Deployment
    variables:
      hostname:
        default: localhost
        description: The hostname of the Cribl instance
      port:
        default: '9000'
        description: The port of the Cribl instance
tags:
  - name: Datasets
    description: >-
      Manage search datasets that define the data sources available
      for querying, including Cribl Lake, Splunk, and other
      connected data stores.
  - name: Saved Searches
    description: >-
      Create and manage saved search queries for reuse and sharing
      across teams and workflows.
  - name: Search Jobs
    description: >-
      Execute and manage search queries across live and stored
      observability data with support for federated search across
      multiple data sources.
  - name: Search Notifications
    description: >-
      Configure notification rules that trigger alerts based on
      search results using webhook and other notification targets.
security:
  - bearerAuth: []
paths:
  /search/jobs:
    get:
      operationId: listSearchJobs
      summary: List all search jobs
      description: >-
        Retrieves a list of all running and completed search jobs
        including their query, status, and result metrics.
      tags:
        - Search Jobs
      parameters:
        - name: status
          in: query
          description: Filter jobs by status
          schema:
            type: string
            enum:
              - running
              - completed
              - failed
              - cancelled
        - name: limit
          in: query
          description: Maximum number of jobs to return
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: Successfully retrieved search jobs
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/SearchJob'
                  count:
                    type: integer
                    description: Total number of search jobs
        '401':
          description: Unauthorized
    post:
      operationId: createSearchJob
      summary: Execute a new search query
      description: >-
        Creates and executes a new search job with the specified query
        and parameters. The search runs asynchronously and results
        can be retrieved when the job completes. Supports Cribl Search
        query language for filtering, aggregating, and transforming
        results across federated data sources.
      tags:
        - Search Jobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchJobRequest'
      responses:
        '200':
          description: Search job created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchJob'
        '400':
          description: Invalid search query or parameters
        '401':
          description: Unauthorized
  /search/jobs/{id}:
    get:
      operationId: getSearchJob
      summary: Get a search job by ID
      description: >-
        Retrieves the status, progress, and metadata of a specific
        search job. When the job is complete, includes result summary
        information.
      tags:
        - Search Jobs
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Successfully retrieved search job
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchJob'
        '401':
          description: Unauthorized
        '404':
          description: Search job not found
    delete:
      operationId: cancelSearchJob
      summary: Cancel a search job
      description: >-
        Cancels a running search job. Completed or already cancelled
        jobs cannot be cancelled.
      tags:
        - Search Jobs
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Search job cancelled successfully
        '401':
          description: Unauthorized
        '404':
          description: Search job not found
  /search/jobs/{id}/results:
    get:
      operationId: getSearchJobResults
      summary: Get search job results
      description: >-
        Retrieves the results of a completed search job. Results are
        returned as an array of events matching the search query with
        support for pagination.
      tags:
        - Search Jobs
      parameters:
        - $ref: '#/components/parameters/resourceId'
        - name: offset
          in: query
          description: The offset for pagination
          schema:
            type: integer
            default: 0
        - name: limit
          in: query
          description: Maximum number of results to return
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: Successfully retrieved search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      description: A search result event
                  count:
                    type: integer
                    description: Total number of matching events
        '401':
          description: Unauthorized
        '404':
          description: Search job not found
  /search/datasets:
    get:
      operationId: listSearchDatasets
      summary: List all search datasets
      description: >-
        Retrieves all configured search datasets that define the data
        sources available for querying including Cribl Lake datasets,
        Splunk indexes, and other connected data stores.
      tags:
        - Datasets
      responses:
        '200':
          description: Successfully retrieved search datasets
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/SearchDataset'
                  count:
                    type: integer
                    description: Total number of datasets
        '401':
          description: Unauthorized
    post:
      operationId: createSearchDataset
      summary: Create a search dataset
      description: >-
        Creates a new search dataset that defines a data source
        available for querying in Cribl Search.
      tags:
        - Datasets
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchDataset'
      responses:
        '200':
          description: Search dataset created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchDataset'
        '400':
          description: Invalid dataset configuration
        '401':
          description: Unauthorized
  /search/datasets/{id}:
    get:
      operationId: getSearchDataset
      summary: Get a search dataset by ID
      description: >-
        Retrieves the configuration and metadata of a specific search
        dataset.
      tags:
        - Datasets
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Successfully retrieved search dataset
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchDataset'
        '401':
          description: Unauthorized
        '404':
          description: Search dataset not found
    patch:
      operationId: updateSearchDataset
      summary: Update a search dataset
      description: >-
        Updates the configuration of an existing search dataset.
      tags:
        - Datasets
      parameters:
        - $ref: '#/components/parameters/resourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchDataset'
      responses:
        '200':
          description: Search dataset updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchDataset'
        '400':
          description: Invalid dataset configuration
        '401':
          description: Unauthorized
        '404':
          description: Search dataset not found
    delete:
      operationId: deleteSearchDataset
      summary: Delete a search dataset
      description: >-
        Deletes a search dataset by its unique ID. Active search
        jobs referencing this dataset will not be affected.
      tags:
        - Datasets
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Search dataset deleted successfully
        '401':
          description: Unauthorized
        '404':
          description: Search dataset not found
  /search/saved:
    get:
      operationId: listSavedSearches
      summary: List all saved searches
      description: >-
        Retrieves all saved search queries that can be reused and
        shared across teams.
      tags:
        - Saved Searches
      responses:
        '200':
          description: Successfully retrieved saved searches
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/SavedSearch'
                  count:
                    type: integer
                    description: Total number of saved searches
        '401':
          description: Unauthorized
    post:
      operationId: createSavedSearch
      summary: Create a saved search
      description: >-
        Creates a new saved search query for reuse and sharing with
        other team members.
      tags:
        - Saved Searches
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SavedSearch'
      responses:
        '200':
          description: Saved search created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedSearch'
        '400':
          description: Invalid saved search configuration
        '401':
          description: Unauthorized
  /search/saved/{id}:
    get:
      operationId: getSavedSearch
      summary: Get a saved search by ID
      description: >-
        Retrieves the configuration of a specific saved search query.
      tags:
        - Saved Searches
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Successfully retrieved saved search
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedSearch'
        '401':
          description: Unauthorized
        '404':
          description: Saved search not found
    patch:
      operationId: updateSavedSearch
      summary: Update a saved search
      description: >-
        Updates the configuration of an existing saved search query.
      tags:
        - Saved Searches
      parameters:
        - $ref: '#/components/parameters/resourceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SavedSearch'
      responses:
        '200':
          description: Saved search updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SavedSearch'
        '400':
          description: Invalid saved search configuration
        '401':
          description: Unauthorized
        '404':
          description: Saved search not found
    delete:
      operationId: deleteSavedSearch
      summary: Delete a saved search
      description: >-
        Deletes a saved search by its unique ID.
      tags:
        - Saved Searches
      parameters:
        - $ref: '#/components/parameters/resourceId'
      responses:
        '200':
          description: Saved search deleted successfully
        '401':
          description: Unauthorized
        '404':
          description: Saved search not found
  /notifications:
    get:
      operationId: listSearchNotifications
      summary: List search notification rules
      description: >-
        Retrieves all configured notification rules for triggering
        alerts based on search results and data patterns.
      tags:
        - Search Notifications
      responses:
        '200':
          description: Successfully retrieved notification rules
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Notification'
                  count:
                    type: integer
                    description: Total number of notification rules
        '401':
          description: Unauthorized
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Bearer token obtained via OAuth 2.0 client credentials grant
        (Cribl Cloud) or the /auth/login endpoint (on-premises).
  parameters:
    resourceId:
      name: id
      in: path
      required: true
      description: The unique identifier of the resource
      schema:
        type: string
  schemas:
    SearchJobRequest:
      type: object
      required:
        - query
      properties:
        query:
          type: string
          description: >-
            The search query in Cribl Search query language
        dataset:
          type: string
          description: The dataset to search against
        earliest:
          type: string
          description: >-
            The earliest time for the search range in relative or
            absolute format
        latest:
          type: string
          description: >-
            The latest time for the search range in relative or
            absolute format
        timezone:
          type: string
          description: The timezone for time range interpretation
    SearchJob:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the search job
        query:
          type: string
          description: The search query that was executed
        status:
          type: string
          description: The current job status
          enum:
            - running
            - completed
            - failed
            - cancelled
        dataset:
          type: string
          description: The dataset being searched
        startTime:
          type: integer
          description: Job start time as a Unix timestamp
        endTime:
          type: integer
          description: Job end time as a Unix timestamp
        numResults:
          type: integer
          description: Number of results found
        numScanned:
          type: integer
          description: Number of events scanned
        error:
          type: string
          description: Error message if the job failed
    SearchDataset:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the search dataset
        name:
          type: string
          description: Display name of the dataset
        description:
          type: string
          description: A human-readable description
        type:
          type: string
          description: The data source type
          enum:
            - cribl_lake
            - splunk
            - s3
            - elasticsearch
            - datadog
        connectionConfig:
          type: object
          description: >-
            Connection configuration specific to the data source type
          properties:
            host:
              type: string
              description: The data source host address
            port:
              type: integer
              description: The data source port
            index:
              type: string
              description: The index or bucket to search
    SavedSearch:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the saved search
        name:
          type: string
          description: Display name of the saved search
        description:
          type: string
          description: A human-readable description
        query:
          type: string
          description: The search query
        dataset:
          type: string
          description: The default dataset
        earliest:
          type: string
          description: Default earliest time range
        latest:
          type: string
          description: Default latest time range
        owner:
          type: string
          description: The owner of the saved search
    Notification:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the notification rule
        type:
          type: string
          description: The notification type
        targets:
          type: array
          description: List of notification targets
          items:
            type: object
            properties:
              type:
                type: string
                description: Target type such as webhook or pagerduty
              url:
                type: string
                description: The target webhook URL
        description:
          type: string
          description: A human-readable description