> ## Documentation Index
> Fetch the complete documentation index at: https://docs.levelblue.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Obtain an Investigation

> Returns an investiation.



## OpenAPI

````yaml /documentation/api-reference/v3.yaml get /investigations/{investigationId}
openapi: 3.0.0
info:
  title: USM Anywhere Investigations API
  version: '3'
  description: >-
    This document contains the API specification for the Investigations
    microservice. You can use this API to build, delete, modify, or list the
    Investigation objects, which may contain attachments, evidence, or notes.
  contact:
    url: http://www.levelblue.com
servers:
  - url: http://investigations.{region}.alienvault.cloud/investigations/v3
security:
  - JWT: []
tags:
  - name: Attachments
  - name: Evidence
  - name: History
  - name: Investigations
  - name: Notes
paths:
  /investigations/{investigationId}:
    parameters:
      - $ref: '#/components/parameters/investigationId'
    get:
      tags:
        - Investigations
      summary: Obtain an Investigation
      description: Returns an investiation.
      operationId: get-investigations-investigationId
      parameters:
        - $ref: '#/components/parameters/X-ATT-MessageId'
      responses:
        '200':
          description: OK
          headers:
            X-ATT-MessageId:
              $ref: '#/components/headers/X-ATT-MessageId'
            X-ATT-TransactionId:
              $ref: '#/components/headers/X-ATT-TransactionId'
            X-ATT-ServiceVersion:
              $ref: '#/components/headers/X-ATT-ServiceVersion'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/gInvestigation'
              examples:
                i11n_g:
                  $ref: '#/components/examples/i11n_g'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '404':
          $ref: '#/components/responses/404'
        '406':
          $ref: '#/components/responses/406'
        '429':
          $ref: '#/components/responses/429'
        '500':
          $ref: '#/components/responses/500'
        '503':
          $ref: '#/components/responses/503'
components:
  parameters:
    investigationId:
      name: investigationId
      description: The unique identifier of an investigation.
      in: path
      schema:
        type: string
        format: uuid
      required: true
    X-ATT-MessageId:
      name: X-ATT-MessageId
      description: |-
        A client-provided value that uniquely identifies a client
        generated message sent to the service. This header will be
        reflected back unchanged in the response.
      in: header
      schema:
        type: string
        format: uuid
  headers:
    X-ATT-MessageId:
      description: |-
        A client-provided value that uniquely identifies a client
        generated message sent to the service. This header will be
        present in the response if the client provided one in the
        request.
      schema:
        type: string
      required: false
    X-ATT-TransactionId:
      description: |-
        A service provided value that uniquely identifies a message
        returned by the service.
      schema:
        type: string
        format: uuid
      required: true
    X-ATT-ServiceVersion:
      description: |-
        Identifies the version number of the service that processed
        the request.
      schema:
        type: string
      required: true
    Date:
      schema:
        type: string
        format: date-time
      required: true
  schemas:
    gInvestigation:
      title: getInvestigation
      type: object
      properties:
        _links:
          type: object
          properties:
            self:
              $ref: '#/components/schemas/selfLink'
            attachments:
              allOf:
                - $ref: '#/components/schemas/href'
              description: A link to the attachments associated with this investigation.
            evidence:
              allOf:
                - $ref: '#/components/schemas/href'
              description: A link to the evidence associated with this investigation.
            notes:
              allOf:
                - $ref: '#/components/schemas/href'
              description: A link to the notes associated with this investigation.
            history:
              allOf:
                - $ref: '#/components/schemas/href'
              description: A link to the change history of this investigation.
        _embedded:
          type: object
          properties:
            attachments:
              title: attachments
              type: object
              properties:
                elements:
                  type: integer
                  minimum: 0
              description: |-
                The number of associated attachments visible to the requesting
                user
            evidence:
              title: evidence
              type: object
              properties:
                elements:
                  type: integer
                  minimum: 0
              description: The number of associated evidence object
            notes:
              title: notes
              type: object
              properties:
                elements:
                  type: integer
                  minimum: 0
              description: The number of associated notes visible to the requesting user
            history:
              title: history
              type: object
              properties:
                elements:
                  type: integer
                  minimum: 0
              description: The number of changes in the investigation history
        id:
          $ref: '#/components/schemas/i11nId'
        i3:
          $ref: '#/components/schemas/i3'
        title:
          $ref: '#/components/schemas/i11nTitle'
        description:
          $ref: '#/components/schemas/description'
        deployment:
          $ref: '#/components/schemas/deployment'
        private:
          $ref: '#/components/schemas/private'
        status:
          $ref: '#/components/schemas/status'
        intent:
          $ref: '#/components/schemas/intent'
        severity:
          $ref: '#/components/schemas/severity'
        assignedTo:
          $ref: '#/components/schemas/assignedTo'
        created:
          $ref: '#/components/schemas/created'
        lastModified:
          $ref: '#/components/schemas/lastModified'
      description: Returns an investigation.
    selfLink:
      type: object
      description: References the returned resource
      allOf:
        - $ref: '#/components/schemas/href'
    href:
      type: object
      description: An absolute URI [RFC3986]
      format: uri
      properties:
        href:
          type: string
          format: uri
          description: An absolute URI [RFC3986]
    i11nId:
      allOf:
        - $ref: '#/components/schemas/id'
      description: ID of the investigation.
    i3:
      type: string
      title: i3
      description: >-
        Allows you to specify an alternative identifier for the investigation so
        that it is simple to integrate with your existing systems and processes.
    i11nTitle:
      title: title
      type: string
      description: Title of the investigation.
    description:
      title: description
      type: string
      description: 'Description of the investigation. '
    deployment:
      type: string
      title: deployment
      format: uri
      description: URI of the USM Anywhere deployment.
    private:
      type: boolean
      description: >-
        Specifies the visibility of the item. This semantic is only valid when
        there exists a relationship between a USM Central deployment and a USM
        Anywhere deployment. When set to true, only the users within the same
        deployment, USM Central or USM Anywhere, can see the item; the users
        from the other deployment cannot. 
    status:
      type: string
      title: status
      enum:
        - Open
        - In Review
        - Closed
      description: Status of the investigation.
    intent:
      type: string
      title: intent
      enum:
        - Exploitation & Installation
        - Delivery & Attack
        - Reconnaissance & Probing
        - Environmental Awareness
      description: 'Intent of the investigation. '
    severity:
      type: string
      title: severity
      enum:
        - None
        - Low
        - Medium
        - High
        - Critical
      description: Severity of the investigation.
    assignedTo:
      type: string
      title: assignedTo
      format: email
      description: 'Email of the user receiving the assignment. '
    created:
      allOf:
        - $ref: '#/components/schemas/_modOnBy'
      description: 'Specifies when the resource was created and by whom. '
    lastModified:
      title: lastModified
      allOf:
        - $ref: '#/components/schemas/_modOnBy'
      description: 'Specifies when the latest modification was made and by whom. '
    errorBody:
      title: errorBody
      type: object
      properties:
        errorId:
          type: string
          description: |-
            Unique errorId in the context of an API.

            Recommendation: two hyphen-delimited subfields:
            * Domain: identifies the API, application, service or general
              category to which the error belongs.
            * Code: provides a unique numeric code within the domain.

            Examples: General-0001, DataDict-0001
        message:
          type: string
          description: Message text
        variables:
          type: array
          description: >-
            List of zero or more strings that represent the contents of the
            variables used by the message text.
          items:
            type: string
        errorUrl:
          type: string
          format: uri
          description: >-
            Hyperlink to more information about the error, including causes and
            solutions.
      required:
        - errorId
        - message
      x-examples:
        full error body:
          errorId: addressbook-0003
          message: 'Invalid input value for property %1. Valid values are: %2.'
          variables:
            - addressType
            - Home, Work, Other
          errorUrl: http://dev.att.com/apis/errors?code=addressbook-0003
        minimal error body:
          errorId: addressbook-0001
          message: Daily TPS limit exceeded.
    id:
      type: string
      title: id
      format: uuid
      description: Unique identifier of the resource.
    _modOnBy:
      title: _mod_on_by
      type: object
      description: 'Specifies when the change was made and by whom.  '
      properties:
        by:
          type: string
          format: email
          description: 'Email of the user who made the change. '
        'on':
          type: string
          format: date-time
          description: >-
            Date and time when the change was made. Accepted format is ISO-8601
            YYYY-MM-DDThh:mm:ss.sTZD. 
      required:
        - by
        - 'on'
  examples:
    i11n_g:
      summary: Response Example
      value:
        _links:
          self:
            href: >-
              https://svc.alienvault.cloud/investigations/v3/investigations/2033c597-97d2-49f4-b3b6-c9079d46c0f2
          attachments:
            href: >-
              https://svc.alienvault.cloud/investigations/v3/investigations/2033c597-97d2-49f4-b3b6-c9079d46c0f2/attachments
          evidence:
            href: >-
              https://svc.alienvault.cloud/investigations/v3/investigations/2033c597-97d2-49f4-b3b6-c9079d46c0f2/evidence
          history:
            href: >-
              https://svc.alienvault.cloud/investigations/v3/investigations/2033c597-97d2-49f4-b3b6-c9079d46c0f2/history
          notes:
            href: >-
              https://svc.alienvault.cloud/investigations/v3/investigations/2033c597-97d2-49f4-b3b6-c9079d46c0f2/notes
        _embedded:
          attachments:
            elements: 1
          evidence:
            elements: 6
          notes:
            elements: 3
          history:
            elements: 21
        id: 2033c597-97d2-49f4-b3b6-c9079d46c0f2
        i3: INV-201811-22-0023
        title: A weird error
        description: I found this strange error in my logs. It could be serious.
        deployment: cn://asecurityteam.alienvault.cloud
        private: false
        severity: Medium
        intent: Reconnaissance & Probing
        status: Open
        assignedTo: ace@some.mssp.com
        created:
          by: user@asecurityteam.com
          'on': '2018-11-07T15:38:52.132Z'
        lastModified:
          by: user@asecurityteam.com
          'on': '2018-11-07T15:38:52.132Z'
  responses:
    '400':
      description: |-
        Bad Request - Many possible reasons associated with the request
        (form, content, etc.). Do not resubmit this request unchanged.
      headers:
        Date:
          $ref: '#/components/headers/Date'
        X-ATT-TransactionId:
          $ref: '#/components/headers/X-ATT-TransactionId'
        X-ATT-ServiceVersion:
          $ref: '#/components/headers/X-ATT-ServiceVersion'
        X-ATT-MessageId:
          $ref: '#/components/headers/X-ATT-MessageId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorBody'
    '401':
      description: |-
        Unauthorized - Authentication failed or was not provided in the
        Authorization header.
      headers:
        WWW-Authenticate:
          schema:
            type: string
            enum:
              - Bearer
        Date:
          $ref: '#/components/headers/Date'
        X-ATT-TransactionId:
          $ref: '#/components/headers/X-ATT-TransactionId'
        X-ATT-ServiceVersion:
          $ref: '#/components/headers/X-ATT-ServiceVersion'
        X-ATT-MessageId:
          $ref: '#/components/headers/X-ATT-MessageId'
    '403':
      description: |-
        Forbidden - The client has insufficient permissions to access
        the resource
      headers:
        Date:
          $ref: '#/components/headers/Date'
        X-ATT-TransactionId:
          $ref: '#/components/headers/X-ATT-TransactionId'
        X-ATT-ServiceVersion:
          $ref: '#/components/headers/X-ATT-ServiceVersion'
        X-ATT-MessageId:
          $ref: '#/components/headers/X-ATT-MessageId'
    '404':
      description: |-
        Not Found - The server has not found anything matching the
        Request-URI. No indication is given of whether the condition
        is temporary or permanent.
      headers:
        Date:
          $ref: '#/components/headers/Date'
        X-ATT-TransactionId:
          $ref: '#/components/headers/X-ATT-TransactionId'
        X-ATT-ServiceVersion:
          $ref: '#/components/headers/X-ATT-ServiceVersion'
        X-ATT-MessageId:
          $ref: '#/components/headers/X-ATT-MessageId'
    '406':
      description: >-
        Not Acceptable - The value specified for the Accept header in the
        request is not supported. Acceptable value is "application/json".
      headers:
        Date:
          $ref: '#/components/headers/Date'
        X-ATT-TransactionId:
          $ref: '#/components/headers/X-ATT-TransactionId'
        X-ATT-ServiceVersion:
          $ref: '#/components/headers/X-ATT-ServiceVersion'
        X-ATT-MessageId:
          $ref: '#/components/headers/X-ATT-MessageId'
    '429':
      description: Too Many Requests
      headers:
        Date:
          $ref: '#/components/headers/Date'
        Retry-After:
          schema:
            type: integer
          description: |-
            Tells the user how long to wait in seconds before making
            another request in seconds.
        X-ATT-TransactionId:
          $ref: '#/components/headers/X-ATT-TransactionId'
        X-ATT-ServiceVersion:
          $ref: '#/components/headers/X-ATT-ServiceVersion'
        X-ATT-MessageId:
          $ref: '#/components/headers/X-ATT-MessageId'
    '500':
      description: |-
        Internal Sever Error - The server encountered an internal error
        or timed out. Please try again later.
      headers:
        Date:
          $ref: '#/components/headers/Date'
        X-ATT-TransactionId:
          $ref: '#/components/headers/X-ATT-TransactionId'
        X-ATT-ServiceVersion:
          $ref: '#/components/headers/X-ATT-ServiceVersion'
        X-ATT-MessageId:
          $ref: '#/components/headers/X-ATT-MessageId'
    '503':
      description: |-
        Service Unavailable - The server is currently unable to receive
        requests. Please try again later.
      headers:
        Date:
          $ref: '#/components/headers/Date'
        X-ATT-TransactionId:
          $ref: '#/components/headers/X-ATT-TransactionId'
        X-ATT-ServiceVersion:
          $ref: '#/components/headers/X-ATT-ServiceVersion'
        X-ATT-MessageId:
          $ref: '#/components/headers/X-ATT-MessageId'
  securitySchemes:
    JWT:
      type: http
      scheme: bearer

````