Amazon Clean Rooms Protected Queries API

openapi: 3.1.0
info:
  title: Amazon Clean Rooms Collaborations Protected Queries API
  description: Amazon Clean Rooms enables organizations to collaborate and analyze shared datasets without exposing underlying raw data to partners. Create secure data clean rooms and collaborate with any company while maintaining data privacy through differential privacy, cryptographic computing, and flexible analytics using SQL, PySpark, or ML models.
  version: '2022-02-17'
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/contact-us/
  termsOfService: https://aws.amazon.com/service-terms/
  x-generated-from: documentation
servers:
- url: https://cleanrooms.{region}.amazonaws.com
  description: Amazon Clean Rooms Regional Endpoint
  variables:
    region:
      default: us-east-1
      description: AWS Region
security:
- aws_signature: []
tags:
- name: Protected Queries
  description: Operations for executing and managing protected queries
paths:
  /memberships/{membershipIdentifier}/protectedQueries:
    get:
      operationId: ListProtectedQueries
      summary: Amazon Clean Rooms List Protected Queries
      description: Lists protected queries, sorted by the most recent query.
      tags:
      - Protected Queries
      parameters:
      - name: membershipIdentifier
        in: path
        required: true
        description: The identifier for a membership resource.
        schema:
          type: string
      - name: nextToken
        in: query
        description: The token value retrieved from a previous paginated request.
        schema:
          type: string
      - name: maxResults
        in: query
        description: The maximum number of protected queries to return.
        schema:
          type: integer
          minimum: 1
          maximum: 100
      - name: status
        in: query
        description: A filter for the status of the protected query.
        schema:
          type: string
          enum:
          - SUBMITTED
          - STARTED
          - CANCELLED
          - CANCELLING
          - FAILED
          - SUCCESS
          - TIMED_OUT
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListProtectedQueriesResponse'
              examples:
                ListProtectedQueries200Example:
                  summary: Default ListProtectedQueries 200 response
                  x-microcks-default: true
                  value:
                    protectedQueries:
                    - id: query-abc12345
                      membershipId: member-abc12345
                      membershipArn: arn:aws:cleanrooms:us-east-1:123456789012:membership/member-abc12345
                      createTime: '2025-03-15T14:30:00Z'
                      status: SUCCESS
                      receiverConfigurations: []
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: StartProtectedQuery
      summary: Amazon Clean Rooms Start a Protected Query
      description: Creates a protected query that is started by AWS Clean Rooms. A protected query enables analysis on configured tables without exposing underlying raw data.
      tags:
      - Protected Queries
      parameters:
      - name: membershipIdentifier
        in: path
        required: true
        description: A unique identifier for the membership to run the protected query.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartProtectedQueryRequest'
            examples:
              StartProtectedQueryRequestExample:
                summary: Default StartProtectedQuery request
                x-microcks-default: true
                value:
                  type: SQL
                  sqlParameters:
                    queryString: SELECT COUNT(*) as count FROM table1
                  resultConfiguration:
                    outputConfiguration:
                      s3:
                        bucket: my-results-bucket
                        keyPrefix: clean-rooms-results/
                        resultFormat: CSV
      responses:
        '200':
          description: Protected query started
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartProtectedQueryResponse'
              examples:
                StartProtectedQuery200Example:
                  summary: Default StartProtectedQuery 200 response
                  x-microcks-default: true
                  value:
                    protectedQuery:
                      id: query-abc12345
                      membershipId: member-abc12345
                      status: SUBMITTED
                      createTime: '2025-03-15T14:30:00Z'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    StartProtectedQueryResponse:
      type: object
      description: Response for starting a protected query.
      properties:
        protectedQuery:
          $ref: '#/components/schemas/ProtectedQuery'
    AccessDeniedException:
      type: object
      description: Caller does not have sufficient access to perform this action.
      properties:
        message:
          type: string
    ListProtectedQueriesResponse:
      type: object
      description: Response for listing protected queries.
      properties:
        nextToken:
          type: string
          description: The token value retrieved from a previous paginated request.
        protectedQueries:
          type: array
          items:
            $ref: '#/components/schemas/ProtectedQuery'
          description: The list of protected queries.
    ValidationException:
      type: object
      description: The input fails to satisfy the specified constraints.
      properties:
        message:
          type: string
        fieldList:
          type: array
          items:
            type: object
    InternalServerException:
      type: object
      description: Unexpected error during processing of request.
      properties:
        message:
          type: string
    ProtectedQuery:
      type: object
      description: Represents a protected query executed within a Clean Rooms collaboration.
      properties:
        id:
          type: string
          description: The unique ID of the protected query.
          example: query-abc12345
        membershipId:
          type: string
          description: The ID of the membership.
        membershipArn:
          type: string
          description: The ARN of the membership.
        createTime:
          type: string
          format: date-time
          description: The time when the query was created.
        status:
          type: string
          enum:
          - SUBMITTED
          - STARTED
          - CANCELLED
          - CANCELLING
          - FAILED
          - SUCCESS
          - TIMED_OUT
          description: The status of the protected query.
    StartProtectedQueryRequest:
      type: object
      description: Request body for starting a protected query.
      required:
      - type
      - resultConfiguration
      properties:
        type:
          type: string
          enum:
          - SQL
          description: The type of the protected query.
        sqlParameters:
          type: object
          description: The parameters for the SQL type protected query.
          properties:
            queryString:
              type: string
              description: The query string to be submitted.
        resultConfiguration:
          type: object
          description: Contains configuration details for protected query results.
  securitySchemes:
    aws_signature:
      type: apiKey
      in: header
      name: Authorization
      description: AWS Signature Version 4
externalDocs:
  description: Amazon Clean Rooms API Reference
  url: https://docs.aws.amazon.com/clean-rooms/latest/apireference/