Skip to main content
POST
/
api
/
dataframer
/
specs
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.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-4-5",
)
print(spec.id)
{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

Authorizations

​
Authorization
string
header
required

API Key authentication. Format: "Bearer YOUR_API_KEY"

Body

application/json
​
name
string
required

Name for the new spec (must be unique)

​
generation_objectives
string

Custom objectives or instructions for data generation that directly influence contents of the generated spec. Required for seedless specs (when dataset_id is omitted).

​
dataset_id
string<uuid>

ID of the seed dataset to generate spec from. Omit for seedless spec creation.

​
spec_generation_model_name
enum<string>
default:gemini/gemini-3-pro-preview

AI model to use for spec generation

Available options:
anthropic/claude-opus-4-5,
anthropic/claude-opus-4-5-thinking,
anthropic/claude-sonnet-4-5,
anthropic/claude-sonnet-4-5-thinking,
anthropic/claude-haiku-4-5,
openai/gpt-oss-120b,
gemini/gemini-3-pro-preview,
gemini/gemini-3-pro-preview-thinking
​
generate_distributions
boolean
default:true

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
boolean
default:false

Generate conditional distributions showing how property values vary based on other properties. Requires generate_distributions to be true.

​
extrapolate_values
boolean
default:true

Extrapolate new values beyond existing data ranges. Not applicable for seedless specs.

​
extrapolate_axes
boolean
default:false

Extrapolate to new axes/dimensions not present in seed data. Not applicable for seedless specs.

​
description
string

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

Response

Spec creation started. Poll GET /api/dataframer/specs/{id}/ until status is SUCCEEDED or FAILED.

​
id
string<uuid>

ID of the newly created spec