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.create(
name="Customer Support Conversations Spec",
dataset_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
extrapolate_axes=False,
extrapolate_values=True,
generate_distributions=True,
spec_generation_model_name="anthropic/claude-sonnet-5-thinking",
)
print(spec.id)curl https://df-api.dataframer.ai/api/dataframer/specs/ \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $DATAFRAMER_API_KEY" \
-d '{
"name": "Customer Support Conversations Spec",
"dataset_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"extrapolate_axes": false,
"extrapolate_values": true,
"generate_distributions": true,
"spec_generation_model_name": "anthropic/claude-fable-5-1-thinking"
}'{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "my-spec",
"description": "",
"status": "PROCESSING",
"created_at": "2026-01-01T00:00:00Z",
"updated_at": "2026-01-01T00:00:00Z",
"dataset_id": null,
"dataset_name": null,
"dataset_type": "MULTI_FILE",
"content_yaml": null,
"versions": []
}{
"error": "<string>",
"code": "not_supported_hybrid"
}Create spec
Generate a new spec (async operation)
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.create(
name="Customer Support Conversations Spec",
dataset_id="a1b2c3d4-e5f6-7890-abcd-ef1234567890",
extrapolate_axes=False,
extrapolate_values=True,
generate_distributions=True,
spec_generation_model_name="anthropic/claude-sonnet-5-thinking",
)
print(spec.id)curl https://df-api.dataframer.ai/api/dataframer/specs/ \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $DATAFRAMER_API_KEY" \
-d '{
"name": "Customer Support Conversations Spec",
"dataset_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"extrapolate_axes": false,
"extrapolate_values": true,
"generate_distributions": true,
"spec_generation_model_name": "anthropic/claude-fable-5-1-thinking"
}'{
"id": "550e8400-e29b-41d4-a716-446655440000",
"name": "my-spec",
"description": "",
"status": "PROCESSING",
"created_at": "2026-01-01T00:00:00Z",
"updated_at": "2026-01-01T00:00:00Z",
"dataset_id": null,
"dataset_name": null,
"dataset_type": "MULTI_FILE",
"content_yaml": null,
"versions": []
}{
"error": "<string>",
"code": "not_supported_hybrid"
}GET /api/dataframer/specs/{id}/ until status is SUCCEEDED or FAILED.dataset_id to analyze a seed dataset) and seedless specs (provide generation_objectives to describe what data to generate).Authorizations
API Key authentication. Format: "Bearer YOUR_API_KEY"
Body
Name for the new spec (must be unique)
Custom objectives or instructions for data generation that directly influence contents of the generated spec. Required for seedless specs (when dataset_id is omitted).
ID of the seed dataset to generate spec from. Omit for seedless spec creation.
AI model to use for spec generation
anthropic/claude-fable-5-1-thinking, anthropic/claude-opus-5-5-thinking, anthropic/claude-sonnet-5-5-thinking, gemini/gemini-3.1-pro-preview-thinking, openai/gpt-6-astra-thinking, openai/gpt-6.1-sol-thinking, openai/gpt-5.6-terra-thinking, databricks/system.ai.claude-sonnet-5-thinking, databricks/system.ai.claude-opus-5-thinking, databricks/system.ai.gpt-6-astra-thinking, databricks/system.ai.gpt-6-1-sol-thinking, databricks/system.ai.gpt-5-6-terra-thinking When true, the spec will include generated probability distributions for each property value; when false, each property will have a uniform distribution.
Generate conditional distributions showing how property values vary based on other properties. Requires generate_distributions to be true.
Extrapolate new values beyond existing data ranges. Not applicable for seedless specs.
Extrapolate to new axes/dimensions not present in seed data. Not applicable for seedless specs.
Description of the spec's purpose (optional, for data organization purposes only)
Response
Spec creation started. Returns the full Spec object with status=PROCESSING, content_yaml=null, and versions=[]. Poll GET /api/dataframer/specs/{id}/ until status is SUCCEEDED or FAILED.
Unique identifier for the spec
Spec name
Description of the spec's purpose (optional, for data organization purposes only)
Current status of the spec
PROCESSING, SUCCEEDED, FAILED Timestamp when the spec was created
Timestamp when the spec was last modified
ID of the seed dataset. Null for seedless specs.
Name of the seed dataset. Null for seedless specs.
Type of dataset. MULTI_FILE for seedless specs.
SINGLE_FILE, MULTI_FILE, MULTI_FOLDER Email of the user who created this spec
Parameters used during spec generation (model name, distribution settings, etc.)
All versions of this spec. Only included when include_versions=true. Empty when status is PROCESSING or FAILED.
Show child attributes
Show child attributes
The YAML content from the latest version of this spec. Null when status is PROCESSING or FAILED. Also null when content_unavailable_reason is set.
Error message when status is FAILED. Null otherwise.
Where the latest version's YAML is stored in your own cloud (null unless your deployment is customer-hosted)
Show child attributes
Show child attributes
Set when content_yaml is null because the YAML is stored in your own cloud. The spec is ready. A current Python SDK reads the YAML from your data plane and returns it in content_yaml, so it does not set this; the DataFramer app shows it too. Absent otherwise
spec_content_in_data_plane