> ## Documentation Index
> Fetch the complete documentation index at: https://docs.galtea.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Create revision

> Create a revision of a metric, from its active revision or from the revision that `parentRevisionId` names. The new revision becomes the active one, and the old active one becomes legacy. A revision keeps the metric's name, description, tags and evaluation type, so the body takes its own `name`, the judge settings and links only. See [Metrics](https://docs.galtea.ai/concepts/metric).



## OpenAPI

````yaml /openapi.json post /v2/revisions
openapi: 3.0.0
info:
  version: 1.0.0
  title: Product Management Service API
  description: API documentation for Product Management Service
  contact:
    name: Galtea AI
servers:
  - url: https://api.galtea.ai
security:
  - bearerAuth: []
tags: []
externalDocs:
  description: Galtea Platform Documentation
  url: https://docs.galtea.ai
paths:
  /v2/revisions:
    post:
      tags:
        - revisions
      summary: Create revision
      description: >-
        Create a revision of a metric, from its active revision or from the
        revision that `parentRevisionId` names. The new revision becomes the
        active one, and the old active one becomes legacy. A revision keeps the
        metric's name, description, tags and evaluation type, so the body takes
        its own `name`, the judge settings and links only. See
        [Metrics](https://docs.galtea.ai/concepts/metric).
      operationId: createRevision
      parameters:
        - $ref: '#/components/parameters/Prefer'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRevisionBody'
      responses:
        '201':
          description: >-
            Revision created successfully. On `Prefer: return=minimal`, or when
            the read after the write fails, the answer has no body.
          headers:
            Location:
              schema:
                type: string
                description: The path of the new resource
              required: true
              description: The path of the new resource
            Content-Location:
              schema:
                type: string
                description: >-
                  The path of the resource in the body; absent when there is no
                  body
              required: false
              description: >-
                The path of the resource in the body; absent when there is no
                body
            Preference-Applied:
              schema:
                type: string
                enum:
                  - return=minimal
                description: 'Present when the API honored `Prefer: return=minimal`'
              required: false
              description: 'Present when the API honored `Prefer: return=minimal`'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Revision'
        '400':
          description: >-
            Invalid request body, an unknown field such as `source`, a name of
            "R" followed by digits other than the revision's own label, a metric
            with no active revision, or a metric the caller does not own, such
            as a Galtea metric
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: The caller may not read or update the metric
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Metric, parent revision, user group or specification not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: >-
            Another live revision of the metric, legacy ones included, already
            has this name
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - bearerAuth: []
components:
  parameters:
    Prefer:
      schema:
        $ref: '#/components/schemas/Prefer'
      required: false
      description: >-
        Send `return=minimal` to get no body back from a write and skip reading
        the resource: a create answers `201` with only `Location`, and an update
        answers `204`.
      name: Prefer
      in: header
  schemas:
    CreateRevisionBody:
      type: object
      properties:
        metricId:
          type: string
          minLength: 1
          example: metric_123
          description: >-
            The metric to revise. The new revision becomes the metric's active
            one, and the previous active one becomes legacy.
        parentRevisionId:
          type: string
          minLength: 1
          example: revision_123
          description: >-
            The revision of the metric to revise from. Defaults to the metric's
            active revision. A revision of another metric answers 404.
        name:
          type: string
          minLength: 1
          maxLength: 200
          example: stricter rubric
          description: >-
            The revision's own name. It shows as "R3: stricter rubric". Omit it
            to leave the revision with none, so it shows as its label, "R3". A
            name equal to the metric's name or to the revision's own label
            stores none. "R" followed by digits is refused unless it is the
            revision's own label. Unique among the live revisions of the metric,
            legacy ones included, ignoring case.
        definition:
          type: string
          nullable: true
        judgePrompt:
          type: string
          nullable: true
          maxLength: 20000
        evaluatorModelName:
          type: string
          nullable: true
          example: gpt-4.1
          description: >-
            Required for PARTIAL_PROMPT. For CLASSIFIER: The selectable
            classifier model to run the question under, as listed by `GET
            /evaluatorModels` with `kind=CLASSIFIER` and `selectable=true`.
            Omitted or null, the one selectable classifier model is used. When
            several are selectable, the request is refused with 400 and this
            field must be sent.
        evaluationParams:
          type: array
          nullable: true
          items:
            type: string
            minLength: 1
            maxLength: 64
          maxItems: 20
          example:
            - input
            - actual_output
        areEvalParamsTop:
          type: boolean
          nullable: true
        judgeGenerationSettings:
          type: object
          nullable: true
          properties:
            temperature:
              type: number
              nullable: true
              minimum: 0
              example: 0.3
            topP:
              type: number
              nullable: true
              minimum: 0
              maximum: 1
              example: 0.9
            maxOutputTokens:
              type: integer
              nullable: true
              minimum: 1
              example: 512
              description: >-
                A new metric needs at least 256, so the judge's structured
                answer fits. A metric stored before that floor keeps its cap.
            reasoningEffort:
              type: string
              nullable: true
              example: low
          additionalProperties: false
          description: >-
            The generation settings this metric's judge runs with. Immutable:
            changing one creates a revision. Only the settings `GET
            /evaluatorModels` reports as configurable for the chosen model take
            effect; a value the provider rejects ends that evaluation as SKIPPED
            carrying the provider's own message.
        passThreshold:
          type: number
          nullable: true
          minimum: 0
          maximum: 1
          example: 0.7
          description: >-
            Score from 0 to 1 at or above which an evaluation of this metric
            passes. Omitted or null, it defaults to 0.5, or to the parent
            metric's threshold for a revision.
        applicabilityScope:
          type: string
          nullable: true
          enum:
            - NONE
            - DEVELOPMENT
            - PRODUCTION
            - ALL
          example: PRODUCTION
          description: >-
            Which sessions get the applicability check before this metric is
            judged: `PRODUCTION`, `DEVELOPMENT`, `ALL` or `NONE` (no check). A
            session the check finds the metric does not apply to is skipped and
            no judge call is made. Omitted or null, it defaults to `PRODUCTION`
            for a metric the platform scores and `NONE` for any other. A
            revision keeps the parent metric's value when the check runs for
            both. Fixed at create: a change creates a revision. Any value but
            `NONE` is refused with a 400 for a metric the platform does not
            score. A metric that scores only `traces` is never checked, so it
            takes `NONE` and refuses any other value. A metric that also scores
            another field is checked without `traces`: on each turn's input and
            actual output and its other fields. A FULL_PROMPT metric with empty
            evaluationParams whose judge prompt reads only `traces` is stored as
            checked, yet the evaluator judges it without the check. A
            FULL_PROMPT metric whose evaluationParams list only `traces` takes
            NONE even when its judge prompt reads another field: list that field
            in evaluationParams to get the check. The check runs only where the
            deployment enables it.
        applicabilityThreshold:
          type: number
          nullable: true
          minimum: 0
          maximum: 1
          example: 0.7
          description: >-
            The lowest probability, from 0 to 1, that the metric applies to a
            session at which it is judged. Below it, the session is skipped.
            Omitted or null, it defaults to 0.5, or to the parent metric's value
            for a revision when the check runs for both. Fixed at create: a
            change creates a revision. Refused with a 400 for a metric the
            platform does not score, and for a metric that scores only `traces`.
            The check runs only where the deployment enables it.
        classifierQuestion:
          type: object
          nullable: true
          properties:
            type:
              type: string
              enum:
                - yes_no
                - scale
            instructions:
              type: string
              maxLength: 2000
              description: >-
                The question, in English, naming at least one {{
                evaluation_param }}.
            goodAnswer:
              type: string
              nullable: true
              enum:
                - 'yes'
                - 'no'
              description: yes_no only, and required there.
            criteria:
              type: object
              nullable: true
              properties:
                'yes':
                  type: string
                  nullable: true
                  maxLength: 1000
                'no':
                  type: string
                  nullable: true
                  maxLength: 1000
              description: 'yes_no only: what yes and no mean.'
            levels:
              type: array
              nullable: true
              items:
                type: object
                properties:
                  description:
                    type: string
                    maxLength: 1000
                  score:
                    type: number
                    nullable: true
                    description: >-
                      From 0 to 1. Omit it on every level to space the scores
                      evenly from 0 (worst) to 1 (best).
                required:
                  - description
              maxItems: 10
              description: >-
                scale only: the scored levels, worst first, with non-decreasing
                scores.
            doesNotApply:
              type: string
              nullable: true
              maxLength: 1000
              description: >-
                scale only: the text of an extra level that skips the evaluation
                when the classifier picks it.
          required:
            - type
            - instructions
          description: >-
            CLASSIFIER only, and required there: the one question the classifier
            answers. evaluationParams is derived from its {{ param }}
            placeholders.
        userGroupIds:
          type: array
          nullable: true
          items:
            type: string
            minLength: 1
          example:
            - ug_123
          description: >-
            User groups to link to the revision. Required for a Human Evaluation
            metric.
        specificationIds:
          type: array
          nullable: true
          items:
            type: string
            minLength: 1
          example:
            - spec_123
          description: Specifications to link to the revision.
      required:
        - metricId
      additionalProperties: false
    Revision:
      type: object
      properties:
        id:
          type: string
          example: revision_123
          description: Revision ID.
        metricId:
          type: string
          example: metric_123
          description: The metric this revision belongs to.
        number:
          type: integer
          minimum: 0
          exclusiveMinimum: true
          example: 3
          description: >-
            The revision number within its metric, allocated once when the
            revision is created and never reused. The revision shows as "R"
            followed by this number, so 3 is "R3".
        parentRevisionId:
          type: string
          nullable: true
          example: revision_122
          description: >-
            The revision this one was revised from. Null for the first revision
            of a metric.
        name:
          type: string
          nullable: true
          example: Accuracy (strict judge)
          description: >-
            The name this revision was saved under, when it differs from its
            metric's name. Null otherwise: read the metric for its name.
        isActive:
          type: boolean
          readOnly: true
          description: >-
            Whether this is the active revision of its metric: its own legacy
            date is unset, it is not deleted and it is not being optimized.
        legacyAt:
          type: string
          nullable: true
          format: date-time
          readOnly: true
          description: >-
            Earliest non-null of this revision's own legacy date and its
            evaluator model's `unselectableAt`, once that date has passed.
        disabledAt:
          type: string
          nullable: true
          format: date-time
          readOnly: true
          description: >-
            Earliest non-null of the metric's disabled date and this revision's
            evaluator model's `disabledAt`.
        definition:
          type: string
          nullable: true
          description: >-
            Name of the built-in evaluator the metric runs, for example
            `json_field_match`. Null when the metric names none.
        judgePrompt:
          type: string
          nullable: true
          example: Evaluate the accuracy of the response
        evaluatorModelName:
          type: string
          nullable: true
          example: gpt-4
        evaluationParams:
          type: array
          items:
            type: string
          example:
            - input
            - actual_output
            - expected_output
          description: >-
            Ordered list of trace fields the evaluator needs, written in
            snake_case (e.g. `input`, `actual_output`, `expected_output`,
            `retrieval_context`). Determines which data the evaluation engine
            extracts from each trace. Full list of accepted values:
            https://docs.galtea.ai/concepts/metric/evaluation-parameters
        areEvalParamsTop:
          type: boolean
          nullable: true
          description: >-
            When true, evaluationParams are injected at the top level of the
            evaluator prompt instead of nested inside the conversation context.
        judgeGenerationSettings:
          type: object
          nullable: true
          properties:
            temperature:
              type: number
              nullable: true
              minimum: 0
              example: 0.3
            topP:
              type: number
              nullable: true
              minimum: 0
              maximum: 1
              example: 0.9
            maxOutputTokens:
              type: integer
              nullable: true
              minimum: 1
              example: 512
              description: >-
                A new metric needs at least 256, so the judge's structured
                answer fits. A metric stored before that floor keeps its cap.
            reasoningEffort:
              type: string
              nullable: true
              example: low
          additionalProperties: false
          description: >-
            The generation settings this metric's judge runs with. Null runs the
            platform defaults. Immutable: changing one creates a revision.
        passThreshold:
          type: number
          minimum: 0
          maximum: 1
          example: 0.7
          description: >-
            Score from 0 to 1 at or above which an evaluation of this metric
            passes. Immutable: changing it creates a revision.
        applicabilityScope:
          type: string
          enum:
            - NONE
            - DEVELOPMENT
            - PRODUCTION
            - ALL
          example: PRODUCTION
          description: >-
            Which sessions get the applicability check before this metric is
            judged. `NONE` for a metric the platform does not score. A metric
            that scores only `traces` is never checked, so it takes `NONE` and
            refuses any other value. A metric that also scores another field is
            checked without `traces`: on each turn's input and actual output and
            its other fields. A FULL_PROMPT metric with empty evaluationParams
            whose judge prompt reads only `traces` is stored as checked, yet the
            evaluator judges it without the check. A FULL_PROMPT metric whose
            evaluationParams list only `traces` takes NONE even when its judge
            prompt reads another field: list that field in evaluationParams to
            get the check. Immutable: changing it creates a revision. The check
            runs only where the deployment enables it.
        applicabilityThreshold:
          type: number
          nullable: true
          minimum: 0
          maximum: 1
          example: 0.7
          description: >-
            The lowest probability that the metric applies to a session at which
            it is judged. Null means the platform default, 0.5. Immutable:
            changing it creates a revision.
        classifierQuestion:
          allOf:
            - $ref: '#/components/schemas/ClassifierQuestion'
            - nullable: true
              description: >-
                The one question of a CLASSIFIER metric; null for every other
                source.
        isBeingOptimized:
          type: boolean
          readOnly: true
          description: Whether the metric is currently being optimized.
        optimizationStatus:
          type: string
          nullable: true
          enum:
            - OPTIMIZING
            - READY_FOR_REVIEW
            - FAILED
            - NO_IMPROVEMENT
            - DECLINED
            - ACTIVATED
          readOnly: true
          example: READY_FOR_REVIEW
          description: >-
            Where an optimization attempt stands. Null for a metric that did not
            come from an optimization. A candidate waiting for review is legacy
            until it is activated.
        optimizationValidation:
          type: object
          nullable: true
          properties:
            used:
              type: boolean
              description: >-
                Whether any evaluation was held out for validation. False when
                none was: too few annotated evaluations and no session kept from
                an earlier attempt, or no session was eligible for the hold-out.
            heldOutEvaluationIds:
              type: array
              items:
                type: string
              description: >-
                Evaluations held out of the search. Empty when no validation set
                was used.
              example:
                - evaluation_123
            results:
              type: object
              nullable: true
              properties:
                optimization:
                  type: object
                  properties:
                    rowsScored:
                      type: integer
                      minimum: 0
                      description: Rows both prompts scored. Only these rows are compared.
                      example: 25
                    rowsTotal:
                      type: integer
                      minimum: 0
                      description: Rows in the set.
                      example: 25
                    source:
                      type: object
                      properties:
                        correct:
                          type: integer
                          minimum: 0
                          description: >-
                            Rows where the AI verdict matches the human label. A
                            score at or above the metric's pass threshold is a
                            positive verdict.
                          example: 20
                        alignment:
                          type: number
                          nullable: true
                          description: >-
                            Alignment between the AI scores and the human labels
                            on the compared rows. Null when undefined.
                          example: 0.71
                      required:
                        - correct
                        - alignment
                      additionalProperties: false
                    candidate:
                      type: object
                      properties:
                        correct:
                          type: integer
                          minimum: 0
                          description: >-
                            Rows where the AI verdict matches the human label. A
                            score at or above the metric's pass threshold is a
                            positive verdict.
                          example: 20
                        alignment:
                          type: number
                          nullable: true
                          description: >-
                            Alignment between the AI scores and the human labels
                            on the compared rows. Null when undefined.
                          example: 0.71
                      required:
                        - correct
                        - alignment
                      additionalProperties: false
                  required:
                    - rowsScored
                    - rowsTotal
                    - source
                    - candidate
                  additionalProperties: false
                validation:
                  type: object
                  properties:
                    rowsScored:
                      type: integer
                      minimum: 0
                      description: Rows both prompts scored. Only these rows are compared.
                      example: 25
                    rowsTotal:
                      type: integer
                      minimum: 0
                      description: Rows in the set.
                      example: 25
                    source:
                      type: object
                      properties:
                        correct:
                          type: integer
                          minimum: 0
                          description: >-
                            Rows where the AI verdict matches the human label. A
                            score at or above the metric's pass threshold is a
                            positive verdict.
                          example: 20
                        alignment:
                          type: number
                          nullable: true
                          description: >-
                            Alignment between the AI scores and the human labels
                            on the compared rows. Null when undefined.
                          example: 0.71
                      required:
                        - correct
                        - alignment
                      additionalProperties: false
                    candidate:
                      type: object
                      properties:
                        correct:
                          type: integer
                          minimum: 0
                          description: >-
                            Rows where the AI verdict matches the human label. A
                            score at or above the metric's pass threshold is a
                            positive verdict.
                          example: 20
                        alignment:
                          type: number
                          nullable: true
                          description: >-
                            Alignment between the AI scores and the human labels
                            on the compared rows. Null when undefined.
                          example: 0.71
                      required:
                        - correct
                        - alignment
                      additionalProperties: false
                  required:
                    - rowsScored
                    - rowsTotal
                    - source
                    - candidate
                  additionalProperties: false
              required:
                - optimization
                - validation
              additionalProperties: false
              description: >-
                Both prompts scored on the rows the search used and on the
                held-out rows. Null when the optimizer reported nothing.
            rows:
              type: array
              nullable: true
              items:
                type: object
                properties:
                  evaluationId:
                    type: string
                    example: evaluation_123
                  humanScore:
                    type: number
                    description: The human label.
                    example: 1
                  sourceScore:
                    type: number
                    nullable: true
                    description: >-
                      The source prompt's judge score on this row, or null when
                      it failed. A score at or above the metric's pass threshold
                      is a positive verdict.
                    example: 0
                  candidateScore:
                    type: number
                    nullable: true
                    description: >-
                      The optimized prompt's judge score on this row, or null
                      when it failed. A score at or above the metric's pass
                      threshold is a positive verdict.
                    example: 1
                required:
                  - evaluationId
                  - humanScore
                  - sourceScore
                  - candidateScore
                additionalProperties: false
              description: >-
                One entry per held-out row the optimizer reported; a score is
                null when that prompt failed on the row. Null when the optimizer
                reported nothing.
          required:
            - used
            - heldOutEvaluationIds
            - results
            - rows
          additionalProperties: false
          readOnly: true
          description: >-
            How an optimization attempt was validated: the held-out evaluations
            and, once the optimizer reported, both prompts scored on the search
            rows and on the held-out rows. Set on an optimization attempt only,
            and null for any other metric, for an attempt that predates it, and
            for an attempt copied from another organization.
        optimizationRun:
          type: object
          nullable: true
          properties:
            strategies:
              type: array
              items:
                type: string
                enum:
                  - FIX_FALSE_POSITIVES
                  - FIX_FALSE_NEGATIVES
                  - ADD_RUBRIC
                  - SIMPLIFY
                  - BROADEN
              description: The strategies the run wrote candidates with.
              example:
                - ADD_RUBRIC
                - SIMPLIFY
            maxSteps:
              type: integer
              minimum: 1
              description: >-
                The run's step budget, after the optimizer applied its own
                ceiling.
              example: 6
            stepsUsed:
              type: integer
              minimum: 0
              description: >-
                The search steps the run took. 0 when the source prompt already
                met the target.
              example: 4
          required:
            - strategies
            - maxSteps
            - stepsUsed
          additionalProperties: false
          readOnly: true
          description: >-
            What an optimization attempt ran: the strategies, the step budget
            and the steps used. Null while the attempt runs, and when it was not
            reported: an attempt from before the report existed, one run by an
            older optimizer, a failed run, an attempt copied from another
            organization, or a metric that is not an optimization attempt. Null
            never means a run of 0 steps.
        specificationIds:
          type: array
          items:
            type: string
          description: >-
            Specifications linked to this revision. A MEMBER caller sees only
            the specifications of the products it can read.
          example:
            - spec_123
        userGroupIds:
          type: array
          items:
            type: string
          example:
            - ug_123
          description: User groups of the caller's organization linked to this revision.
        excludedFromAnalyticsAt:
          type: string
          nullable: true
          format: date-time
          readOnly: true
          description: >-
            When this revision was excluded from analytics. Null when its
            results still count. The other revisions of the metric are
            unaffected.
        excludedByUserId:
          type: string
          nullable: true
          readOnly: true
          description: >-
            User who excluded this revision from analytics. A repeated exclusion
            keeps the first user.
        createdAt:
          type: string
          format: date-time
      required:
        - id
        - metricId
        - number
        - parentRevisionId
        - name
        - isActive
        - legacyAt
        - disabledAt
        - definition
        - judgePrompt
        - evaluatorModelName
        - evaluationParams
        - areEvalParamsTop
        - judgeGenerationSettings
        - passThreshold
        - applicabilityScope
        - applicabilityThreshold
        - classifierQuestion
        - isBeingOptimized
        - optimizationStatus
        - optimizationValidation
        - optimizationRun
        - specificationIds
        - userGroupIds
        - excludedFromAnalyticsAt
        - excludedByUserId
        - createdAt
    Error:
      type: object
      properties:
        error:
          type: string
          example: Error type
        message:
          type: string
          example: Error message description
    Prefer:
      type: string
      description: >-
        Send `return=minimal` to get no body back from a write and skip reading
        the resource: a create answers `201` with only `Location`, and an update
        answers `204`.
      example: return=minimal
    ClassifierQuestion:
      type: object
      properties:
        type:
          type: string
          enum:
            - yes_no
            - scale
        instructions:
          type: string
        goodAnswer:
          type: string
          enum:
            - 'yes'
            - 'no'
        criteria:
          type: object
          nullable: true
          properties:
            'yes':
              type: string
              nullable: true
            'no':
              type: string
              nullable: true
          required:
            - 'yes'
            - 'no'
        levels:
          type: array
          items:
            type: object
            properties:
              description:
                type: string
              score:
                type: number
            required:
              - description
              - score
        doesNotApply:
          type: string
          nullable: true
      required:
        - type
        - instructions
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        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-...`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.