Amazon CloudTrail API

openapi: 3.1.0
info:
  title: Amazon CloudTrail API
  description: >-
    AWS CloudTrail is a service that enables governance, compliance, operational
    auditing, and risk auditing of your AWS account. With CloudTrail, you can log,
    continuously monitor, and retain account activity related to actions across
    your AWS infrastructure.
  version: '2013-11-01'
  contact:
    name: Amazon Web Services
    url: https://aws.amazon.com/contact-us/
  termsOfService: https://aws.amazon.com/service-terms/
externalDocs:
  description: Amazon CloudTrail API Reference
  url: https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/
servers:
  - url: https://cloudtrail.{region}.amazonaws.com
    description: Amazon CloudTrail Regional Endpoint
    variables:
      region:
        default: us-east-1
        description: AWS Region
tags:
  - name: Event Data Stores
    description: Operations for managing CloudTrail Lake event data stores
  - name: Events
    description: Operations for looking up and querying events
  - name: Trails
    description: Operations for creating and managing CloudTrail trails
paths:
  /trails:
    post:
      operationId: CreateTrail
      summary: Amazon CloudTrail Create a trail
      description: >-
        Creates a trail that specifies the settings for delivery of log data to
        an Amazon S3 bucket.
      tags:
        - Trails
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTrailRequest'
      responses:
        '200':
          description: Trail created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTrailResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidTrailNameException'
        '409':
          description: Trail already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrailAlreadyExistsException'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationNotPermittedException'
    get:
      operationId: DescribeTrails
      summary: Amazon CloudTrail Describe trails
      description: >-
        Retrieves settings for one or more trails associated with the current
        region for your account.
      tags:
        - Trails
      parameters:
        - name: trailNameList
          in: query
          description: List of trail names or ARNs.
          schema:
            type: array
            items:
              type: string
        - name: includeShadowTrails
          in: query
          description: Whether to include shadow trails.
          schema:
            type: boolean
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DescribeTrailsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidTrailNameException'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationNotPermittedException'

  /trails/{trailName}:
    delete:
      operationId: DeleteTrail
      summary: Amazon CloudTrail Delete a trail
      description: >-
        Deletes a trail. This operation must be called from the region in which
        the trail was created.
      tags:
        - Trails
      parameters:
        - name: trailName
          in: path
          required: true
          description: The name or ARN of the trail.
          schema:
            type: string
      responses:
        '200':
          description: Trail deleted
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidTrailNameException'
        '404':
          description: Trail not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TrailNotFoundException'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationNotPermittedException'

  /events/lookup:
    post:
      operationId: LookupEvents
      summary: Amazon CloudTrail Look up events
      description: >-
        Looks up management events or CloudTrail Insights events captured by
        CloudTrail. You can look up events that occurred in a region within
        the last 90 days.
      tags:
        - Events
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LookupEventsRequest'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupEventsResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidLookupAttributesException'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationNotPermittedException'

  /event-data-stores:
    post:
      operationId: CreateEventDataStore
      summary: Amazon CloudTrail Create an event data store
      description: >-
        Creates a new event data store for CloudTrail Lake, which lets you
        run SQL-based queries on your CloudTrail events.
      tags:
        - Event Data Stores
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEventDataStoreRequest'
      responses:
        '200':
          description: Event data store created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateEventDataStoreResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidParameterException'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationNotPermittedException'
    get:
      operationId: ListEventDataStores
      summary: Amazon CloudTrail List event data stores
      description: >-
        Returns information about all event data stores in the account.
      tags:
        - Event Data Stores
      parameters:
        - name: maxResults
          in: query
          description: Maximum number of results to return.
          schema:
            type: integer
            minimum: 1
            maximum: 25
        - name: nextToken
          in: query
          description: Token for pagination.
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListEventDataStoresResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvalidParameterException'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationNotPermittedException'

components:
  schemas:
    CreateTrailRequest:
      type: object
      required:
        - Name
        - S3BucketName
      properties:
        Name:
          type: string
          description: The name of the trail.
        S3BucketName:
          type: string
          description: The name of the S3 bucket for log file delivery.
        S3KeyPrefix:
          type: string
          description: The S3 key prefix for log file delivery.
        IsMultiRegionTrail:
          type: boolean
          description: Whether the trail is created in all regions.
        EnableLogFileValidation:
          type: boolean
          description: Whether log file integrity validation is enabled.
        CloudWatchLogsLogGroupArn:
          type: string
          description: The ARN of the CloudWatch Logs log group.
        CloudWatchLogsRoleArn:
          type: string
          description: The role ARN for CloudWatch Logs delivery.

    CreateTrailResponse:
      type: object
      properties:
        Name:
          type: string
        S3BucketName:
          type: string
        TrailARN:
          type: string
        IsMultiRegionTrail:
          type: boolean
        LogFileValidationEnabled:
          type: boolean

    DescribeTrailsResponse:
      type: object
      properties:
        trailList:
          type: array
          items:
            type: object
            properties:
              Name:
                type: string
              S3BucketName:
                type: string
              TrailARN:
                type: string
              HomeRegion:
                type: string
              IsMultiRegionTrail:
                type: boolean
              LogFileValidationEnabled:
                type: boolean
              HasCustomEventSelectors:
                type: boolean

    LookupEventsRequest:
      type: object
      properties:
        LookupAttributes:
          type: array
          items:
            type: object
            properties:
              AttributeKey:
                type: string
                enum:
                  - EventId
                  - EventName
                  - ReadOnly
                  - Username
                  - ResourceType
                  - ResourceName
                  - EventSource
                  - AccessKeyId
              AttributeValue:
                type: string
        StartTime:
          type: string
          format: date-time
        EndTime:
          type: string
          format: date-time
        MaxResults:
          type: integer
        NextToken:
          type: string

    LookupEventsResponse:
      type: object
      properties:
        Events:
          type: array
          items:
            type: object
            properties:
              EventId:
                type: string
              EventName:
                type: string
              EventTime:
                type: string
                format: date-time
              EventSource:
                type: string
              Username:
                type: string
              CloudTrailEvent:
                type: string
              ReadOnly:
                type: string
        NextToken:
          type: string

    CreateEventDataStoreRequest:
      type: object
      required:
        - Name
      properties:
        Name:
          type: string
          description: The name of the event data store.
        RetentionPeriod:
          type: integer
          description: Retention period in days.
        MultiRegionEnabled:
          type: boolean

    CreateEventDataStoreResponse:
      type: object
      properties:
        EventDataStoreArn:
          type: string
        Name:
          type: string
        Status:
          type: string
        RetentionPeriod:
          type: integer
        CreatedTimestamp:
          type: string
          format: date-time

    ListEventDataStoresResponse:
      type: object
      properties:
        EventDataStores:
          type: array
          items:
            type: object
            properties:
              EventDataStoreArn:
                type: string
              Name:
                type: string
              Status:
                type: string
              RetentionPeriod:
                type: integer
        NextToken:
          type: string

    InvalidTrailNameException:
      type: object
      properties:
        message:
          type: string

    TrailAlreadyExistsException:
      type: object
      properties:
        message:
          type: string

    TrailNotFoundException:
      type: object
      properties:
        message:
          type: string

    InvalidLookupAttributesException:
      type: object
      properties:
        message:
          type: string

    InvalidParameterException:
      type: object
      properties:
        message:
          type: string

    OperationNotPermittedException:
      type: object
      properties:
        message:
          type: string