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 description becomes the agent’s initial prompt, so describe the problem you want investigated.

curl -X POST "https://api.ft-jam.firetigerapi.com/firetiger.investigations.v1.InvestigationService/CreateInvestigation" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "investigation": {
      "display_name": "Elevated error rate in payments service",
      "description": "The payments service started returning 500s at 14:00 UTC. Investigate the root cause and affected scope."
    }
  }'

{
  "investigation": {
    "name": "investigations/inv_abc123",
    "displayName": "Elevated error rate in payments service",
    "description": "The payments service started returning 500s at 14:00 UTC. Investigate the root cause and affected scope.",
    "status": "INVESTIGATION_STATUS_EXECUTING",
    "createdBy": "user_2xK9mBqHn1pL4vR7wT3eYjZ8aFd",
    "createTime": "2024-06-15T14:30:00Z",
    "updateTime": "2024-06-15T14:30:00Z"
  }
}

2. Check investigation status

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

curl -X POST "https://api.ft-jam.firetigerapi.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": "Elevated error rate in payments service",
    "description": "The payments service started returning 500s at 14:00 UTC. Investigate the root cause and affected scope.",
    "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 description field becomes the agent’s initial prompt, so it should describe the problem you want the agent to investigate. You can optionally seed the session with additional context via initial_activities.

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 accepted; other fields are set by the server.
initial_activities Activity[] No Initial activities to seed the investigation session with. Use these to provide additional context beyond the description, such as log snippets, metric data, or prior analysis from other sessions.

Example

curl -X POST "https://api.ft-jam.firetigerapi.com/firetiger.investigations.v1.InvestigationService/CreateInvestigation" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "investigation": {
      "display_name": "Elevated error rate in payments service",
      "description": "The payments service started returning 500s at 14:00 UTC. Investigate the root cause and affected scope."
    }
  }'

Response

{
  "investigation": {
    "name": "investigations/inv_abc123",
    "displayName": "Elevated error rate in payments service",
    "description": "The payments service started returning 500s at 14:00 UTC. Investigate the root cause and affected scope.",
    "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.ft-jam.firetigerapi.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.ft-jam.firetigerapi.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.ft-jam.firetigerapi.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.