Services

The Services catalog is the system map agents use to reason about ownership, blast radius, and which components show up in a given Flow. Each Service entry carries a human description, a durable agent-curated context describing the Service, and the breakdown Dimensions its health is measured along.

Service: firetiger.observability.v1.ServiceCatalogService

Resource name pattern: services/{service_id}

Access: Read-write

Methods

The standard AIP-compliant CRUD surface plus a recommendation-lifecycle surface is available. Request/response shapes are in proto/firetiger/observability/v1/services.proto and follow the same patterns as other resources documented here (e.g. Tags).

Service methods

RPC HTTP
CreateService POST /v1/catalog/services
GetService GET /v1/catalog/{name=services/*}
ListServices GET /v1/catalog/services
UpdateService PATCH /v1/catalog/{service.name=services/*}
DeleteService DELETE /v1/catalog/{name=services/*}
RecommendService POST /v1/catalog/services:recommend
AcceptService POST /v1/catalog/{name=services/*}:accept
ArchiveService POST /v1/catalog/{name=services/*}:archive
RestoreService POST /v1/catalog/{name=services/*}:restore
RecommendServiceObservability POST /v1/catalog/{parent=services/*}:recommendObservability
RecreateServiceExpertSession POST /v1/catalog/{name=services/*}:recreateExpertSession

ServiceDimension methods

A ServiceDimension is a service-local health breakdown axis nested under a Service (services/{service}/dimensions/{dimension}). It replaces the deprecated top-level Service.dimensions list for Service observability: Objectives and Indicators bind to a ServiceDimension.

RPC HTTP
CreateServiceDimension POST /v1/catalog/{parent=services/*}/dimensions
GetServiceDimension GET /v1/catalog/{name=services/*/dimensions/*}
ListServiceDimensions GET /v1/catalog/{parent=services/*}/dimensions
UpdateServiceDimension PATCH /v1/catalog/{service_dimension.name=services/*/dimensions/*}
DeleteServiceDimension DELETE /v1/catalog/{name=services/*/dimensions/*}
AcceptServiceDimension POST /v1/catalog/{name=services/*/dimensions/*}:accept
ArchiveServiceDimension POST /v1/catalog/{name=services/*/dimensions/*}:archive
RestoreServiceDimension POST /v1/catalog/{name=services/*/dimensions/*}:restore

Recommendation lifecycle

Services and ServiceDimensions are both first-class catalog resources that carry a state, and both flow through the same recommendation lifecycle:

  • System discovery stores newly-discovered catalog entries via RecommendService. The recommended Service is persisted as a real resource in SERVICE_STATE_RECOMMENDED and its Service Expert is provisioned immediately.
  • Each Service’s Expert then proposes its breakdown dimensions, Objectives, and backing Indicators via RecommendServiceObservability. Recommended ServiceDimensions land in SERVICE_DIMENSION_STATE_RECOMMENDED.
  • A customer accepts a recommendation (AcceptService / AcceptServiceDimension) to promote it to the *_ACTIVE state, or archives it (ArchiveService / ArchiveServiceDimension) to dismiss it into the *_ARCHIVED state. Restore (RestoreService / RestoreServiceDimension) brings an archived resource back. User-created Services default to SERVICE_STATE_ACTIVE.
  • AcceptService bulk-activates the Service’s accepted breakdown and Objectives; archived child Objectives are skipped.

Recommendation metadata is carried on the resource itself: recommendation_confidence, recommendation_evidence, and recommendation_reasoning (see field tables below).

Service resource

Field Type Behavior Description
name string Output only Format: services/{service}
display_name string Required Short, scannable label shown in headers and Service lists (1–200 chars)
description string Optional One-paragraph, human-facing overview of what the Service is
context string Optional Durable, structured Markdown describing the Service, read by agents and rendered on the Service page. Agents curate it into canonical sections (purpose, code references, Service and Provider dependencies, invariants, failure modes and known bugs); it holds steady-state knowledge, not point-in-time evidence or timestamps. Customer-editable
expert_session string Output only The per-Service service-expert agent session that proposes and maintains this Service’s Objectives, Indicators, and Dimensions. Format: agents/{agent}/sessions/{session}
dimensions string[] Optional, deprecated The firetiger.dimensions.v1 Dimensions this Service’s health is broken down by — its declared deployment shape (e.g. environment, region, cloud). Each entry is a dimensions/{dimension} resource name. Superseded by the nested ServiceDimension resource; use CreateServiceDimension/ListServiceDimensions instead
state ServiceState Output only Lifecycle state. User-created Services default to SERVICE_STATE_ACTIVE; system-recommended Services persist in SERVICE_STATE_RECOMMENDED until accepted or archived. See ServiceState
recommendation_confidence RecommendationConfidence Optional Agent’s confidence in this recommendation. See RecommendationConfidence
recommendation_evidence string[] Optional Supporting evidence the agent cited when recommending this Service
recommendation_reasoning string Optional Free-text rationale for why this Service was recommended
etag string Output only Optimistic-concurrency token returned by Get and required on Update; stale etags fail with ABORTED
create_time / update_time / delete_time timestamp Output only Standard AIP lifecycle timestamps

UpdateService is field-masked: send the Service with an update_mask listing the paths to write (e.g. context). state, expert_session, and the other output-only fields are server-managed and ignored on Create/Update.

ServiceDimension resource

Field Type Behavior Description
name string Output only Format: services/{service}/dimensions/{dimension}
display_name string Required Short, scannable label for the breakdown axis (1–200 chars)
description string Optional One-line, human-facing description of what this axis splits on
state ServiceDimensionState Output only Lifecycle state. Recommended dimensions persist in SERVICE_DIMENSION_STATE_RECOMMENDED until accepted or archived. See ServiceDimensionState
source_column string Optional Suggested or observed query output column for this axis. Indicator DimensionBindings still carry the authoritative per-query column mapping; this lets the Service page preview recommended dimensions before an Objective is opened
recommendation_confidence RecommendationConfidence Optional Agent’s confidence in this recommendation. See RecommendationConfidence
recommendation_evidence string[] Optional Supporting evidence the agent cited when recommending this dimension
recommendation_reasoning string Optional Free-text rationale for why this dimension was recommended
etag string Output only Optimistic-concurrency token returned by Get and required on Update; stale etags fail with ABORTED
create_time / update_time / delete_time timestamp Output only Standard AIP lifecycle timestamps

UpdateServiceDimension is field-masked: send the ServiceDimension with an update_mask of the paths to write. Output-only fields (state, etag, timestamps) are server-managed and ignored on Create/Update.

Enums

ServiceState

Value Description
SERVICE_STATE_UNSPECIFIED Default zero value; not a valid persisted state
SERVICE_STATE_RECOMMENDED System-recommended Service awaiting accept/archive
SERVICE_STATE_ACTIVE Accepted (or user-created) Service
SERVICE_STATE_ARCHIVED Dismissed recommendation; hidden from active views

ServiceDimensionState

Value Description
SERVICE_DIMENSION_STATE_UNSPECIFIED Default zero value; not a valid persisted state
SERVICE_DIMENSION_STATE_RECOMMENDED Recommended breakdown axis awaiting accept/archive
SERVICE_DIMENSION_STATE_ACTIVE Accepted dimension
SERVICE_DIMENSION_STATE_ARCHIVED Dismissed recommendation

RecommendationConfidence

Value Description
RECOMMENDATION_CONFIDENCE_UNSPECIFIED Confidence not set
RECOMMENDATION_CONFIDENCE_HIGH High confidence
RECOMMENDATION_CONFIDENCE_MEDIUM Medium confidence
RECOMMENDATION_CONFIDENCE_LOW Low confidence

Revision history (AIP-162)

Revision history is served by the legacy firetiger.objectives.v1.ServicesService, which exposes the same services/{service} resource plus two read RPCs. Every mutation (Create, Update, Delete, Undelete) atomically writes a revision row recording who changed the resource, what kind of change, and when.

ListServiceRevisions

List the revision history of one Service. Default order is reverse-chronological (newest first).

GET /v1/{parent=services/*}/revisions

or as a Connect RPC:

POST /firetiger.objectives.v1.ServicesService/ListServiceRevisions

Request body

Field Type Required Description
parent string Yes Resource name of the Service whose revisions to list. Format: services/{service}
page_size integer No Maximum revisions per page
page_token string No Token from a previous ListServiceRevisionsResponse
filter string No AIP-160 filter over name, revision_number, operation, actor_subject, actor_kind, create_time
order_by string No AIP-132 ordering. Defaults to create_time desc

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.objectives.v1.ServicesService/ListServiceRevisions" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"parent": "services/checkout-api", "page_size": 50}'

Response

{
  "serviceRevisions": [
    {
      "name": "services/checkout-api/revisions/3",
      "snapshot": { "name": "services/checkout-api", "displayName": "Checkout API v3", "...": "..." },
      "createTime": "2026-05-14T18:10:11Z",
      "operation": "REVISION_OPERATION_UPDATE",
      "actor": { "subject": "user_2abc", "kind": "ACTOR_KIND_USER" }
    }
  ],
  "nextPageToken": ""
}

GetServiceRevision

Return a single revision by its AIP-162 nested-collection name.

GET /v1/{name=services/*/revisions/*}

or:

POST /firetiger.objectives.v1.ServicesService/GetServiceRevision

Request body

Field Type Required Description
name string Yes Format: services/{service}/revisions/{n} where n is a positive integer

Example

curl -X POST "https://api.cloud.firetiger.com/firetiger.objectives.v1.ServicesService/GetServiceRevision" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"name": "services/checkout-api/revisions/2"}'

Notes

  • History starts at opt-in time. Services that existed before this revision API shipped have no historical revisions until their next mutation.
  • Purge (force delete) cascades to revisions atomically.
  • See Flows for the same revision pattern applied to the Flows resource.
This site uses Just the Docs, a documentation theme for Jekyll.