Amazon IoT SiteWise Iot Sitewise Searches API

openapi: 3.2.0
info:
  title: AWS IoT SiteWise Searches API
  version: '2019-12-02'
  description: Generated from AWS's published Smithy model for AWS IoT SiteWise. 3 operation(s).
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/contact-us/
  license:
    name: Apache 2.0
    identifier: Apache-2.0
    url: https://github.com/aws/api-models-aws/blob/main/LICENSE
servers:
- url: https://iotsitewise.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
tags:
- name: Searches
paths:
  /workspaces/{workspaceName}/searches/{searchId}:
    get:
      operationId: DescribeSearch
      summary: Describe Search
      description: Returns the current status and metadata of a single search, including the query that was submitted, the search type, and — when the search has failed — the reason. Use this to poll a search started with StartSearch until it reaches a terminal status (SUCCEEDED or FAILED).
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DescribeSearchResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalFailureException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalFailureException'
        '400':
          description: InvalidRequestException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DescribeSearchRequest'
      tags:
      - Searches
  /workspaces/{workspaceName}/searches/list:
    post:
      operationId: ListSearches
      summary: List Searches
      description: 'Lists the searches in a workspace, most recently started first. Results can be narrowed with optional filters (status, search type, group, and started-at time range) and are paginated: when nextToken is present, pass it on a subsequent call to retrieve the next page.'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListSearchesResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalFailureException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalFailureException'
        '400':
          description: InvalidRequestException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListSearchesRequest'
      tags:
      - Searches
  /workspaces/{workspaceName}/searches:
    post:
      operationId: StartSearch
      summary: Start Search
      description: 'Starts an asynchronous search over the data in a workspace. The search runs in the background; the response returns immediately with a searchId and an initial status of QUEUED. Use DescribeSearch to poll for completion and GetSearchResults to retrieve the results once the search reaches SUCCEEDED. The request is idempotent on clientToken: repeating a call with the same token returns the original search instead of starting a new one.'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartSearchResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '409':
          description: ConflictingOperationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConflictingOperationException'
        '500':
          description: InternalFailureException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalFailureException'
        '400':
          description: InvalidRequestException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidRequestException'
        '410':
          description: LimitExceededException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LimitExceededException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: ThrottlingException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ThrottlingException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartSearchRequest'
      tags:
      - Searches
components:
  schemas:
    SearchSummary:
      type: object
      properties:
        searchId:
          type: string
          description: The unique identifier of the search.
        workspaceName:
          type: string
          description: The name of the workspace the search runs against.
        status:
          type: string
          enum:
          - QUEUED
          - RUNNING
          - SUCCEEDED
          - FAILED
          description: The current status of the search.
        queryStatement:
          type: string
          description: The natural-language query that was submitted for the search.
        searchType:
          type: string
          enum:
          - DEEP
          - QUICK
          description: The search strategy used for the search.
        statusReason:
          type: string
          description: A human-readable explanation of the current status. Populated when the search has FAILED.
        startedAt:
          type: string
          description: The time at which the search was started.
        groupId:
          type: string
          description: The group identifier associated with the search, if one was supplied on the request.
      required:
      - searchId
      - workspaceName
      - status
      - queryStatement
      - searchType
    ListSearchesFilters:
      type: object
      properties:
        statusFilter:
          type: array
          items:
            type: string
            enum:
            - QUEUED
            - RUNNING
            - SUCCEEDED
            - FAILED
          description: Returns only searches whose status is one of the listed values.
        startedAfter:
          type: string
          description: Returns only searches started at or after this time.
        startedBefore:
          type: string
          description: Returns only searches started at or before this time.
        groupIdFilter:
          type: array
          items:
            type: string
          description: Returns only searches whose groupId is one of the listed values.
        searchTypeFilter:
          type: array
          items:
            type: string
            enum:
            - DEEP
            - QUICK
          description: Returns only searches whose searchType is one of the listed values.
    TimeInNanos:
      type: object
      properties:
        timeInSeconds:
          type: integer
          description: The timestamp date, in seconds, in the Unix epoch format. Fractional nanosecond data is provided by offsetInNanos.
        offsetInNanos:
          type: integer
          description: The nanosecond offset from timeInSeconds.
      required:
      - timeInSeconds
    LimitExceededException:
      type: object
      properties:
        message:
          type: string
      required:
      - message
    SearchFilters:
      type: object
      properties:
        timeSeriesIds:
          type: array
          items:
            type: string
          description: Restricts the search to these time series.
        datasetIds:
          type: array
          items:
            type: string
          description: Restricts the search to these datasets.
        timeIntervals:
          type: array
          items:
            $ref: '#/components/schemas/TimeInterval'
          description: Restricts the search to these time intervals.
    AccessDeniedException:
      type: object
      properties:
        message:
          type: string
    StartSearchRequest:
      type: object
      properties:
        workspaceName:
          type: string
          description: The name of the workspace whose data is searched.
        queryStatement:
          type: string
          description: The natural-language query describing the data to search for.
        clientToken:
          type: string
          description: A unique, case-sensitive identifier you provide to ensure the request is idempotent. Repeating a StartSearch call with the same clientToken returns the original search rather than starting a new one. If omitted, the SDK autogenerates one.
        searchType:
          type: string
          enum:
          - DEEP
          - QUICK
          description: The search strategy to use. Defaults to QUICK when omitted.
        searchFilters:
          $ref: '#/components/schemas/SearchFilters'
        groupId:
          type: string
          description: An optional caller-supplied identifier used to group related searches together.
      required:
      - workspaceName
      - queryStatement
    ListSearchesResponse:
      type: object
      properties:
        searchSummaries:
          type: array
          items:
            $ref: '#/components/schemas/SearchSummary'
          description: A page of search summaries, most recently started first.
        nextToken:
          type: string
          description: The pagination token to use in a subsequent ListSearches call to retrieve the next page. Absent when there are no more searches.
      required:
      - searchSummaries
    ListSearchesRequest:
      type: object
      properties:
        workspaceName:
          type: string
          description: The name of the workspace whose searches are listed.
        maxResults:
          type: integer
          description: The maximum number of searches to return in a single page. Valid range is 1 to 1,000; if omitted, a service-defined default is used.
        nextToken:
          type: string
          description: The pagination token returned by a previous ListSearches call. Provide it to retrieve the next page; omit it to retrieve the first page.
        listSearchesFilters:
          $ref: '#/components/schemas/ListSearchesFilters'
      required:
      - workspaceName
    DescribeSearchRequest:
      type: object
      properties:
        workspaceName:
          type: string
          description: The name of the workspace the search belongs to.
        searchId:
          type: string
          description: The identifier of the search to describe.
      required:
      - workspaceName
      - searchId
    StartSearchResponse:
      type: object
      properties:
        searchId:
          type: string
          description: The unique identifier assigned to the newly started search.
        workspaceName:
          type: string
          description: The name of the workspace the search runs against.
        status:
          type: string
          enum:
          - QUEUED
          - RUNNING
          - SUCCEEDED
          - FAILED
          description: The initial status of the search. A newly started search is QUEUED.
        groupId:
          type: string
          description: The group identifier associated with the search, if one was supplied on the request.
      required:
      - searchId
      - workspaceName
      - status
    ThrottlingException:
      type: object
      properties:
        message:
          type: string
      required:
      - message
    ResourceNotFoundException:
      type: object
      properties:
        message:
          type: string
      required:
      - message
    TimeInterval:
      type: object
      properties:
        startTime:
          $ref: '#/components/schemas/TimeInNanos'
        endTime:
          $ref: '#/components/schemas/TimeInNanos'
      required:
      - startTime
      - endTime
    InternalFailureException:
      type: object
      properties:
        message:
          type: string
      required:
      - message
    InvalidRequestException:
      type: object
      properties:
        message:
          type: string
      required:
      - message
    DescribeSearchResponse:
      type: object
      properties:
        searchId:
          type: string
          description: The unique identifier of the search.
        workspaceName:
          type: string
          description: The name of the workspace the search runs against.
        status:
          type: string
          enum:
          - QUEUED
          - RUNNING
          - SUCCEEDED
          - FAILED
          description: The current status of the search.
        queryStatement:
          type: string
          description: The natural-language query that was submitted for the search.
        searchType:
          type: string
          enum:
          - DEEP
          - QUICK
          description: The search strategy used for the search.
        statusReason:
          type: string
          description: A human-readable explanation of the current status. Populated when the search has FAILED.
        startedAt:
          type: string
          description: The time at which the search was started.
        groupId:
          type: string
          description: The group identifier associated with the search, if one was supplied on the request.
      required:
      - searchId
      - workspaceName
      - status
      - queryStatement
      - searchType
    ConflictingOperationException:
      type: object
      properties:
        message:
          type: string
        resourceId:
          type: string
          description: The ID of the resource that conflicts with this operation.
        resourceArn:
          type: string
          description: The ARN of the resource that conflicts with this operation.
      required:
      - message
      - resourceId
      - resourceArn
  securitySchemes:
    sigv4:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4. The Authorization header carries an AWS4-HMAC-SHA256 signature over the canonical request, with X-Amz-Date (and X-Amz-Security-Token for temporary credentials). Not a bearer token.
      x-aws-sigv4:
        signingName: iotsitewise
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/582e55931c45b944739742a2c1620b6026dd2d13/models/iotsitewise/service/2019-12-02/iotsitewise-2019-12-02.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)