Skip to main content
PUT
/
api
/
dataframer
/
specs
/
{spec_id}
Python
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)
{
  "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",
  "created_by_email": "[email protected]",
  "runtime_params": {
    "spec_generation_model_name": "gemini/gemini-3-pro-preview",
    "generate_distributions": true,
    "extrapolate_values": true,
    "extrapolate_axes": false
  },
  "content_yaml": "spec:\n  description: \"Updated customer support conversations\"\n  data_property_variations:\n    - property_name: sentiment\n      property_values: [positive, negative, neutral, mixed]\n      base_distributions:\n        positive: 35\n        negative: 25\n        neutral: 25\n        mixed: 15\n"
}

Authorizations

​
Authorization
string
header
required

API Key authentication. Format: "Bearer YOUR_API_KEY"

Path Parameters

​
spec_id
string<uuid>
required

UUID of the spec

Body

application/json
​
content_yaml
string
required

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

Response

New spec version created and returned

​
id
string<uuid>

Unique identifier for the spec

​
name
string

Spec name

​
description
string

Description of the spec's purpose (optional, for data organization purposes only)

​
status
enum<string>

Current status of the spec

Available options:
PROCESSING,
SUCCEEDED,
FAILED
​
created_at
string<date-time>

Timestamp when the spec was created

​
updated_at
string<date-time>

Timestamp when the spec was last modified

​
dataset_id
string<uuid> | null

ID of the seed dataset. Null for seedless specs.

​
dataset_name
string | null

Name of the seed dataset. Null for seedless specs.

​
created_by_email
string

Email of the user who created this spec

​
runtime_params
object

Parameters used during spec generation (model name, distribution settings, etc.)

​
versions
object[]

All versions of this spec. Only included when include_versions=true. Empty when status is PROCESSING or FAILED.

​
content_yaml
string | null

The YAML content from the latest version of this spec. Null when status is PROCESSING or FAILED.

​
error
string | null

Error message when status is FAILED. Null otherwise.