Amazon IoT SiteWise Iot Sitewise Enrichment Jobs API

openapi: 3.2.0
info:
  title: AWS IoT SiteWise Enrichment Jobs 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: Enrichment Jobs
paths:
  /workspaces/{workspaceName}/enrichment-jobs:
    post:
      operationId: CreateEnrichmentJob
      summary: Create Enrichment Job
      description: 'Creates an asynchronous enrichment job to analyze time-series sensor data. The operation returns immediately with job details while processing continues in the background. Idempotency Include a clientToken to make the operation idempotent. If you submit the same request with the same token within the idempotency window, you receive the original job details without creating a duplicate. Prerequisites Before creating a job, ensure: The workspace is in ACTIVE state (not being deleted) You have IAM permissions for the workspace, dataset, and time-series resources You have KMS Decrypt permission on the workspace''s customer-managed encryption key No duplicate job (same workspace, dataset, property, and job type) is currently running Workflow Submit the job with configuration specifying which video data to analyze and the time range Capture the jobId from the response Use DescribeEnrichmentJob to monitor progress and check job status When status reaches a terminal state (COMPLETED, FAILED, TIMED_OUT, CANCELLED), check results For COMPLETED jobs, query IoT SiteWise for semantic search on video events Error Handling ConflictingOperationException: A duplicate job is already running for the s'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateEnrichmentJobResponse'
        '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/CreateEnrichmentJobRequest'
      tags:
      - Enrichment Jobs
    get:
      operationId: ListEnrichmentJobs
      summary: List Enrichment Jobs
      description: 'Lists enrichment jobs within a workspace with optional filtering and pagination. Results are ordered by createdAt timestamp descending (newest first). Filtering Combine filters to narrow results: datasetId: Filter by dataset propertyAlias OR timeSeriesId: Filter by time series (specify one, not both) status: Filter by job status (e.g., RUNNING to find active jobs) jobType: Filter by enrichment type (currently only EVENT_DETECTION) startDate and endDate: Filter by job creation time range Important Constraints You must specify either propertyAlias OR timeSeriesId, but not both Attempting to specify both results in an InvalidRequestException Date filters use ISO 8601 format startDate is exclusive, endDate is inclusive Pagination The operation returns up to maxResults jobs per page (default 50). If more results exist, the response includes a nextToken. Submit this token in a subsequent request to retrieve the next page. Common Use Cases Find all running jobs: Filter by status=RUNNING List recent jobs for a dataset: Filter by datasetId with optional date range Monitor jobs for a specific sensor: Filter by propertyAlias or timeSeriesId Track all event detection jobs: Filter by jobType=EV'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListEnrichmentJobsResponse'
        '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/ListEnrichmentJobsRequest'
      tags:
      - Enrichment Jobs
  /workspaces/{workspaceName}/enrichment-jobs/{jobId}:
    get:
      operationId: DescribeEnrichmentJob
      summary: Describe Enrichment Job
      description: 'Retrieves detailed information about a specific enrichment job, including its current status, configuration, and timestamps. Use Cases Monitor job progress by checking status updates with DescribeEnrichmentJob Retrieve the complete job configuration submitted during creation Debug failed jobs by examining the failureMessage field Track job lifecycle with creation, update, completion, and cancellation timestamps Status Monitoring Jobs progress through statuses: PENDING → RUNNING → terminal state Terminal states: COMPLETED: Job finished successfully; query IoT SiteWise for semantic search results FAILED: Job encountered an error; check failureMessage for details TIMED_OUT: Job exceeded maximum processing time CANCELLED: Job was cancelled via CancelEnrichmentJob Response Fields The response includes: Current job status and type Full job configuration as originally submitted Lifecycle timestamps (created, updated, completed, cancelled) Failure details if status is FAILED'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DescribeEnrichmentJobResponse'
        '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/DescribeEnrichmentJobRequest'
      tags:
      - Enrichment Jobs
components:
  schemas:
    CreateEnrichmentJobResponse:
      type: object
      properties:
        jobId:
          type: string
          description: Unique identifier for the enrichment job. Use this ID with DescribeEnrichmentJob to monitor progress or with CancelEnrichmentJob to cancel the job.
        status:
          type: string
          enum:
          - PENDING
          - RUNNING
          - COMPLETED
          - FAILED
          - TIMED_OUT
          - CANCELLED
          description: Initial status of the enrichment job, typically PENDING. The job will transition to RUNNING when processing begins, then to a terminal state (COMPLETED, FAILED, TIMED_OUT, or CANCELLED). Use DescribeEnrichmentJob to track status changes.
        createdAt:
          type: string
          description: Timestamp when the enrichment job was created in ISO 8601 format.
      required:
      - jobId
      - status
      - createdAt
    ListEnrichmentJobsResponse:
      type: object
      properties:
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/EnrichmentJobSummary'
          description: Array of job summaries matching the filter criteria, ordered by creation time descending (newest first). Each summary includes key identifiers (jobId, datasetId, propertyAlias/timeSeriesId) and status information without the full job configuration. Use DescribeEnrichmentJob to retrieve complete details.
        nextToken:
          type: string
          description: Pagination token to retrieve the next page of results. If present, more jobs exist that match the filter criteria. Include this token in a subsequent ListEnrichmentJobs request to retrieve the next page. If absent, you have retrieved all matching jobs.
      required:
      - jobs
    EnrichmentTrimSettings:
      type: object
      properties:
        startTime:
          $ref: '#/components/schemas/TimeInNanos'
        endTime:
          $ref: '#/components/schemas/TimeInNanos'
      required:
      - startTime
      - endTime
    ListEnrichmentJobsRequest:
      type: object
      properties:
        workspaceName:
          type: string
          description: The name of the IoT SiteWise workspace to list enrichment jobs from.
        datasetId:
          type: string
          description: Filter jobs by dataset ID. Returns only jobs analyzing data from the specified dataset.
        propertyAlias:
          type: string
          description: Filter by property alias (human-readable sensor name). Specify either propertyAlias or timeSeriesId, but not both. Returns only jobs analyzing the specified property alias.
        timeSeriesId:
          type: string
          description: Filter by time series ID (system identifier). Specify either timeSeriesId or propertyAlias, but not both. Returns only jobs analyzing the specified time series.
        status:
          type: string
          enum:
          - PENDING
          - RUNNING
          - COMPLETED
          - FAILED
          - TIMED_OUT
          - CANCELLED
          description: Filter by job status. Returns only jobs in the specified status. Use RUNNING to find active jobs, or FAILED to identify jobs requiring attention.
        jobType:
          type: string
          enum:
          - EVENT_DETECTION
          description: Filter by enrichment job type. Currently only EVENT_DETECTION is supported. Use this filter to future-proof queries when additional job types are added.
        startDate:
          type: string
          description: The exclusive start of the date range for filtering jobs by creation time. Jobs created after this timestamp are included. Use ISO 8601 format (e.g., 2024-01-01T00:00:00Z).
        endDate:
          type: string
          description: The inclusive end of the date range for filtering jobs by creation time. Jobs created on or before this timestamp are included. Use ISO 8601 format (e.g., 2024-01-31T23:59:59Z).
        maxResults:
          type: integer
          description: Maximum number of jobs to return per page. Defaults to 50 if not specified. Use smaller values for faster responses, larger values to reduce API calls.
        nextToken:
          type: string
          description: Pagination token from a previous ListEnrichmentJobs response. Include this token to retrieve the next page of results. Omit for the first request.
      required:
      - workspaceName
    LimitExceededException:
      type: object
      properties:
        message:
          type: string
      required:
      - message
    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
    AccessDeniedException:
      type: object
      properties:
        message:
          type: string
    InvalidRequestException:
      type: object
      properties:
        message:
          type: string
      required:
      - message
    CreateEnrichmentJobRequest:
      type: object
      properties:
        workspaceName:
          type: string
          description: The name of the IoT SiteWise workspace containing the video data to analyze.
        jobConfiguration:
          $ref: '#/components/schemas/EnrichmentJobConfiguration'
        clientToken:
          type: string
          description: Optional unique token that makes the operation idempotent. If you submit the same request with the same token within the idempotency window, the service returns the original job without creating a duplicate. Use a UUID or timestamp-based token for each unique request.
      required:
      - workspaceName
      - jobConfiguration
    EnrichmentJobSummary:
      type: object
      properties:
        jobId:
          type: string
          description: Unique identifier for the enrichment job.
        status:
          type: string
          enum:
          - PENDING
          - RUNNING
          - COMPLETED
          - FAILED
          - TIMED_OUT
          - CANCELLED
          description: 'Current status of the job: PENDING, RUNNING, COMPLETED, FAILED, TIMED_OUT, or CANCELLED. Use this to quickly identify active jobs or jobs requiring attention.'
        workspaceName:
          type: string
          description: The name of the IoT SiteWise workspace containing this job.
        jobType:
          type: string
          enum:
          - EVENT_DETECTION
          description: The type of enrichment job. Currently EVENT_DETECTION is the only supported type.
        datasetId:
          type: string
          description: The dataset being enriched. Useful for filtering and identifying jobs without fetching the full configuration. This allows you to quickly find all jobs related to a specific dataset.
        propertyAlias:
          type: string
          description: The property alias (human-readable sensor name) of the time series being enriched. Present when the job was created using a propertyAlias. Use this to identify which sensor the job analyzes.
        timeSeriesId:
          type: string
          description: The system identifier of the time series being enriched. Present when the job was created using a timeSeriesId. Use this to identify which time series the job analyzes.
        createdAt:
          type: string
          description: Timestamp when the job was created in ISO 8601 format.
        updatedAt:
          type: string
          description: Timestamp of the last job status change in ISO 8601 format. Use this to track recent activity and identify stale jobs. For active jobs, this shows the last time the job transitioned to a new status.
      required:
      - jobId
      - status
      - workspaceName
      - jobType
      - datasetId
      - createdAt
    DescribeEnrichmentJobRequest:
      type: object
      properties:
        workspaceName:
          type: string
          description: The name of the IoT SiteWise workspace containing the enrichment job.
        jobId:
          type: string
          description: The unique identifier of the enrichment job to retrieve. This is the jobId returned by CreateEnrichmentJob.
      required:
      - workspaceName
      - jobId
    ThrottlingException:
      type: object
      properties:
        message:
          type: string
      required:
      - message
    ResourceNotFoundException:
      type: object
      properties:
        message:
          type: string
      required:
      - message
    DescribeEnrichmentJobResponse:
      type: object
      properties:
        jobId:
          type: string
          description: The unique identifier of the enrichment job.
        status:
          type: string
          enum:
          - PENDING
          - RUNNING
          - COMPLETED
          - FAILED
          - TIMED_OUT
          - CANCELLED
          description: 'Current status of the enrichment job. Possible values: PENDING: Job is waiting to start processing RUNNING: Job is actively processing video data COMPLETED: Job finished successfully; embeddings available in IoT SiteWise FAILED: Job encountered an error; see failureMessage for details TIMED_OUT: Job exceeded maximum processing time limit CANCELLED: Job was cancelled by user request'
        workspaceName:
          type: string
          description: The name of the IoT SiteWise workspace containing the job.
        jobType:
          type: string
          enum:
          - EVENT_DETECTION
          description: The type of enrichment job, derived from the job configuration. Currently EVENT_DETECTION is the only supported type.
        jobConfiguration:
          $ref: '#/components/schemas/EnrichmentJobConfiguration'
        createdAt:
          type: string
          description: Timestamp when the enrichment job was created in ISO 8601 format.
        updatedAt:
          type: string
          description: Timestamp when the job status was last updated in ISO 8601 format. Useful for tracking recent activity.
        completedAt:
          type: string
          description: Timestamp when the job completed successfully in ISO 8601 format. Only present if status is COMPLETED.
        cancelledAt:
          type: string
          description: Timestamp when the job was cancelled in ISO 8601 format. Only present if status is CANCELLED.
        failureMessage:
          type: string
          description: Human-readable error message explaining why the job failed. Only present if status is FAILED. Use this information to diagnose configuration issues, permission problems, or data processing errors.
      required:
      - jobId
      - status
      - workspaceName
      - jobType
      - jobConfiguration
      - createdAt
    InternalFailureException:
      type: object
      properties:
        message:
          type: string
      required:
      - message
    EventDetection:
      type: object
      properties:
        datasetId:
          type: string
          description: The IoT SiteWise dataset ID containing the video time-series data to analyze. Query IoT SiteWise to discover available datasets in your workspace.
        timeSeriesId:
          type: string
          description: Unique system identifier for the video time series to analyze. Specify either timeSeriesId or propertyAlias, but not both. Use this when you have the system-generated time series identifier from IoT SiteWise.
        propertyAlias:
          type: string
          description: Human-readable alias for the video time series to analyze (e.g., /camera/warehouse/zone-a). Specify either propertyAlias or timeSeriesId, but not both. Use this when you have configured friendly aliases in IoT SiteWise for better readability.
        trimSettings:
          $ref: '#/components/schemas/EnrichmentTrimSettings'
      required:
      - datasetId
      - trimSettings
    EnrichmentJobConfiguration:
      type: object
      properties:
        eventDetection:
          $ref: '#/components/schemas/EventDetection'
      description: Exactly one member is set.
    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)