Amazon Detective API

openapi: 3.1.0
info:
  title: Amazon Detective
  description: >-
    Amazon Detective makes it easy to analyze, investigate, and quickly identify
    the root cause of potential security issues or suspicious activities. It
    automatically collects log data from AWS resources and uses machine learning,
    statistical analysis, and graph theory to build interactive visualizations
    that help you conduct faster and more efficient security investigations.
  version: '2018-10-26'
  contact:
    name: AWS Support
    url: https://aws.amazon.com/premiumsupport/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  termsOfService: https://aws.amazon.com/service-terms/
  x-logo:
    url: https://a0.awsstatic.com/libra-css/images/logos/aws_logo_smile_1200x630.png
  x-generated-from: documentation
externalDocs:
  description: Amazon Detective API Reference
  url: https://docs.aws.amazon.com/detective/latest/APIReference/Welcome.html
servers:
  - url: https://api.detective.{region}.amazonaws.com
    description: Amazon Detective regional endpoint
    variables:
      region:
        default: us-east-1
        description: AWS region
        enum:
          - us-east-1
          - us-east-2
          - us-west-1
          - us-west-2
          - eu-west-1
          - eu-west-2
          - eu-central-1
          - ap-northeast-1
          - ap-southeast-1
          - ap-southeast-2
          - ap-south-1
          - sa-east-1
security:
  - sigv4: []
tags:
  - name: Graph
    description: Behavior graph management operations
  - name: Members
    description: Member account management operations
  - name: Invitations
    description: Invitation management for member accounts
  - name: Datasources
    description: Data source package management operations
  - name: Investigations
    description: Security investigation operations
  - name: Organizations
    description: AWS Organizations integration operations
  - name: Tags
    description: Resource tagging operations
paths:
  /graph:
    post:
      summary: Amazon Detective Create Graph
      description: Creates a new behavior graph for the calling account and sets it as the administrator account.
      operationId: createGraph
      tags:
        - Graph
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateGraphRequest'
            examples:
              CreateGraphRequestExample:
                summary: Default createGraph request
                x-microcks-default: true
                value:
                  Tags:
                    Environment: production
      responses:
        '200':
          description: Successfully created behavior graph
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateGraphResponse'
              examples:
                CreateGraph200Example:
                  summary: Default createGraph 200 response
                  x-microcks-default: true
                  value:
                    GraphArn: arn:aws:detective:us-east-1:123456789012:graph:abc123def456
        '400':
          description: Bad request - validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict - behavior graph already enabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      summary: Amazon Detective Delete Graph
      description: Disables Amazon Detective and queues the behavior graph for deletion. This operation requires the behavior graph ARN in the request.
      operationId: deleteGraph
      tags:
        - Graph
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteGraphRequest'
            examples:
              DeleteGraphRequestExample:
                summary: Default deleteGraph request
                x-microcks-default: true
                value:
                  GraphArn: arn:aws:detective:us-east-1:123456789012:graph:abc123def456
      responses:
        '200':
          description: Successfully deleted behavior graph
        '400':
          description: Bad request - validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /graphs/list:
    post:
      summary: Amazon Detective List Graphs
      description: Returns the list of behavior graphs that the calling account is an administrator account of. This operation can only be called by a Detective administrator account.
      operationId: listGraphs
      tags:
        - Graph
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListGraphsRequest'
            examples:
              ListGraphsRequestExample:
                summary: Default listGraphs request
                x-microcks-default: true
                value:
                  MaxResults: 100
      responses:
        '200':
          description: Successfully listed behavior graphs
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListGraphsResponse'
              examples:
                ListGraphs200Example:
                  summary: Default listGraphs 200 response
                  x-microcks-default: true
                  value:
                    GraphList:
                      - Arn: arn:aws:detective:us-east-1:123456789012:graph:abc123def456
                        CreatedTime: '2025-01-15T10:00:00Z'
                    NextToken: null
        '400':
          description: Bad request - validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /graph/members:
    post:
      summary: Amazon Detective Create Members
      description: Sends a request to invite the specified AWS accounts to be member accounts in the behavior graph. This operation can only be called by the administrator account.
      operationId: createMembers
      tags:
        - Members
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateMembersRequest'
            examples:
              CreateMembersRequestExample:
                summary: Default createMembers request
                x-microcks-default: true
                value:
                  GraphArn: arn:aws:detective:us-east-1:123456789012:graph:abc123def456
                  Message: You are invited to join the security behavior graph.
                  Accounts:
                    - AccountId: '234567890123'
                      EmailAddress: [email protected]
      responses:
        '200':
          description: Successfully invited member accounts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateMembersResponse'
              examples:
                CreateMembers200Example:
                  summary: Default createMembers 200 response
                  x-microcks-default: true
                  value:
                    Members:
                      - AccountId: '234567890123'
                        EmailAddress: [email protected]
                        GraphArn: arn:aws:detective:us-east-1:123456789012:graph:abc123def456
                        Status: INVITED
                    UnprocessedAccounts: []
        '400':
          description: Bad request - validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /graph/members/removal:
    post:
      summary: Amazon Detective Delete Members
      description: Removes the specified member accounts from the behavior graph. The removed accounts no longer contribute data to the behavior graph.
      operationId: deleteMembers
      tags:
        - Members
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteMembersRequest'
            examples:
              DeleteMembersRequestExample:
                summary: Default deleteMembers request
                x-microcks-default: true
                value:
                  GraphArn: arn:aws:detective:us-east-1:123456789012:graph:abc123def456
                  AccountIds:
                    - '234567890123'
      responses:
        '200':
          description: Successfully removed member accounts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DeleteMembersResponse'
              examples:
                DeleteMembers200Example:
                  summary: Default deleteMembers 200 response
                  x-microcks-default: true
                  value:
                    AccountIds:
                      - '234567890123'
                    UnprocessedAccounts: []
        '400':
          description: Bad request - validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /graph/members/get:
    post:
      summary: Amazon Detective Get Members
      description: Returns the membership details for specified member accounts for a behavior graph.
      operationId: getMembers
      tags:
        - Members
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetMembersRequest'
            examples:
              GetMembersRequestExample:
                summary: Default getMembers request
                x-microcks-default: true
                value:
                  GraphArn: arn:aws:detective:us-east-1:123456789012:graph:abc123def456
                  AccountIds:
                    - '234567890123'
      responses:
        '200':
          description: Successfully retrieved member details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetMembersResponse'
              examples:
                GetMembers200Example:
                  summary: Default getMembers 200 response
                  x-microcks-default: true
                  value:
                    MemberDetails:
                      - AccountId: '234567890123'
                        EmailAddress: [email protected]
                        GraphArn: arn:aws:detective:us-east-1:123456789012:graph:abc123def456
                        AdministratorId: '123456789012'
                        Status: ENABLED
                        InvitedTime: '2025-01-15T10:00:00Z'
                        UpdatedTime: '2025-01-16T12:00:00Z'
                    UnprocessedAccounts: []
        '400':
          description: Bad request - validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /graph/members/list:
    post:
      summary: Amazon Detective List Members
      description: Retrieves the list of member accounts for a behavior graph. Does not return member accounts that were removed.
      operationId: listMembers
      tags:
        - Members
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListMembersRequest'
            examples:
              ListMembersRequestExample:
                summary: Default listMembers request
                x-microcks-default: true
                value:
                  GraphArn: arn:aws:detective:us-east-1:123456789012:graph:abc123def456
                  MaxResults: 100
      responses:
        '200':
          description: Successfully listed members
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListMembersResponse'
              examples:
                ListMembers200Example:
                  summary: Default listMembers 200 response
                  x-microcks-default: true
                  value:
                    MemberDetails:
                      - AccountId: '234567890123'
                        EmailAddress: [email protected]
                        GraphArn: arn:aws:detective:us-east-1:123456789012:graph:abc123def456
                        Status: ENABLED
                    NextToken: null
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /graph/members/monitoringEnable:
    post:
      summary: Amazon Detective Start Monitoring Member
      description: Sends a request to enable data ingest for a member account that has a status of ACCEPTED_BUT_DISABLED.
      operationId: startMonitoringMember
      tags:
        - Members
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartMonitoringMemberRequest'
            examples:
              StartMonitoringMemberRequestExample:
                summary: Default startMonitoringMember request
                x-microcks-default: true
                value:
                  GraphArn: arn:aws:detective:us-east-1:123456789012:graph:abc123def456
                  AccountId: '234567890123'
      responses:
        '200':
          description: Successfully started monitoring member
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /invitation:
    put:
      summary: Amazon Detective Accept Invitation
      description: Accepts an invitation for the member account to contribute data to a behavior graph.
      operationId: acceptInvitation
      tags:
        - Invitations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcceptInvitationRequest'
            examples:
              AcceptInvitationRequestExample:
                summary: Default acceptInvitation request
                x-microcks-default: true
                value:
                  GraphArn: arn:aws:detective:us-east-1:123456789012:graph:abc123def456
      responses:
        '200':
          description: Successfully accepted invitation
        '400':
          description: Bad request - validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Access denied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /invitation/removal:
    put:
      summary: Amazon Detective Reject Invitation
      description: Rejects an invitation to contribute the account data to a behavior graph.
      operationId: rejectInvitation
      tags:
        - Invitations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RejectInvitationRequest'
            examples:
              RejectInvitationRequestExample:
                summary: Default rejectInvitation request
                x-microcks-default: true
                value:
                  GraphArn: arn:aws:detective:us-east-1:123456789012:graph:abc123def456
      responses:
        '200':
          description: Successfully rejected invitation
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /invitations/list:
    post:
      summary: Amazon Detective List Invitations
      description: Retrieves the list of open and accepted behavior graph invitations for the member account.
      operationId: listInvitations
      tags:
        - Invitations
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListInvitationsRequest'
            examples:
              ListInvitationsRequestExample:
                summary: Default listInvitations request
                x-microcks-default: true
                value:
                  MaxResults: 100
      responses:
        '200':
          description: Successfully listed invitations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListInvitationsResponse'
              examples:
                ListInvitations200Example:
                  summary: Default listInvitations 200 response
                  x-microcks-default: true
                  value:
                    Invitations:
                      - AccountId: '234567890123'
                        GraphArn: arn:aws:detective:us-east-1:123456789012:graph:abc123def456
                        Status: INVITED
                    NextToken: null
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /membership/removal:
    post:
      summary: Amazon Detective Disassociate Membership
      description: Removes the member account from the specified behavior graph. This operation can only be called by a Detective member account.
      operationId: disassociateMembership
      tags:
        - Invitations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DisassociateMembershipRequest'
            examples:
              DisassociateMembershipRequestExample:
                summary: Default disassociateMembership request
                x-microcks-default: true
                value:
                  GraphArn: arn:aws:detective:us-east-1:123456789012:graph:abc123def456
      responses:
        '200':
          description: Successfully disassociated membership
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /graph/datasources/list:
    post:
      summary: Amazon Detective List Datasource Packages
      description: Lists data source packages in the behavior graph.
      operationId: listDatasourcePackages
      tags:
        - Datasources
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListDatasourcePackagesRequest'
            examples:
              ListDatasourcePackagesRequestExample:
                summary: Default listDatasourcePackages request
                x-microcks-default: true
                value:
                  GraphArn: arn:aws:detective:us-east-1:123456789012:graph:abc123def456
                  MaxResults: 100
      responses:
        '200':
          description: Successfully listed datasource packages
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListDatasourcePackagesResponse'
              examples:
                ListDatasourcePackages200Example:
                  summary: Default listDatasourcePackages 200 response
                  x-microcks-default: true
                  value:
                    DatasourcePackages:
                      DETECTIVE_CORE:
                        DatasourcePackageIngestState: STARTED
                        LastIngestStateChange:
                          STARTED:
                            Timestamp: '2025-01-15T10:00:00Z'
                    NextToken: null
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /graph/datasources/get:
    post:
      summary: Amazon Detective Batch Get Graph Member Datasources
      description: Gets data source package information for the behavior graph.
      operationId: batchGetGraphMemberDatasources
      tags:
        - Datasources
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchGetGraphMemberDatasourcesRequest'
            examples:
              BatchGetGraphMemberDatasourcesRequestExample:
                summary: Default batchGetGraphMemberDatasources request
                x-microcks-default: true
                value:
                  GraphArn: arn:aws:detective:us-east-1:123456789012:graph:abc123def456
                  AccountIds:
                    - '234567890123'
      responses:
        '200':
          description: Successfully retrieved datasource details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchGetGraphMemberDatasourcesResponse'
              examples:
                BatchGetGraphMemberDatasources200Example:
                  summary: Default batchGetGraphMemberDatasources 200 response
                  x-microcks-default: true
                  value:
                    MemberDatasources:
                      - AccountId: '234567890123'
                        GraphArn: arn:aws:detective:us-east-1:123456789012:graph:abc123def456
                        DatasourcePackageIngestHistory: {}
                    UnprocessedAccounts: []
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /membership/datasources/get:
    post:
      summary: Amazon Detective Batch Get Membership Datasources
      description: Gets information on the data source package history for an account.
      operationId: batchGetMembershipDatasources
      tags:
        - Datasources
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchGetMembershipDatasourcesRequest'
            examples:
              BatchGetMembershipDatasourcesRequestExample:
                summary: Default batchGetMembershipDatasources request
                x-microcks-default: true
                value:
                  GraphArns:
                    - arn:aws:detective:us-east-1:123456789012:graph:abc123def456
      responses:
        '200':
          description: Successfully retrieved membership datasource history
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchGetMembershipDatasourcesResponse'
              examples:
                BatchGetMembershipDatasources200Example:
                  summary: Default batchGetMembershipDatasources 200 response
                  x-microcks-default: true
                  value:
                    MembershipDatasources:
                      - AccountId: '234567890123'
                        GraphArn: arn:aws:detective:us-east-1:123456789012:graph:abc123def456
                    UnprocessedGraphs: []
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /graph/datasources/update:
    post:
      summary: Amazon Detective Update Datasource Packages
      description: Starts a data source packages for the specified behavior graph.
      operationId: updateDatasourcePackages
      tags:
        - Datasources
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDatasourcePackagesRequest'
            examples:
              UpdateDatasourcePackagesRequestExample:
                summary: Default updateDatasourcePackages request
                x-microcks-default: true
                value:
                  GraphArn: arn:aws:detective:us-east-1:123456789012:graph:abc123def456
                  DatasourcePackages:
                    - EKS_AUDIT
      responses:
        '200':
          description: Successfully updated datasource packages
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /investigations/startInvestigation:
    post:
      summary: Amazon Detective Start Investigation
      description: Initiates a Detective investigation on an entity in a behavior graph.
      operationId: startInvestigation
      tags:
        - Investigations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartInvestigationRequest'
            examples:
              StartInvestigationRequestExample:
                summary: Default startInvestigation request
                x-microcks-default: true
                value:
                  GraphArn: arn:aws:detective:us-east-1:123456789012:graph:abc123def456
                  EntityArn: arn:aws:iam::123456789012:user/jsmith
                  ScopeStartTime: '2025-01-01T00:00:00Z'
                  ScopeEndTime: '2025-01-15T23:59:59Z'
      responses:
        '200':
          description: Successfully started investigation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartInvestigationResponse'
              examples:
                StartInvestigation200Example:
                  summary: Default startInvestigation 200 response
                  x-microcks-default: true
                  value:
                    InvestigationId: invest-abc123def456
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /investigations/getInvestigation:
    post:
      summary: Amazon Detective Get Investigation
      description: Returns the investigation results of an investigation for a behavior graph.
      operationId: getInvestigation
      tags:
        - Investigations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetInvestigationRequest'
            examples:
              GetInvestigationRequestExample:
                summary: Default getInvestigation request
                x-microcks-default: true
                value:
                  GraphArn: arn:aws:detective:us-east-1:123456789012:graph:abc123def456
                  InvestigationId: invest-abc123def456
      responses:
        '200':
          description: Successfully retrieved investigation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetInvestigationResponse'
              examples:
         

# --- truncated at 32 KB (86 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/amazon-detective/refs/heads/main/openapi/amazon-detective-openapi.yml