Skip to main content
PUT
/
api
/
dataframer
/
specs
/
{spec_id}
Replace spec
curl --request PUT \
  --url https://df-api.dataframer.ai/api/dataframer/specs/{spec_id}/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "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"
}
'
{
  "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"
}
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.

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.