> ## 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.

# Rename a revision

> Give one revision a name of its own, or clear it. The revision keeps its number and judge settings, no revision is created, and the metric's name stays as it is. The id is a revision id. A metric id answers 404.



## OpenAPI

````yaml /openapi.json patch /v2/revisions/{id}
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/{id}:
    patch:
      tags:
        - revisions
      summary: Rename a revision
      description: >-
        Give one revision a name of its own, or clear it. The revision keeps its
        number and judge settings, no revision is created, and the metric's name
        stays as it is. The id is a revision id. A metric id answers 404.
      operationId: updateRevision
      parameters:
        - schema:
            type: string
            minLength: 1
            description: >-
              Revision ID. A metric ID answers 404; read a metric under
              /v2/metrics.
            example: revision_123
          required: true
          description: >-
            Revision ID. A metric ID answers 404; read a metric under
            /v2/metrics.
          name: id
          in: path
        - $ref: '#/components/parameters/Prefer'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RevisionUpdate'
      responses:
        '200':
          description: >-
            The renamed revision. The body is the resource as its GET answers
            it.
          headers:
            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'
        '204':
          description: >-
            No body: the client sent `Prefer: return=minimal`, or the read after
            the write failed.
          headers:
            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`'
        '400':
          description: >-
            A name of "R" followed by digits that is not this revision's label,
            a revision of a Galtea metric, or a revision of a metric of another
            organization
          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 update this revision
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Revision 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:
    RevisionUpdate:
      type: object
      properties:
        name:
          type: string
          nullable: true
          example: stricter rubric
          description: >-
            The revision's own name. It shows as "R3: stricter rubric". Empty or
            null clears it, so the revision shows as its label, "R3". "R"
            followed by digits is refused unless it is this revision's own
            label. Unique among the live revisions of the metric, ignoring case.
      required:
        - name
      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.