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-sonnet-5-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": []
}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-sonnet-5-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": []
}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. For databricks/ models, you must also provide databricks_client_id, databricks_client_secret, and databricks_api_base.
anthropic/claude-fable-5-thinking, anthropic/claude-opus-5-thinking, anthropic/claude-sonnet-5-thinking, gemini/gemini-3.1-pro-preview-thinking, openai/gpt-5.6-sol-thinking, openai/gpt-5.6-terra-thinking, databricks/databricks-claude-haiku-4-5, databricks/databricks-claude-haiku-4-5-thinking, databricks/databricks-claude-opus-5, databricks/databricks-claude-opus-5-thinking, databricks/databricks-claude-sonnet-5, databricks/databricks-claude-sonnet-5-thinking, databricks/databricks-gemini-3-1-pro, databricks/databricks-gemini-3-1-pro-thinking, databricks/databricks-gpt-5-6-terra, databricks/databricks-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)
Databricks service principal application (client) ID. Required when using databricks/ models.
Databricks service principal secret. Required when using databricks/ models.
Databricks Model Serving endpoint URL (e.g. https://adb-xxx.azuredatabricks.net/serving-endpoints). Required when using databricks/ models.
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.
Error message when status is FAILED. Null otherwise.