Investigations

Investigations are agent-driven sessions that analyze and diagnose issues in your system. Each investigation tracks metadata like a display name, description, and execution status.

Service: firetiger.investigations.v1.InvestigationService

Resource name pattern: investigations/{investigation_id}

Access: Read-write (no delete)

Resource type: Investigation

Example flow

Create an investigation to kick off an agent session, then poll for its status.

1. Create an investigation

The agent’s initial prompt is the content of the user-text activity in initial_activities — that’s what the agent reads and acts on. The description field is investigation metadata only and is not sent to the agent. You don’t need to set display_name: when a seed message is present the server generates the title from it.

curl -X POST "https://api.cloud.firetiger.com/firetiger.investigations.v1.InvestigationService/CreateInvestigation" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "investigation": {},
    "initial_activities": [
      {
        "user": {
          "text": {
            "content": "The payments service started returning 500s at 14:00 UTC. Investigate the root cause and affected scope.",
            "role": "USER"
          }
        }
      }
    ]
  }'

{
  "investigation": {
    "name": "investigations/inv_abc123",
    "displayName": "Payments service returning 500s",
    "status": "INVESTIGATION_STATUS_EXECUTING",
    "createdBy": "user_2xK9mBqHn1pL4vR7wT3eYjZ8aFd",
    "createTime": "2024-06-15T14:30:00Z",
    "updateTime": "2024-06-15T14:30:00Z"
  }
}

The displayName in the response is the title the server generated from the seed message.

2. Check investigation status

Poll the investigation to see whether the agent has finished its analysis.

curl -X POST "https://api.cloud.firetiger.com/firetiger.investigations.v1.InvestigationService/GetInvestigation" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"name": "investigations/inv_abc123"}'

{
  "investigation": {
    "name": "investigations/inv_abc123",
    "displayName": "Payments service returning 500s",
    "status": "INVESTIGATION_STATUS_WAITING",
    "createdBy": "user_2xK9mBqHn1pL4vR7wT3eYjZ8aFd",
    "createTime": "2024-06-15T14:30:00Z",
    "updateTime": "2024-06-15T14:35:12Z"
  }
}

Methods

Method Description
CreateInvestigation Create a new investigation
GetInvestigation Retrieve an investigation by name
ListInvestigations List investigations with filtering and pagination
UpdateInvestigation Update an existing investigation

CreateInvestigation

Create a new investigation. The server auto-generates the investigation ID and starts an agent session. The agent’s prompt comes from initial_activities — seed it with a user-text activity describing what to investigate. If you omit display_name, the server auto-titles the investigation from the seed message.

POST /firetiger.investigations.v1.InvestigationService/CreateInvestigation

Request body

Field Type Required Description
investigation Investigation Yes The investigation to create. Only display_name and description are read from the client (both metadata); other fields are set by the server. description is not sent to the agent.
initial_activities Activity[] No (but effectively required to give the agent a prompt) Activities to seed the investigation session with. This is the client input that carries the agent’s prompt — put the problem statement in a user-text activity (user.text.content), plus any context like log snippets, metric data, or prior analysis. (artifacts below can attach files alongside it.)
artifacts Artifact[] No References (by sha256) to artifacts already uploaded via PUT /v1/artifacts/{sha256}. Each entry carries {name, sha256, content_type, content_encoding}. The server imports each referenced object into the new session’s artifact namespace under the given name before the initial activities are appended, so attachments arrive atomically with the message. The CAS object must already exist (returns FailedPrecondition otherwise). Each artifact is capped at 64 MiB, with a 128 MiB combined per-request cap.

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.investigations.v1.InvestigationService/CreateInvestigation" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "investigation": {},
    "initial_activities": [
      {
        "user": {
          "text": {
            "content": "The payments service started returning 500s at 14:00 UTC. Investigate the root cause and affected scope.",
            "role": "USER"
          }
        }
      }
    ]
  }'

Response

{
  "investigation": {
    "name": "investigations/inv_abc123",
    "displayName": "Payments service returning 500s",
    "status": "INVESTIGATION_STATUS_EXECUTING",
    "createdBy": "user_2xK9mBqHn1pL4vR7wT3eYjZ8aFd",
    "createTime": "2024-06-15T14:30:00Z",
    "updateTime": "2024-06-15T14:30:00Z"
  }
}

GetInvestigation

Retrieve an investigation by name.

POST /firetiger.investigations.v1.InvestigationService/GetInvestigation

Request body

Field Type Required Description
name string Yes Resource name of the investigation (investigations/{id})

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.investigations.v1.InvestigationService/GetInvestigation" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"name": "investigations/inv_abc123"}'

ListInvestigations

List investigations with optional filtering and pagination.

POST /firetiger.investigations.v1.InvestigationService/ListInvestigations

Request body

| Field | Type | Required | Description | |:——|:—–|:———|:————| | filter | string | No | Filter expression (e.g. status = INVESTIGATION_STATUS_EXECUTING) | | order_by | string | No | Field to sort by. Supported: create_time, update_time, display_name. Append ` desc or asc for direction. Default: create_time desc. | | page_size | integer | No | Maximum results per page | | page_token | string | No | Token for the next page of results | | show_deleted` | boolean | No | Include soft-deleted investigations |

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.investigations.v1.InvestigationService/ListInvestigations" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"filter": "status = \"INVESTIGATION_STATUS_EXECUTING\"", "page_size": 25}'

Response

{
  "investigations": [
    {
      "name": "investigations/inv_abc123",
      "displayName": "Elevated error rate in payments service",
      "status": "INVESTIGATION_STATUS_EXECUTING",
      "createdBy": "user_2xK9mBqHn1pL4vR7wT3eYjZ8aFd",
      "createTime": "2024-06-15T14:30:00Z",
      "updateTime": "2024-06-15T14:30:00Z"
    }
  ],
  "nextPageToken": ""
}

UpdateInvestigation

Update an existing investigation’s metadata. Use update_mask to specify which fields to modify.

POST /firetiger.investigations.v1.InvestigationService/UpdateInvestigation

Request body

Field Type Required Description
investigation Investigation Yes The investigation with name set and updated fields
update_mask string No Comma-separated list of fields to update. Supported: display_name, description, status. If omitted, all provided fields are updated.

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.investigations.v1.InvestigationService/UpdateInvestigation" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "investigation": {
      "name": "investigations/inv_abc123",
      "display_name": "Payments 500s - resolved: bad deploy"
    },
    "update_mask": "display_name"
  }'
This site uses Just the Docs, a documentation theme for Jekyll.