API Reference

This is the reference documentation for the Firetiger REST API. The API follows Google’s API Improvement Proposals (AIP) conventions.

Base URL

Your deployment’s API base URL is:

https://api.ft-scaletowin.firetigerapi.com

Authentication

API requests are authenticated with API keys using HTTP Basic auth. When you create a key, the UI provides a username and password you can use directly.

curl -X POST "https://api.ft-scaletowin.firetigerapi.com/firetiger.knownissues.v1.KnownIssuesService/ListKnownIssues" \
  -u "$API_KEY_USERNAME:$API_KEY_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{}'

API keys come in two access levels:

Level	Description
Read-only	List and get resources, plus invoke triggers
Read-write	All read-only access, plus create, update, and delete resources

Calling convention

All API methods use HTTP POST with a JSON request body. The URL pattern is:

POST /{package}.{Service}/{Method}

Every request must include the header Content-Type: application/json.

Requests accept both snake_case and camelCase field names. Responses always use camelCase.

Resource names

Resources are identified by a name field following the pattern {collection}/{id}. For example:

• known-issues/ki-auth-timeout
• agents/my-agent
• agents/my-agent/sessions/s-123

Nested resources include their parent’s name as a prefix.

Standard methods

Most resources support some or all of these standard methods:

Method	Description	Key request fields
Create	Create a new resource	{resource_id}, {resource} object
Get	Retrieve a single resource	name
List	List resources with pagination	page_size, page_token, filter, order_by
Update	Modify an existing resource	{resource} object with name set, update_mask
Delete	Soft-delete a resource	name

Pagination

List methods return results in pages.

Request fields

Field	Description
page_size	Maximum number of results per page (server may return fewer)
page_token	Token from a previous next_page_token to fetch the next page

Response fields

Field	Description
next_page_token	Token to pass as page_token in the next request. Empty when there are no more results.

# First page
curl -X POST "https://api.ft-scaletowin.firetigerapi.com/firetiger.knownissues.v1.KnownIssuesService/ListKnownIssues" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"page_size": 10}'

# Next page (using next_page_token from previous response)
curl -X POST "https://api.ft-scaletowin.firetigerapi.com/firetiger.knownissues.v1.KnownIssuesService/ListKnownIssues" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"page_size": 10, "page_token": "..."}'

Filtering

List methods accept a filter parameter for filtering results. The syntax is based on AIP-160.

Operators

Operator	Description	Example
=	Equals	status = "KNOWN_ISSUE_STATUS_ACTIVE"
!=	Not equals	status != "KNOWN_ISSUE_STATUS_RESOLVED"
<	Less than	create_time < "2024-06-01T00:00:00Z"
>	Greater than	create_time > "2024-01-01T00:00:00Z"
<=	Less than or equal	create_time <= "2024-06-30T23:59:59Z"
>=	Greater than or equal	create_time >= "2024-01-01T00:00:00Z"
:	Has / contains (wildcard)	display_name : "*payments*"

Combining filters

Use AND, OR, and NOT to combine expressions:

{"filter": "status = \"KNOWN_ISSUE_STATUS_ACTIVE\" AND create_time > \"2024-01-01T00:00:00Z\""}

Field access

Use dot-delimited paths to access nested fields and map keys:

• labels.environment = "production" – map value access
• origin.repository = "acme-corp/backend" – nested message field

See each resource page for the filterable fields specific to that resource.

Ordering

List methods accept an order_by parameter to control sort order:

{"order_by": "create_time desc"}

Use asc (default) or desc after the field name. Dot-delimited paths work for nested fields (e.g. origin.pr_number desc).

Partial updates

Update methods accept an update_mask field (a FieldMask) to specify which fields to modify. Only the listed fields are changed; others are left untouched.

The value is a comma-separated list of field paths. Dot-delimited paths address nested fields (e.g. configuration.cron.schedule).

{
  "known_issue": {
    "name": "known-issues/ki-auth-timeout",
    "status": "KNOWN_ISSUE_STATUS_RESOLVED"
  },
  "update_mask": "status"
}

If update_mask is omitted, all mutable fields in the request are updated.

For repeated fields and map fields, the provided value replaces the existing value entirely – there is no element-level merging.

Soft delete

Delete methods perform a soft delete by default. Soft-deleted resources:

• Have a non-null delete_time timestamp
• Are excluded from List results unless show_deleted is set to true
• Can still be retrieved with Get by name

{"show_deleted": true}

Field behaviors

Fields in the resource type tables are annotated with behaviors:

Behavior	Meaning
OUTPUT_ONLY	Set by the server. Ignored if included in create/update requests.
REQUIRED	Must be provided in create requests.
No annotation	Optional. Can be set on create and modified with update.

Timestamps

All timestamps are in RFC 3339 format with UTC timezone:

"2024-06-15T14:30:00Z"

Error responses

Errors are returned as JSON with an HTTP status code and a code string:

{
  "code": "not_found",
  "message": "known-issues/does-not-exist not found"
}

HTTP Status	Code	Description
400	invalid_argument	The request is malformed or a required field is missing
401	unauthenticated	Missing or invalid credentials
403	permission_denied	The API key doesn’t have access to this method
404	not_found	The requested resource doesn’t exist
409	already_exists	A resource with that ID already exists
500	internal	Internal server error

Resources

Read-write

These resources support full CRUD operations with a read-write API key:

• Known Issues — problems your team is tracking
• Customers — customer definitions for scoping investigations
• Investigations — ad-hoc data investigations
• Notes — free-form notes attached to resources
• Runbooks — operational runbooks for agents
• Triggers — webhook triggers for agent invocation
• Agents — autonomous agents, sessions, and message read/write
• Deployments — software deployment tracking

Read-only

These resources are managed by the system and available for reading:

• Connections — configured integrations and their sub-services
• Issues — system-detected issues and notification policies
• Monitoring Plans — agent monitoring configurations and runs

Reference

• Types — all resource types, enums, and shared types

---

Table of contents

• Agents
• Connections
• Customers
• Deployments
• Investigations
• Issues
• Known Issues
• Monitoring Plans
• Notes
• Runbooks
• Triggers
• Types