Create monitor

Create a new monitor. It scores the metric families in metricGroupIds and the metrics of the Specifications in specificationIds; at least one of the two is required. See Monitors.

POST /monitors

Create monitor

cURL

curl --request POST \
  --url https://api.galtea.ai/monitors \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "productId": "prod_123",
  "name": "Production quality watch",
  "versionId": "version_123",
  "metricGroupIds": [
    "metricGroup_123"
  ],
  "specificationIds": [
    "specification_123"
  ],
  "samplingPercentage": 10,
  "monthlyCreditCap": 500,
  "filterQuery": "refund, cancel, chargeback",
  "filterTarget": "EITHER",
  "excludeQuery": "test, internal",
  "excludeTarget": "EITHER",
  "messageConditions": [
    {
      "count": "messages",
      "operator": "gt",
      "value": 1
    }
  ],
  "status": "ACTIVE"
}
'

201

{
  "id": "monitor_123",
  "productId": "prod_123",
  "versionId": "version_123",
  "userId": "user_123",
  "name": "Production quality watch",
  "metricGroupIds": [
    "metricGroup_123"
  ],
  "specificationIds": [
    "specification_123"
  ],
  "scoredMetricGroupIds": [
    "metricGroup_123"
  ],
  "specificationIdsByMetricGroupId": {
    "metricGroup_123": [
      "specification_123"
    ]
  },
  "samplingPercentage": 10,
  "monthlyCreditCap": 500,
  "filterQuery": "refund, cancel, chargeback",
  "filterTarget": "EITHER",
  "excludeQuery": "test, internal",
  "excludeTarget": "EITHER",
  "messageConditions": [
    {
      "count": "messages",
      "operator": "gt",
      "value": 1
    }
  ],
  "status": "ACTIVE",
  "families": [
    {
      "metricGroupId": "metricGroup_123",
      "name": "Answer relevancy",
      "state": "ACTIVE",
      "metricId": "metric_123"
    }
  ],
  "createdAt": "2023-11-07T05:31:56Z",
  "deletedAt": "2023-11-07T05:31:56Z"
}

Authorizations

Authorization · string · header · required

API key authorization. Pass your API key in the Authorization header as a Bearer token. Both new (gsk_*) and legacy (gsk-) API keys are accepted, e.g. Authorization: Bearer gsk_... or Authorization: Bearer gsk-....

Body

application/json

productId · string · required

Minimum string length: 1

Example:

"prod_123"

name · string · required

Example:

"Production quality watch"

versionId · string | null

Optional version to narrow the monitor to. When null the monitor watches the whole product.

Example:

"version_123"

metricGroupIds · string[]

The metric families (Metric.metricGroupId) picked directly on the monitor. The list may be empty when specificationIds is set. The families the monitor scores are in scoredMetricGroupIds. The monitor binds the family, not a specific revision, so revising a metric is picked up automatically without editing the monitor.

Example:

["metricGroup_123"]

specificationIds · string[]

The Specifications (Specification.id) bound to the monitor. The monitor also scores the metrics each one links, so a metric added to or removed from a Specification takes effect on the next scan. Only Policy and Capability Specifications can be bound. At least one of metricGroupIds and specificationIds is required.

Example:

["specification_123"]

samplingPercentage · number · default: 10

Percentage of production sessions to evaluate (greater than 0, at most 100).

Required range: 0 < x <= 100

Example:

10

monthlyCreditCap · integer | null

Optional monthly credit ceiling for this monitor. When set it must be a positive integer; it may exceed the organization monthly allocation (spend is clamped to the available balance). Null means uncapped.

Required range: x >= 1

Example:

500

filterQuery · string | null

Optional content gate. Comma-separated terms; a session matches when at least one turn whose chosen target (filterTarget) contains ANY term (case-insensitive). Only matching sessions are sampled and evaluated; other sessions are skipped, spending no credits. Max 500 chars. Must be set together with filterTarget. Null means no content gate: every session that meets messageConditions is sampled.

Maximum string length: 500

Example:

"refund, cancel, chargeback"

filterTarget · enum<string> | null

Which side of a turn filterQuery is matched against: INPUT (the user turn), OUTPUT (the agent turn), or EITHER. Must be set together with filterQuery.

Available options: INPUT, OUTPUT, EITHER, null

Example:

"EITHER"

excludeQuery · string | null

Optional exclude gate. Comma-separated terms; a session is dropped when at least one turn whose chosen target (excludeTarget) contains ANY term (case-insensitive). Applied on top of filterQuery: a session passes the content gate only when it passes filterQuery (if set) AND is not hit by excludeQuery. Max 500 chars. Must be set together with excludeTarget. Null means exclude nothing.

Maximum string length: 500

Example:

"test, internal"

excludeTarget · enum<string> | null

Which side of a turn excludeQuery is matched against: INPUT (the user turn), OUTPUT (the agent turn), or EITHER. Must be set together with excludeQuery.

Available options: INPUT, OUTPUT, EITHER, null

Example:

"EITHER"

messageConditions · object[]

Conditions on the number of messages in a session, joined by AND: the monitor scores a session only when every condition holds. Sessions that fail are skipped and spend no credits. An empty list turns the filter off. A list no session can meet is refused, such as messages above 5 with messages at most 3, or more user messages than the messages allow: messages counts the user messages too. Defaults to messages above 1, which skips a session where only the agent spoke once.

Maximum array length: 10

Show child attributes

Example:

[
  {
    "count": "messages",
    "operator": "gt",
    "value": 1
  }
]

status · enum<string> · default: ACTIVE

Users may set ACTIVE or PAUSED; CAPPED and NO_CREDITS are system-set by the scanner, FAILING is reserved and never set yet, and all three are rejected on user writes.

Available options: ACTIVE, PAUSED, CAPPED, NO_CREDITS, FAILING

Example:

"ACTIVE"

Response

201

application/json

Monitor created successfully. The Location header holds its path. The body holds only the monitor id when the read after the write fails; read the monitor by that id.

Option 1

Option 2

id · string · required

Example:

"monitor_123"

productId · string · required

Example:

"prod_123"

versionId · string | null · required

Optional version to narrow the monitor to. When null the monitor watches the whole product.

Example:

"version_123"

userId · string | null · required

Example:

"user_123"

name · string · required

Example:

"Production quality watch"

metricGroupIds · string[] · required

The metric families (Metric.metricGroupId) picked directly on the monitor. The list may be empty when specificationIds is set. The families the monitor scores are in scoredMetricGroupIds. The monitor binds the family, not a specific revision, so revising a metric is picked up automatically without editing the monitor.

Example:

["metricGroup_123"]

specificationIds · string[] · required

The Specifications (Specification.id) bound to the monitor. The monitor also scores the metrics each one links, so a metric added to or removed from a Specification takes effect on the next scan. Only Policy and Capability Specifications can be bound.

Example:

["specification_123"]

scoredMetricGroupIds · string[] · required

Read-only. The metric families the monitor scores: metricGroupIds plus the families of its bound Specifications that can score production sessions.

Example:

["metricGroup_123"]

specificationIdsByMetricGroupId · object · required

Read-only. For each family a bound Specification brings, the ids of the bound Specifications that bring it.

Show child attributes

Example:

{ "metricGroup_123": ["specification_123"] }

samplingPercentage · number · default: 10 · required

Percentage of production sessions to evaluate (greater than 0, at most 100).

Required range: 0 < x <= 100

Example:

10

monthlyCreditCap · integer | null · required

Optional monthly credit ceiling for this monitor. When set it must be a positive integer; it may exceed the organization monthly allocation (spend is clamped to the available balance). Null means uncapped.

Required range: x >= 1

Example:

500

filterQuery · string | null · required

Optional content gate. Comma-separated terms; a session matches when at least one turn whose chosen target (filterTarget) contains ANY term (case-insensitive). Only matching sessions are sampled and evaluated; other sessions are skipped, spending no credits. Max 500 chars. Must be set together with filterTarget. Null means no content gate: every session that meets messageConditions is sampled.

Maximum string length: 500

Example:

"refund, cancel, chargeback"

filterTarget · enum<string> | null · required

Which side of a turn filterQuery is matched against: INPUT (the user turn), OUTPUT (the agent turn), or EITHER. Must be set together with filterQuery.

Available options: INPUT, OUTPUT, EITHER, null

Example:

"EITHER"

excludeQuery · string | null · required

Optional exclude gate. Comma-separated terms; a session is dropped when at least one turn whose chosen target (excludeTarget) contains ANY term (case-insensitive). Applied on top of filterQuery: a session passes the content gate only when it passes filterQuery (if set) AND is not hit by excludeQuery. Max 500 chars. Must be set together with excludeTarget. Null means exclude nothing.

Maximum string length: 500

Example:

"test, internal"

excludeTarget · enum<string> | null · required

Which side of a turn excludeQuery is matched against: INPUT (the user turn), OUTPUT (the agent turn), or EITHER. Must be set together with excludeQuery.

Available options: INPUT, OUTPUT, EITHER, null

Example:

"EITHER"

messageConditions · object[] · required

Conditions on the number of messages in a session, joined by AND: the monitor scores a session only when every condition holds. Sessions that fail are skipped and spend no credits. An empty list turns the filter off.

Maximum array length: 10

Show child attributes

Example:

[
  {
    "count": "messages",
    "operator": "gt",
    "value": 1
  }
]

status · enum<string> · default: ACTIVE · required

Users may set ACTIVE or PAUSED; CAPPED and NO_CREDITS are system-set by the scanner, FAILING is reserved and never set yet, and all three are rejected on user writes.

Available options: ACTIVE, PAUSED, CAPPED, NO_CREDITS, FAILING

Example:

"ACTIVE"

families · object[] · required

Read-only. Every family in scoredMetricGroupIds with its state, so a family that no longer scores stays visible and can be removed.

Show child attributes

createdAt · string<date-time> · required

deletedAt · string<date-time> | null · required