> ## Documentation Index > Fetch the complete documentation index at: https://docs.dataframer.ai/llms.txt > Use this file to discover all available pages before exploring further. # Update spec > Replace a spec with a new version specified using YAML **Versioning**: Each update creates a new version of the spec. Previous versions are preserved and can be retrieved using `include_versions=true` on the GET endpoint. To check the expected spec YAML format, check the YAML section in spec view in the UI, or look at YAML returned by the Get spec API endpoint. Only the `spec:` section of the YAML is editable - the `metadata:` section is read-only and ignored if included. ## OpenAPI ````yaml PUT /api/dataframer/specs/{spec_id}/ openapi: 3.0.0 info: title: DataFramer API version: 0.1.0 description: '' termsOfService: https://www.aimon.ai/docs/privacy-policy.pdf contact: name: DataFramer Support email: info@dataframer.ai license: name: Proprietary x-logo: url: https://dataframer.ai/logo.png altText: DataFramer AI x-stainless: package-name: aimon-dataframer namespace: - aimon - dataframer servers: - url: https://df-api.dataframer.ai description: Production server security: - BearerAuth: [] tags: - name: Seed Datasets description: Manage seed datasets for generation - name: Specs description: Data specifications for sample generation - name: Runs description: Generation runs and results - name: Evaluations description: Evaluate generated sample quality - name: Red Teaming description: Security testing and adversarial prompts - name: Spec Creation description: Create specs from datasets or from scratch (seedless) - name: Generation description: Synthetic data generation - name: API Keys description: API key management and rotation - name: Health description: Health check endpoints - name: Models description: Available AI models externalDocs: description: Complete API Guide url: https://docs.dataframer.ai/dataframer paths: /api/dataframer/specs/{spec_id}/: parameters: - name: spec_id in: path description: UUID of the spec required: true schema: type: string format: uuid put: tags: - Specs summary: Update spec description: >- Replace the spec's YAML configuration with a new version. Each update creates a new version. Previous versions are preserved and can be retrieved using `include_versions=true` on the GET endpoint. To check the expected spec YAML format, check the YAML section in spec view in the UI, or look at YAML returned by the Get spec API endpoint. Only the `spec:` section is editable - the `metadata:` section is read-only and ignored. operationId: api_dataframer_specs_update parameters: - name: spec_id in: path description: UUID of the spec to update required: true schema: type: string format: uuid requestBody: required: true content: application/json: schema: required: - content_yaml type: object properties: content_yaml: description: >- Complete YAML spec configuration replacing its previous version in the spec. The YAML should have a 'spec' root key containing one or more editable fields: description, requirements, data_property_variations, selected_sql_schema_column, selected_sql_query_columns. To check the expected spec YAML format, check the YAML section in spec view in the UI, or look at YAML returned by the Get spec API endpoint. If a 'metadata' section is present, it is ignored (read-only). type: string examples: update_spec: summary: Update spec with new distributions value: content_yaml: | spec: description: "Customer support conversations with varying sentiment and priority" requirements: "Each conversation should include a customer greeting, issue description, and agent response. Maintain professional tone throughout." data_property_variations: - property_name: sentiment property_values: - positive - negative - neutral base_distributions: positive: 40 negative: 30 neutral: 30 - property_name: priority property_values: - high - medium - low base_distributions: high: 20 medium: 50 low: 30 responses: '200': description: New spec version created and returned content: application/json: schema: $ref: '#/components/schemas/Spec' examples: spec_updated: value: id: 550e8400-e29b-41d4-a716-446655440000 name: Customer Support Conversations Spec description: Updated customer support conversations status: SUCCEEDED created_at: '2025-01-15T10:30:00Z' updated_at: '2025-01-15T14:30:00Z' dataset_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 dataset_name: Customer Support Dataset dataset_type: SINGLE_FILE created_by_email: sarah.chen@acme.com runtime_params: spec_generation_model_name: anthropic/claude-sonnet-4-5-thinking generate_distributions: true extrapolate_values: true extrapolate_axes: false content_yaml: | spec: description: "Updated customer support conversations" data_property_variations: - property_name: sentiment property_values: [positive, negative, neutral, mixed] base_distributions: positive: 35 negative: 25 neutral: 25 mixed: 15 '400': description: >- Bad request - spec not SUCCEEDED, YAML validation error, missing content_yaml, or maximum versions reached '401': description: Unauthorized - Invalid or missing authentication token '404': description: Spec not found or does not belong to user's company x-codeSamples: - lang: JavaScript source: >- import Dataframer from 'dataframer'; const client = new Dataframer({ apiKey: process.env['DATAFRAMER_API_KEY'], // This is the default and can be omitted }); const spec = await client.dataframer.specs.update('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { content_yaml: 'spec:\n description: "Customer support conversations with varying sentiment and priority"\n requirements: "Each conversation should include a customer greeting, issue description, and agent response. Maintain professional tone throughout."\n data_property_variations:\n - property_name: sentiment\n property_values:\n - positive\n - negative\n - neutral\n base_distributions:\n positive: 40\n negative: 30\n neutral: 30\n - property_name: priority\n property_values:\n - high\n - medium\n - low\n base_distributions:\n high: 20\n medium: 50\n low: 30\n', }); console.log(spec.id); - lang: Python source: |- import os from dataframer import Dataframer client = Dataframer( api_key=os.environ.get("DATAFRAMER_API_KEY"), # This is the default and can be omitted ) spec = client.dataframer.specs.update( spec_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", content_yaml="spec:\n description: \"Customer support conversations with varying sentiment and priority\"\n requirements: \"Each conversation should include a customer greeting, issue description, and agent response. Maintain professional tone throughout.\"\n data_property_variations:\n - property_name: sentiment\n property_values:\n - positive\n - negative\n - neutral\n base_distributions:\n positive: 40\n negative: 30\n neutral: 30\n - property_name: priority\n property_values:\n - high\n - medium\n - low\n base_distributions:\n high: 20\n medium: 50\n low: 30\n", ) print(spec.id) components: schemas: Spec: type: object description: '' properties: id: type: string format: uuid readOnly: true description: Unique identifier for the spec name: type: string description: Spec name description: type: string description: >- Description of the spec's purpose (optional, for data organization purposes only) status: type: string enum: - PROCESSING - SUCCEEDED - FAILED description: Current status of the spec created_at: type: string format: date-time readOnly: true description: Timestamp when the spec was created updated_at: type: string format: date-time readOnly: true description: Timestamp when the spec was last modified dataset_id: type: string format: uuid nullable: true readOnly: true description: ID of the seed dataset. Null for seedless specs. dataset_name: type: string nullable: true readOnly: true description: Name of the seed dataset. Null for seedless specs. dataset_type: type: string readOnly: true enum: - SINGLE_FILE - MULTI_FILE - MULTI_FOLDER description: Type of dataset. MULTI_FILE for seedless specs. created_by_email: type: string readOnly: true description: Email of the user who created this spec runtime_params: type: object additionalProperties: true description: >- Parameters used during spec generation (model name, distribution settings, etc.) versions: type: array items: $ref: '#/components/schemas/SpecVersionPublic' readOnly: true description: >- All versions of this spec. Only included when include_versions=true. Empty when status is PROCESSING or FAILED. content_yaml: type: string nullable: true readOnly: true description: >- The YAML content from the latest version of this spec. Null when status is PROCESSING or FAILED. error: type: string nullable: true readOnly: true description: Error message when status is FAILED. Null otherwise. SpecVersionPublic: type: object properties: content_yaml: title: Content yaml type: string created_at: title: Created at type: string format: date-time readOnly: true securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API Key description: 'API Key authentication. Format: "Bearer YOUR_API_KEY"' ````