Amazon Detective Investigations API

Security investigation operations

GitHub OpenAPI

Operations 5

POST /investigations/getInvestigation Get Investigation #
POST /investigations/listIndicators List Indicators #
POST /investigations/listInvestigations List Investigations #
POST /investigations/startInvestigation Start Investigation #
POST /investigations/updateInvestigationState Update Investigation State #

Documentation

Specifications

Schemas & Data

Other Resources

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/amazon-detective:amazon-detective-investigations-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

amazon-detective-investigations-api-openapi.yml Raw ↑
openapi: 3.1.0
info:
  title: Amazon Detective Investigations API
  version: '2018-10-26'
  description: Generated from AWS's published Smithy model for Amazon Detective. 5 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://api.detective.{region}.amazonaws.com
  variables:
    region:
      default: us-east-1
security:
- sigv4: []
paths:
  /investigations/getInvestigation:
    post:
      operationId: GetInvestigation
      summary: Get Investigation
      description: Detective investigations lets you investigate IAM users and IAM roles using indicators of compromise. An
        indicator of compromise (IOC) is an artifact observed in or on a network, system, or environment that can (with a
        high level of confidence) identify malicious activity or a security incident. GetInvestigation returns the investigation
        results of an investigation for a behavior graph.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetInvestigationResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: TooManyRequestsException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GetInvestigationRequest'
      tags:
      - Investigations
  /investigations/listIndicators:
    post:
      operationId: ListIndicators
      summary: List Indicators
      description: Gets the indicators from an investigation. You can use the information from the indicators to determine
        if an IAM user and/or IAM role is involved in an unusual activity that could indicate malicious behavior and its impact.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListIndicatorsResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: TooManyRequestsException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListIndicatorsRequest'
      tags:
      - Investigations
  /investigations/listInvestigations:
    post:
      operationId: ListInvestigations
      summary: List Investigations
      description: Detective investigations lets you investigate IAM users and IAM roles using indicators of compromise. An
        indicator of compromise (IOC) is an artifact observed in or on a network, system, or environment that can (with a
        high level of confidence) identify malicious activity or a security incident. ListInvestigations lists all active
        Detective investigations.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListInvestigationsResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: TooManyRequestsException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ListInvestigationsRequest'
      tags:
      - Investigations
  /investigations/startInvestigation:
    post:
      operationId: StartInvestigation
      summary: Start Investigation
      description: Detective investigations lets you investigate IAM users and IAM roles using indicators of compromise. An
        indicator of compromise (IOC) is an artifact observed in or on a network, system, or environment that can (with a
        high level of confidence) identify malicious activity or a security incident. StartInvestigation initiates an investigation
        on an entity in a behavior graph.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartInvestigationResponse'
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: TooManyRequestsException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartInvestigationRequest'
      tags:
      - Investigations
  /investigations/updateInvestigationState:
    post:
      operationId: UpdateInvestigationState
      summary: Update Investigation State
      description: Updates the state of an investigation.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: string
        '403':
          description: AccessDeniedException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccessDeniedException'
        '500':
          description: InternalServerException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerException'
        '404':
          description: ResourceNotFoundException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResourceNotFoundException'
        '429':
          description: TooManyRequestsException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TooManyRequestsException'
        '400':
          description: ValidationException
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationException'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateInvestigationStateRequest'
      tags:
      - Investigations
components:
  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: detective
  schemas:
    AccessDeniedException:
      type: object
      properties:
        Message:
          type: string
        ErrorCode:
          type: string
          enum:
          - INVALID_GRAPH_ARN
          - INVALID_REQUEST_BODY
          - INTERNAL_ERROR
          description: The SDK default error code associated with the access denied exception.
        ErrorCodeReason:
          type: string
          description: The SDK default explanation of why access was denied.
        SubErrorCode:
          type: string
          enum:
          - INVALID_GRAPH_ARN
          - INVALID_REQUEST_BODY
          - INTERNAL_ERROR
          description: The error code associated with the access denied exception.
        SubErrorCodeReason:
          type: string
          description: An explanation of why access was denied.
    DateFilter:
      type: object
      properties:
        StartInclusive:
          type: string
          format: date-time
          description: A timestamp representing the start of the time period from when data is filtered, including the start
            date.
        EndInclusive:
          type: string
          format: date-time
          description: A timestamp representing the end date of the time period until when data is filtered, including the
            end date.
      required:
      - StartInclusive
      - EndInclusive
    FilterCriteria:
      type: object
      properties:
        Severity:
          $ref: '#/components/schemas/StringFilter'
        Status:
          $ref: '#/components/schemas/StringFilter'
        State:
          $ref: '#/components/schemas/StringFilter'
        EntityArn:
          $ref: '#/components/schemas/StringFilter'
        CreatedTime:
          $ref: '#/components/schemas/DateFilter'
    FlaggedIpAddressDetail:
      type: object
      properties:
        IpAddress:
          type: string
          description: IP address of the suspicious entity.
        Reason:
          type: string
          enum:
          - AWS_THREAT_INTELLIGENCE
          description: Details the reason the IP address was flagged as suspicious.
    GetInvestigationRequest:
      type: object
      properties:
        GraphArn:
          type: string
          description: The Amazon Resource Name (ARN) of the behavior graph.
        InvestigationId:
          type: string
          description: The investigation ID of the investigation report.
      required:
      - GraphArn
      - InvestigationId
    GetInvestigationResponse:
      type: object
      properties:
        GraphArn:
          type: string
          description: The Amazon Resource Name (ARN) of the behavior graph.
        InvestigationId:
          type: string
          description: The investigation ID of the investigation report.
        EntityArn:
          type: string
          description: The unique Amazon Resource Name (ARN). Detective supports IAM user ARNs and IAM role ARNs.
        EntityType:
          type: string
          enum:
          - IAM_ROLE
          - IAM_USER
          description: Type of entity. For example, Amazon Web Services accounts, such as an IAM user and/or IAM role.
        CreatedTime:
          type: string
          format: date-time
          description: The creation time of the investigation report in UTC time stamp format.
        ScopeStartTime:
          type: string
          format: date-time
          description: The start date and time used to set the scope time within which you want to generate the investigation
            report. The value is an UTC ISO8601 formatted string. For example, 2021-08-18T16:35:56.284Z.
        ScopeEndTime:
          type: string
          format: date-time
          description: The data and time when the investigation began. The value is an UTC ISO8601 formatted string. For example,
            2021-08-18T16:35:56.284Z.
        Status:
          type: string
          enum:
          - RUNNING
          - FAILED
          - SUCCESSFUL
          description: The status based on the completion status of the investigation.
        Severity:
          type: string
          enum:
          - INFORMATIONAL
          - LOW
          - MEDIUM
          - HIGH
          - CRITICAL
          description: The severity assigned is based on the likelihood and impact of the indicators of compromise discovered
            in the investigation.
        State:
          type: string
          enum:
          - ACTIVE
          - ARCHIVED
          description: The current state of the investigation. An archived investigation indicates that you have completed
            reviewing the investigation.
    ImpossibleTravelDetail:
      type: object
      properties:
        StartingIpAddress:
          type: string
          description: IP address where the resource was first used in the impossible travel.
        EndingIpAddress:
          type: string
          description: IP address where the resource was last used in the impossible travel.
        StartingLocation:
          type: string
          description: Location where the resource was first used in the impossible travel.
        EndingLocation:
          type: string
          description: Location where the resource was last used in the impossible travel.
        HourlyTimeDelta:
          type: integer
          description: Returns the time difference between the first and last timestamp the resource was used.
    Indicator:
      type: object
      properties:
        IndicatorType:
          type: string
          enum:
          - TTP_OBSERVED
          - IMPOSSIBLE_TRAVEL
          - FLAGGED_IP_ADDRESS
          - NEW_GEOLOCATION
          - NEW_ASO
          - NEW_USER_AGENT
          - RELATED_FINDING
          - RELATED_FINDING_GROUP
          description: The type of indicator.
        IndicatorDetail:
          $ref: '#/components/schemas/IndicatorDetail'
    IndicatorDetail:
      type: object
      properties:
        TTPsObservedDetail:
          $ref: '#/components/schemas/TTPsObservedDetail'
        ImpossibleTravelDetail:
          $ref: '#/components/schemas/ImpossibleTravelDetail'
        FlaggedIpAddressDetail:
          $ref: '#/components/schemas/FlaggedIpAddressDetail'
        NewGeolocationDetail:
          $ref: '#/components/schemas/NewGeolocationDetail'
        NewAsoDetail:
          $ref: '#/components/schemas/NewAsoDetail'
        NewUserAgentDetail:
          $ref: '#/components/schemas/NewUserAgentDetail'
        RelatedFindingDetail:
          $ref: '#/components/schemas/RelatedFindingDetail'
        RelatedFindingGroupDetail:
          $ref: '#/components/schemas/RelatedFindingGroupDetail'
    InternalServerException:
      type: object
      properties:
        Message:
          type: string
    InvestigationDetail:
      type: object
      properties:
        InvestigationId:
          type: string
          description: The investigation ID of the investigation report.
        Severity:
          type: string
          enum:
          - INFORMATIONAL
          - LOW
          - MEDIUM
          - HIGH
          - CRITICAL
          description: Severity based on the likelihood and impact of the indicators of compromise discovered in the investigation.
        Status:
          type: string
          enum:
          - RUNNING
          - FAILED
          - SUCCESSFUL
          description: Status based on the completion status of the investigation.
        State:
          type: string
          enum:
          - ACTIVE
          - ARCHIVED
          description: The current state of the investigation. An archived investigation indicates you have completed reviewing
            the investigation.
        CreatedTime:
          type: string
          format: date-time
          description: The time stamp of the creation time of the investigation report. The value is an UTC ISO8601 formatted
            string. For example, 2021-08-18T16:35:56.284Z.
        EntityArn:
          type: string
          description: The unique Amazon Resource Name (ARN) of the IAM user and IAM role.
        EntityType:
          type: string
          enum:
          - IAM_ROLE
          - IAM_USER
          description: Type of entity. For example, Amazon Web Services accounts, such as IAM user and role.
    ListIndicatorsRequest:
      type: object
      properties:
        GraphArn:
          type: string
          description: The Amazon Resource Name (ARN) of the behavior graph.
        InvestigationId:
          type: string
          description: The investigation ID of the investigation report.
        IndicatorType:
          type: string
          enum:
          - TTP_OBSERVED
          - IMPOSSIBLE_TRAVEL
          - FLAGGED_IP_ADDRESS
          - NEW_GEOLOCATION
          - NEW_ASO
          - NEW_USER_AGENT
          - RELATED_FINDING
          - RELATED_FINDING_GROUP
          description: For the list of indicators of compromise that are generated by Detective investigations, see Detective
            investigations.
        NextToken:
          type: string
          description: Lists if there are more results available. The value of nextToken is a unique pagination token for
            each page. Repeat the call using the returned token to retrieve the next page. Keep all other arguments unchanged.
            Each pagination token expires after 24 hours. Using an expired pagination token will return a Validation Exception
            error.
        MaxResults:
          type: integer
          description: Lists the maximum number of indicators in a page.
      required:
      - GraphArn
      - InvestigationId
    ListIndicatorsResponse:
      type: object
      properties:
        GraphArn:
          type: string
          description: The Amazon Resource Name (ARN) of the behavior graph.
        InvestigationId:
          type: string
          description: The investigation ID of the investigation report.
        NextToken:
          type: string
          description: Lists if there are more results available. The value of nextToken is a unique pagination token for
            each page. Repeat the call using the returned token to retrieve the next page. Keep all other arguments unchanged.
            Each pagination token expires after 24 hours. Using an expired pagination token will return a Validation Exception
            error.
        Indicators:
          type: array
          items:
            $ref: '#/components/schemas/Indicator'
          description: Lists the indicators of compromise.
    ListInvestigationsRequest:
      type: object
      properties:
        GraphArn:
          type: string
          description: The Amazon Resource Name (ARN) of the behavior graph.
        NextToken:
          type: string
          description: Lists if there are more results available. The value of nextToken is a unique pagination token for
            each page. Repeat the call using the returned token to retrieve the next page. Keep all other arguments unchanged.
            Each pagination token expires after 24 hours. Using an expired pagination token will return a Validation Exception
            error.
        MaxResults:
          type: integer
          description: Lists the maximum number of investigations in a page.
        FilterCriteria:
          $ref: '#/components/schemas/FilterCriteria'
        SortCriteria:
          $ref: '#/components/schemas/SortCriteria'
      required:
      - GraphArn
    ListInvestigationsResponse:
      type: object
      properties:
        InvestigationDetails:
          type: array
          items:
            $ref: '#/components/schemas/InvestigationDetail'
          description: Lists the summary of uncommon behavior or malicious activity which indicates a compromise.
        NextToken:
          type: string
          description: Lists if there are more results available. The value of nextToken is a unique pagination token for
            each page. Repeat the call using the returned token to retrieve the next page. Keep all other arguments unchanged.
            Each pagination token expires after 24 hours.
    NewAsoDetail:
      type: object
      properties:
        Aso:
          type: string
          description: Details about the new Autonomous System Organization (ASO).
        IsNewForEntireAccount:
          type: boolean
          description: Checks if the Autonomous System Organization (ASO) is new for the entire account.
    NewGeolocationDetail:
      type: object
      properties:
        Location:
          type: string
          description: Location where the resource was accessed.
        IpAddress:
          type: string
          description: IP address using which the resource was accessed.
        IsNewForEntireAccount:
          type: boolean
          description: Checks if the geolocation is new for the entire account.
    NewUserAgentDetail:
      type: object
      properties:
        UserAgent:
          type: string
          description: New user agent which accessed the resource.
        IsNewForEntireAccount:
          type: boolean
          description: Checks if the user agent is new for the entire account.
    RelatedFindingDetail:
      type: object
      properties:
        Arn:
          type: string
          description: The Amazon Resource Name (ARN) of the related finding.
        Type:
          type: string
          description: The type of finding.
        IpAddress:
          type: string
          description: The IP address of the finding.
    RelatedFindingGroupDetail:
      type: object
      properties:
        Id:
          type: string
          description: The unique identifier for the finding group.
    ResourceNotFoundException:
      type: object
      properties:
        Message:
          type: string
    SortCriteria:
      type: object
      properties:
        Field:
          type: string
          enum:
          - SEVERITY
          - STATUS
          - CREATED_TIME
          description: Represents the Field attribute to sort investigations.
        SortOrder:
          type: string
          enum:
          - ASC
          - DESC
          description: The order by which the sorted findings are displayed.
    StartInvestigationRequest:
      type: object
      properties:
        GraphArn:
          type: string
          description: The Amazon Resource Name (ARN) of the behavior graph.
        EntityArn:
          type: string
          description: The unique Amazon Resource Name (ARN) of the IAM user and IAM role.
        ScopeStartTime:
          type: string
          format: date-time
          description: The data and time when the investigation began. The value is an UTC ISO8601 formatted string. For example,
            2021-08-18T16:35:56.284Z.
        ScopeEndTime:
          type: string
          format: date-time
          description: The data and time when the investigation ended. The value is an UTC ISO8601 formatted string. For example,
            2021-08-18T16:35:56.284Z.
      required:
      - GraphArn
      - EntityArn
      - ScopeStartTime
      - ScopeEndTime
    StartInvestigationResponse:
      type: object
      properties:
        InvestigationId:
          type: string
          description: The investigation ID of the investigation report.
    StringFilter:
      type: object
      properties:
        Value:
          type: string
          description: The string filter value.
      required:
      - Value
    TTPsObservedDetail:
      type: object
      properties:
        Tactic:
          type: string
          description: The tactic used, identified by the investigation.
        Technique:
          type: string
          description: The technique used, identified by the investigation.
        Procedure:
          type: string
          description: The procedure used, identified by the investigation.
        IpAddress:
          type: string
          description: The IP address where the tactics, techniques, and procedure (TTP) was observed.
        APIName:
          type: string
          description: The name of the API where the tactics, techniques, and procedure (TTP) was observed.
        APISuccessCount:
          type: integer
          description: The total number of successful API requests.
        APIFailureCount:
          type: integer
          description: The total number of failed API requests.
    TooManyRequestsException:
      type: object
      properties:
        Message:
          type: string
    UpdateInvestigationStateRequest:
      type: object
      properties:
        GraphArn:
          type: string
          description: The Amazon Resource Name (ARN) of the behavior graph.
        InvestigationId:
          type: string
          description: The investigation ID of the investigation report.
        State:
          type: string
          enum:
          - ACTIVE
          - ARCHIVED
          description: The current state of the investigation. An archived investigation indicates you have completed reviewing
            the investigation.
      required:
      - GraphArn
      - InvestigationId
      - State
    ValidationException:
      type: object
      properties:
        Message:
          type: string
        ErrorCode:
          type: string
          enum:
          - INVALID_GRAPH_ARN
          - INVALID_REQUEST_BODY
          - INTERNAL_ERROR
          description: The error code associated with the validation failure.
        ErrorCodeReason:
          type: string
          description: An explanation of why validation failed.
x-provenance:
  method: harvested
  publisher: Amazon Web Services
  source: https://raw.githubusercontent.com/aws/api-models-aws/3cd98287b471c106254abd89279cc87308d38bfd/models/detective/service/2018-10-26/detective-2018-10-26.json
  note: converted by smithy-to-openapi.py from AWS's Smithy model (roadmap#1001)