Create Version

POSThttps://api.confident-ai.com/v2/organization/governance-controls/{controlId}/versions

Changes what a governance control checks by appending a new version of its definition. The version that was current is not edited or removed — it stays in the history with the verdicts computed against it, and the new version becomes the current one, which is what the next assessment runs against. Existing verdicts are neither recomputed nor migrated, so a control's assessment history is read one version at a time.

Which request shape is expected follows the control's own type: a pre-deployment control takes the pre-deployment config, and every other type takes the runtime config. Every field is required even when null — the only field carried over from the previous version is extraQueryParams, and only when you omit it — so send the definition you want in full rather than a patch.

POST/v2/organization/governance-controls/{controlId}/versions

curl -X POST "https://api.confident-ai.com/v2/organization/governance-controls/{controlId}/versions" \
  -H "CONFIDENT_API_KEY: <ORGANIZATION-API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "dataModel": "TRACE",
  "aggregation": "Avg cost",
  "thresholdSettings": {
    "value": 0.02,
    "direction": "above"
  },
  "extraQueryParams": {
    "category": "TRACE"
  },
  "filters": {
    "operator": "AND",
    "groups": [
      {
        "operator": "AND",
        "filters": [
          {
            "category": "User Id",
            "condition": "Is less than",
            "value": "string",
            "key": "string"
          }
        ]
      }
    ]
  },
  "severity": "CRITICAL"
}'

200

{
  "success": true,
  "data": {
    "id": "<GOVERNANCE-CONTROL-VERSION-ID>",
    "version": "00.00.02",
    "sequence": 2,
    "dataModel": "TRACE",
    "aggregation": "Error rate",
    "thresholdSettings": {
      "value": 0.02,
      "direction": "above"
    },
    "extraQueryParams": {
      "category": "TRACE"
    },
    "preDeploymentSettings": {
      "identifier": "pre-release",
      "window": {
        "days": 30
      },
      "officialOnly": false
    },
    "filters": {
      "operator": "AND",
      "groups": [
        {
          "operator": "AND",
          "filters": [
            {
              "category": "User Id",
              "condition": "Is less than",
              "value": "string",
              "key": "string"
            }
          ]
        }
      ]
    },
    "severity": "CRITICAL",
    "assessmentsCount": 64,
    "createdAt": "2025-01-18T16:45:00.000Z"
  },
  "link": "https://app.confident-ai.com/organization/<ORGANIZATION-ID>/governance/controls/<GOVERNANCE-CONTROL-ID>",
  "deprecated": false
}

Headers

CONFIDENT_API_KEYstringRequired
The organization API key for your Confident AI organization.

Path parameters

controlIdstringRequired
The id of the governance control.

Request body

Runtime Control Configobject
The rule a RUNTIME control evaluates, read as one sentence: aggregate aggregation over dataModel for the trailing 24 hours, restricted to filters, and fail when the result sits on the direction side of the threshold. Aggregating Error rate over TRACE against a threshold of 0.02 above fails a project whose traces errored on more than 2% of requests in the last day. The window is fixed and is not part of the definition. The aggregation has to be one the data model supports.
Show 6 propertiesHide 6 properties
- dataModelenum | nullRequired
  The production data a runtime control measures: TRACE for whole requests, SPAN for individual steps, THREAD for conversations, METRIC_DATA for evaluation scores, and ANNOTATION for human ratings. It decides which aggregations are valid.
  Show 5 enum valuesHide 5 enum values
  - TRACE
  - SPAN
  - THREAD
  - METRIC_DATA
  - ANNOTATION
- aggregationenum | nullRequired
  How a runtime control reduces the data it measures to the single number it compares against its threshold. Each aggregation is only valid for some data models — Avg score and Pass rate need METRIC_DATA, Avg rating needs ANNOTATION, Input tokens needs SPAN — and a pairing the selected dataModel does not support is rejected.
  Show 22 enum valuesHide 22 enum values
  - Avg cost
  - Avg latency
  - Avg rating
  - Avg score
  - Count
  - Error count
  - Error rate
  - Failure rate
  - Input cost
  - Input tokens
  - Median score
  - Output cost
  - Output tokens
  - P50 latency
  - P90 latency
  - P99 latency
  - Pass rate
  - Total cost
  - Total tokens
  - Unique end users
  - Unique metadata values
  - Unique threads
- thresholdSettingsobject | nullRequired
  The comparison that turns a runtime control's measured value into a verdict.
  Show 2 propertiesHide 2 properties
  - valuenumberRequired
    The number the aggregated value is compared against, in the unit the aggregation produces — a rate is a fraction between 0 and 1, a latency is in milliseconds, a cost is in USD.
  - directionenumRequired
    Which side of the threshold fails: above fails once the measured value rises past value, below fails once it drops under it.
    Show 2 enum valuesHide 2 enum values
    above
    below
- extraQueryParamsobject | null
  Extra scoping for the data a runtime control measures, beyond its data model and filters.
  Show 1 propertyHide 1 property
  - categoryenum
    Which kind of item the evaluation scores were recorded on, for a control measuring METRIC_DATA.
    Show 3 enum valuesHide 3 enum values
    TRACE
    SPAN
    THREAD
- filtersobject | nullRequired
  A set of filter groups combined by a top-level operator. Each group combines its filter rows by its own operator, and each row matches one property, such as Name or User Id, against a value with a condition such as Is or Contains.
  Show 2 propertiesHide 2 properties
  - operatorenumRequired
    Show 2 enum valuesHide 2 enum values
    AND
    OR
  - groupslist of objectsRequired
    Show 2 propertiesHide 2 properties
    operatorenumRequired
    Show 2 enum valuesHide 2 enum values
    AND
    OR
    filterslist of objectsRequired
    Show 4 propertiesHide 4 properties
    categoryenumRequired
    Show 80 enum valuesHide 80 enum values
    User Id
    Thread Id
    Trace Uuid
    Trace Name
    Trace Version
    Trace Status
    Trace Tags
    Trace
    Span Uuid
    Name
    Span Name
    Span Type
    Span Status
    Metrics Status
    Error Status
    Name
    Model
    Provider
    Integration
    Embedder
    Chunk Size
    Top-K
    Hyperparameter
    Dataset
    Dataset Name
    Test Run ID
    Identifier
    Test File
    Status
    Official
    Evals Mode
    Tests Passed
    Tests Failed
    Pass Rate
    Fail Rate
    Star Rating
    Thumbs Rating
    Explanation
    Expected Output
    Expected Outcome
    Annotator
    End User
    Annotation Type
    Annotation Name
    Criteria
    Annotation Date
    Metric Score
    Metric Status
    Name
    Metadata
    Classifier
    Metric
    Metric Name
    Trace Count
    Test Case ID
    Requested review from
    Assigned to
    Tags
    Labels
    Tools Called
    Finalized
    Golden ID
    Ingestion Task
    Latency
    Environment
    Review flag
    Vulnerability
    Vulnerability Type
    Attack Method
    Risk Category
    Framework
    Assessment ID
    Prompt Alias
    Prompt Version
    Prompt Label
    Prompt Commit Hash
    Prompt
    Annotations
    Status Code
    Actor Type
    conditionenum | enum | enum | enum | enum | enum | enum | enum | enum | enumRequired
    Show 10 variantsHide 10 variants
    enum
    Show 6 enum valuesHide 6 enum values
    Is less than
    Is equal or less than
    Is greater than
    Is equal or greater than
    Is equal to
    Does not equal
    OR
    enum
    Show 2 enum valuesHide 2 enum values
    Has
    Has not
    OR
    enum
    Show 2 enum valuesHide 2 enum values
    Is
    Is not
    OR
    enum
    Show 2 enum valuesHide 2 enum values
    Is one of
    Is not one of
    OR
    enum
    Show 4 enum valuesHide 4 enum values
    Is
    Is not
    Is empty
    Is not empty
    OR
    enum
    Show 2 enum valuesHide 2 enum values
    Contains
    Does not contain
    OR
    enum
    Show 3 enum valuesHide 3 enum values
    Contains
    Contains only
    Does not contain
    OR
    enum
    Show 4 enum valuesHide 4 enum values
    Has decreased by more than
    Has decreased by less than
    Has increased by more than
    Has increased by less than
    OR
    enum
    Show 1 enum valueHide 1 enum value
    Has changed from
    OR
    enum
    Show 1 enum valueHide 1 enum value
    Is between
    valuestring | number | list of stringsRequired
    Show 3 variantsHide 3 variants
    string
    OR
    number
    OR
    list of strings
    keystring
- severityenum | nullRequired
  How much a failing control matters, set per version rather than per control. LOW never blocks a deployment gate; CRITICAL, HIGH and MEDIUM block, and so does leaving the severity unset.
  Show 4 enum valuesHide 4 enum values
  - CRITICAL
  - HIGH
  - MEDIUM
  - LOW
OR
Pre-Deployment Control Configobject
The rule a PRE_DEPLOYMENT_EVALS or PRE_DEPLOYMENT_RED_TEAMING control evaluates, read as one sentence: find the project's newest completed run whose identifier is identifier within the last window.days days, and pass when that run satisfies filters. An identifier of pre-release with a 30-day window and a filter of Pass rate >= 0.9 fails a project whose last pre-release run scored below 90%, and reports NO_DATA when it has not run one at all. PRE_DEPLOYMENT_EVALS looks at test runs and PRE_DEPLOYMENT_RED_TEAMING at red teaming runs; the endpoint picks which by the control's own type, so the same shape serves both. Send a non-empty identifier unless officialOnly is true.
Show 5 propertiesHide 5 properties
- identifierstringRequired
  The identifier of the run to gate on, as sent when the test run or red teaming run was created. Send an empty string when officialOnly is true.
- windowobjectRequired
  The rolling lookback a pre-deployment control searches for the run it gates on.
  Show 1 propertyHide 1 property
  - daysintegerRequired
    How many days back the control looks for a run. It is stored as a day count rather than as dates, so the gate does not go stale as it is re-assessed.
- officialOnlyboolean
  Gate on the project's most recent official run instead of on a run matching identifier, which ignores identifier and the window. Defaults to false.
- filtersobject | nullRequired
  A set of filter groups combined by a top-level operator. Each group combines its filter rows by its own operator, and each row matches one property, such as Name or User Id, against a value with a condition such as Is or Contains.
  Show 2 propertiesHide 2 properties
  - operatorenumRequired
    Show 2 enum valuesHide 2 enum values
    AND
    OR
  - groupslist of objectsRequired
    Show 2 propertiesHide 2 properties
    operatorenumRequired
    Show 2 enum valuesHide 2 enum values
    AND
    OR
    filterslist of objectsRequired
    Show 4 propertiesHide 4 properties
    categoryenumRequired
    Show 80 enum valuesHide 80 enum values
    User Id
    Thread Id
    Trace Uuid
    Trace Name
    Trace Version
    Trace Status
    Trace Tags
    Trace
    Span Uuid
    Name
    Span Name
    Span Type
    Span Status
    Metrics Status
    Error Status
    Name
    Model
    Provider
    Integration
    Embedder
    Chunk Size
    Top-K
    Hyperparameter
    Dataset
    Dataset Name
    Test Run ID
    Identifier
    Test File
    Status
    Official
    Evals Mode
    Tests Passed
    Tests Failed
    Pass Rate
    Fail Rate
    Star Rating
    Thumbs Rating
    Explanation
    Expected Output
    Expected Outcome
    Annotator
    End User
    Annotation Type
    Annotation Name
    Criteria
    Annotation Date
    Metric Score
    Metric Status
    Name
    Metadata
    Classifier
    Metric
    Metric Name
    Trace Count
    Test Case ID
    Requested review from
    Assigned to
    Tags
    Labels
    Tools Called
    Finalized
    Golden ID
    Ingestion Task
    Latency
    Environment
    Review flag
    Vulnerability
    Vulnerability Type
    Attack Method
    Risk Category
    Framework
    Assessment ID
    Prompt Alias
    Prompt Version
    Prompt Label
    Prompt Commit Hash
    Prompt
    Annotations
    Status Code
    Actor Type
    conditionenum | enum | enum | enum | enum | enum | enum | enum | enum | enumRequired
    Show 10 variantsHide 10 variants
    enum
    Show 6 enum valuesHide 6 enum values
    Is less than
    Is equal or less than
    Is greater than
    Is equal or greater than
    Is equal to
    Does not equal
    OR
    enum
    Show 2 enum valuesHide 2 enum values
    Has
    Has not
    OR
    enum
    Show 2 enum valuesHide 2 enum values
    Is
    Is not
    OR
    enum
    Show 2 enum valuesHide 2 enum values
    Is one of
    Is not one of
    OR
    enum
    Show 4 enum valuesHide 4 enum values
    Is
    Is not
    Is empty
    Is not empty
    OR
    enum
    Show 2 enum valuesHide 2 enum values
    Contains
    Does not contain
    OR
    enum
    Show 3 enum valuesHide 3 enum values
    Contains
    Contains only
    Does not contain
    OR
    enum
    Show 4 enum valuesHide 4 enum values
    Has decreased by more than
    Has decreased by less than
    Has increased by more than
    Has increased by less than
    OR
    enum
    Show 1 enum valueHide 1 enum value
    Has changed from
    OR
    enum
    Show 1 enum valueHide 1 enum value
    Is between
    valuestring | number | list of stringsRequired
    Show 3 variantsHide 3 variants
    string
    OR
    number
    OR
    list of strings
    keystring
- severityenum | nullRequired
  How much a failing control matters, set per version rather than per control. LOW never blocks a deployment gate; CRITICAL, HIGH and MEDIUM block, and so does leaving the severity unset.
  Show 4 enum valuesHide 4 enum values
  - CRITICAL
  - HIGH
  - MEDIUM
  - LOW

Response

Create Version succeeded.

successboolean
Indicates if the request was successful.
dataobject
An immutable snapshot of what a control checks. Which fields are populated follows the control's type: a runtime control carries dataModel, aggregation and thresholdSettings, a pre-deployment control carries preDeploymentSettings, and an OPERATIONAL control carries neither because its check ships with the platform. Editing a control appends a new version rather than changing this one, so every past verdict keeps pointing at the definition it was computed against.
Show 12 propertiesHide 12 properties
- idstring
  The id of the version, generated by Confident AI.
- versionstring
  The human-readable label for sequence, written as three two-digit groups that roll over at 100, so sequence 2 is 00.00.02 and sequence 100 is 00.01.00.
- sequenceinteger
  The position of this version in the control's history, counting from 1. The highest sequence is the current version, which is the one every new assessment runs against.
- dataModelenum | null
  The production data a runtime control measures: TRACE for whole requests, SPAN for individual steps, THREAD for conversations, METRIC_DATA for evaluation scores, and ANNOTATION for human ratings. It decides which aggregations are valid.
  Show 5 enum valuesHide 5 enum values
  - TRACE
  - SPAN
  - THREAD
  - METRIC_DATA
  - ANNOTATION
- aggregationstring | null
  How the measured data is reduced to one number, as one of the GovernanceControlAggregation values. It is set on a runtime control and null on every other type.
- thresholdSettingsobject | null
  A threshold as a version stores it. Both fields are set on a configured runtime control; either can be absent on a version snapshotted before the control was configured, which is what makes it unconfigured.
  Show 2 propertiesHide 2 properties
  - valuenumber
    The number the aggregated value is compared against, in the unit the aggregation produces — a rate is a fraction between 0 and 1, a latency is in milliseconds, a cost is in USD.
  - directionenum
    Which side of the threshold fails: above fails once the measured value rises past value, below fails once it drops under it.
    Show 2 enum valuesHide 2 enum values
    above
    below
- extraQueryParamsobject | null
  Extra scoping for the data a runtime control measures, beyond its data model and filters.
  Show 1 propertyHide 1 property
  - categoryenum
    Which kind of item the evaluation scores were recorded on, for a control measuring METRIC_DATA.
    Show 3 enum valuesHide 3 enum values
    TRACE
    SPAN
    THREAD
- preDeploymentSettingsobject | null
  Which run a pre-deployment control gates on. The fields are individually optional because a version snapshotted before the control was configured stores an empty object; a configured control always carries either identifier and window or officialOnly set to true.
  Show 3 propertiesHide 3 properties
  - identifierstring
    The identifier of the test run or red teaming run the control gates on. Absent on a control that gates on the project's official run instead.
  - windowobject
    The rolling lookback a pre-deployment control searches for the run it gates on.
    Show 1 propertyHide 1 property
    daysinteger
    How many days back the control looks for a run. It is stored as a day count rather than as dates, so the gate does not go stale as it is re-assessed.
  - officialOnlyboolean
    Whether the control gates on the project's most recent official run rather than on a run matching identifier.
- filtersobject | null
  A set of filter groups combined by a top-level operator. Each group combines its filter rows by its own operator, and each row matches one property, such as Name or User Id, against a value with a condition such as Is or Contains.
  Show 2 propertiesHide 2 properties
  - operatorenum
    Show 2 enum valuesHide 2 enum values
    AND
    OR
  - groupslist of objects
    Show 2 propertiesHide 2 properties
    operatorenum
    Show 2 enum valuesHide 2 enum values
    AND
    OR
    filterslist of objects
    Show 4 propertiesHide 4 properties
    categoryenum
    Show 80 enum valuesHide 80 enum values
    User Id
    Thread Id
    Trace Uuid
    Trace Name
    Trace Version
    Trace Status
    Trace Tags
    Trace
    Span Uuid
    Name
    Span Name
    Span Type
    Span Status
    Metrics Status
    Error Status
    Name
    Model
    Provider
    Integration
    Embedder
    Chunk Size
    Top-K
    Hyperparameter
    Dataset
    Dataset Name
    Test Run ID
    Identifier
    Test File
    Status
    Official
    Evals Mode
    Tests Passed
    Tests Failed
    Pass Rate
    Fail Rate
    Star Rating
    Thumbs Rating
    Explanation
    Expected Output
    Expected Outcome
    Annotator
    End User
    Annotation Type
    Annotation Name
    Criteria
    Annotation Date
    Metric Score
    Metric Status
    Name
    Metadata
    Classifier
    Metric
    Metric Name
    Trace Count
    Test Case ID
    Requested review from
    Assigned to
    Tags
    Labels
    Tools Called
    Finalized
    Golden ID
    Ingestion Task
    Latency
    Environment
    Review flag
    Vulnerability
    Vulnerability Type
    Attack Method
    Risk Category
    Framework
    Assessment ID
    Prompt Alias
    Prompt Version
    Prompt Label
    Prompt Commit Hash
    Prompt
    Annotations
    Status Code
    Actor Type
    conditionenum | enum | enum | enum | enum | enum | enum | enum | enum | enum
    Show 10 variantsHide 10 variants
    enum
    Show 6 enum valuesHide 6 enum values
    Is less than
    Is equal or less than
    Is greater than
    Is equal or greater than
    Is equal to
    Does not equal
    OR
    enum
    Show 2 enum valuesHide 2 enum values
    Has
    Has not
    OR
    enum
    Show 2 enum valuesHide 2 enum values
    Is
    Is not
    OR
    enum
    Show 2 enum valuesHide 2 enum values
    Is one of
    Is not one of
    OR
    enum
    Show 4 enum valuesHide 4 enum values
    Is
    Is not
    Is empty
    Is not empty
    OR
    enum
    Show 2 enum valuesHide 2 enum values
    Contains
    Does not contain
    OR
    enum
    Show 3 enum valuesHide 3 enum values
    Contains
    Contains only
    Does not contain
    OR
    enum
    Show 4 enum valuesHide 4 enum values
    Has decreased by more than
    Has decreased by less than
    Has increased by more than
    Has increased by less than
    OR
    enum
    Show 1 enum valueHide 1 enum value
    Has changed from
    OR
    enum
    Show 1 enum valueHide 1 enum value
    Is between
    valuestring | number | list of strings
    Show 3 variantsHide 3 variants
    string
    OR
    number
    OR
    list of strings
    keystring
- severityenum | null
  How much a failing control matters, set per version rather than per control. LOW never blocks a deployment gate; CRITICAL, HIGH and MEDIUM block, and so does leaving the severity unset.
  Show 4 enum valuesHide 4 enum values
  - CRITICAL
  - HIGH
  - MEDIUM
  - LOW
- assessmentsCountinteger
  How many verdicts were recorded against this version.
- createdAtstring
  When this version was snapshotted.
linkstring
This is the URL of the resource on the Confident AI platform.
deprecatedboolean
Indicates if this endpoint is deprecated.

Built byConfident AI