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

# Update Experiment

> Update mutable fields of an experiment.

Use this tool when the caller wants to rename an experiment or replace its
description without changing the experiment identity. The request must
include at least one mutable field, and names must remain unique within the
authenticated user scope.

When to Use:
    - Call this to rename an experiment or replace its description while
      keeping the same experiment identity.
    - Call this after retrieving the experiment when the user wants to
      refine the stored metadata.

Constraints:
    - Only ``name`` and ``description`` are mutable through this route.
    - Names must remain unique within the authenticated user scope.

Notes:
    - For agent-facing output, explicitly confirm which fields changed and
      include the resulting ``id`` and ``name``.
    - The endpoint returns the updated ``ContextExperimentModel`` rather
      than a status-only wrapper.

Args:
    experiment_id: Opaque experiment identifier to update.
    user: Authenticated user resolved from the API key.
    data: Update payload containing ``name`` and/or ``description``.
    db: Active database session.

Returns:
    The updated experiment object.

Raises:
    HTTPException: Raised with ``404`` when the experiment is not available
        to the caller, or ``409`` when the requested new name already
        exists in the same user scope.



## OpenAPI

````yaml https://api.haiqu.ai/openapi.json put /ai/{experiment_id}
openapi: 3.1.0
info:
  title: Haiqu API
  summary: Haiqu RESTful API service.
  description: Cloud service providing the access to Haiqu cloud runtime
  contact:
    name: Haiqu Inc.
    url: https://haiqu.ai/
    email: info@haiqu.ai
  version: 1.4.0
servers: []
security: []
paths:
  /ai/{experiment_id}:
    put:
      summary: Update Experiment
      description: >-
        Update mutable fields of an experiment.


        Use this tool when the caller wants to rename an experiment or replace
        its

        description without changing the experiment identity. The request must

        include at least one mutable field, and names must remain unique within
        the

        authenticated user scope.


        When to Use:
            - Call this to rename an experiment or replace its description while
              keeping the same experiment identity.
            - Call this after retrieving the experiment when the user wants to
              refine the stored metadata.

        Constraints:
            - Only ``name`` and ``description`` are mutable through this route.
            - Names must remain unique within the authenticated user scope.

        Notes:
            - For agent-facing output, explicitly confirm which fields changed and
              include the resulting ``id`` and ``name``.
            - The endpoint returns the updated ``ContextExperimentModel`` rather
              than a status-only wrapper.

        Args:
            experiment_id: Opaque experiment identifier to update.
            user: Authenticated user resolved from the API key.
            data: Update payload containing ``name`` and/or ``description``.
            db: Active database session.

        Returns:
            The updated experiment object.

        Raises:
            HTTPException: Raised with ``404`` when the experiment is not available
                to the caller, or ``409`` when the requested new name already
                exists in the same user scope.
      operationId: update_experiment
      parameters:
        - name: experiment_id
          in: path
          required: true
          schema:
            type: string
            title: Experiment Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: >-
                #/components/schemas/haiqu__api__mcp__schemas__ExperimentUpdateModel
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContextExperimentModel'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      security:
        - APIKeyQuery: []
        - APIKeyHeader: []
components:
  schemas:
    haiqu__api__mcp__schemas__ExperimentUpdateModel:
      properties:
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: New experiment name unique within the caller scope.
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          description: >-
            Experiment description stored as HTML-formatted text. Send markup
            such as `<p>...</p>` when updating rich text content.
      type: object
      title: ExperimentUpdateModel
      description: |-
        Define payload for MCP experiment update requests.

        Attributes:
            name: New experiment name.
            description: New HTML-formatted experiment description.
    ContextExperimentModel:
      properties:
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          default: ''
        creation_date:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Creation Date
        tags:
          anyOf:
            - type: string
            - type: 'null'
          title: Tags
          default: ''
        circuits_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Circuits Count
          default: 0
        jobs_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Jobs Count
          default: 0
        last_action_date:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Last Action Date
        context:
          type: string
          title: Context
        url:
          anyOf:
            - type: string
            - type: 'null'
          title: Url
          default: ''
      type: object
      required:
        - id
        - name
        - context
      title: ContextExperimentModel
      description: |-
        Represent an experiment with MCP-specific context metadata.

        ``description`` and ``creation_date`` remain optional for compatibility
        with legacy database rows.

        Attributes:
            description: Plain-text experiment description. Optional for legacy
                rows that still store ``NULL``.
            creation_date: Experiment creation timestamp. Optional for legacy rows
                that still store ``NULL``.
            context: Additional plain-text guidance for AI agents consuming the
                experiment.
            url: Dashboard URL for the experiment when available.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    APIKeyQuery:
      type: apiKey
      in: query
      name: HAIQU_API_KEY
    APIKeyHeader:
      type: apiKey
      in: header
      name: authorization

````