> ## Documentation Index > Fetch the complete documentation index at: https://www.dataframer.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create spec > Generate a new spec (async operation) **Async operation**: This endpoint returns immediately with a spec ID. Poll `GET /api/dataframer/specs/{id}/` until status is `SUCCEEDED` or `FAILED`. Supports both seeded specs (provide `dataset_id` to analyze a seed dataset) and seedless specs (provide `generation_objectives` to describe what data to generate). ## OpenAPI ````yaml POST /api/dataframer/specs/ openapi: 3.0.0 info: title: DataFramer API version: 0.1.0 description: '' termsOfService: https://www.aimon.ai/docs/privacy-policy.pdf contact: name: DataFramer Support email: info@dataframer.ai license: name: Proprietary x-logo: url: https://dataframer.ai/logo.png altText: DataFramer AI x-stainless: package-name: aimon-dataframer namespace: - aimon - dataframer servers: - url: https://df-api.dataframer.ai description: Production server security: - BearerAuth: [] externalDocs: description: Complete API Guide url: https://docs.dataframer.ai/dataframer paths: /api/dataframer/specs/: post: summary: Create spec description: >- Generate a new spec (async operation). **Async operation**: This endpoint returns immediately with a spec ID. Poll `GET /api/dataframer/specs/{id}/` until status is `SUCCEEDED` or `FAILED`. For seeded specs: provide `dataset_id` (ID of an uploaded seed dataset). For seedless specs: provide `generation_objectives` (text describing what data to generate). **Seedless output format**: Seedless specs produce only plain-text `.txt` sample files, regardless of what `generation_objectives` describes. To get CSV, JSONL, Markdown, PDF, or XLSX output, upload a seed dataset of that file type and use a seeded spec. operationId: api_dataframer_specs_create requestBody: required: true content: application/json: schema: required: - name type: object properties: name: description: Name for the new spec (must be unique) type: string generation_objectives: description: >- Custom objectives or instructions for data generation that directly influence contents of the generated spec. Required for seedless specs (when dataset_id is omitted). type: string dataset_id: description: >- ID of the seed dataset to generate spec from. Omit for seedless spec creation. type: string format: uuid spec_generation_model_name: description: AI model to use for spec generation type: string enum: - 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 default: anthropic/claude-opus-5-5-thinking generate_distributions: description: >- When true, the spec will include generated probability distributions for each property value; when false, each property will have a uniform distribution. type: boolean default: true generate_conditional_distributions: description: >- Generate conditional distributions showing how property values vary based on other properties. Requires generate_distributions to be true. type: boolean default: true extrapolate_values: description: >- Extrapolate new values beyond existing data ranges. Not applicable for seedless specs. type: boolean default: true extrapolate_axes: description: >- Extrapolate to new axes/dimensions not present in seed data. Not applicable for seedless specs. type: boolean default: false description: description: >- Description of the spec's purpose (optional, for data organization purposes only) type: string examples: seeded_spec: summary: Create spec from dataset value: dataset_id: a1b2c3d4-e5f6-7890-abcd-ef1234567890 name: Customer Support Conversations Spec spec_generation_model_name: anthropic/claude-sonnet-5-thinking generate_distributions: true extrapolate_values: true extrapolate_axes: false seedless_spec: summary: Create spec without dataset (seedless) value: name: Product Reviews Spec spec_generation_model_name: anthropic/claude-sonnet-5-thinking generation_objectives: >- Generate realistic product reviews for an e-commerce platform. Reviews should vary in sentiment (positive, negative, neutral), length (short, medium, long), and product category. responses: '202': description: >- 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. content: application/json: schema: $ref: '#/components/schemas/Spec' examples: spec_creation_started: value: 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: [] '400': description: >- Bad request - validation error, duplicate spec name, or invalid parameters '404': description: Dataset not found '500': description: Internal server error during spec creation x-codeSamples: - lang: Python source: |- 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) - lang: cURL source: |- 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" }' components: schemas: Spec: type: object description: '' properties: id: type: string format: uuid description: Unique identifier for the spec name: type: string description: Spec name description: type: string nullable: true description: >- Description of the spec's purpose (optional, for data organization purposes only) status: type: string enum: - PROCESSING - SUCCEEDED - FAILED description: Current status of the spec created_at: type: string format: date-time description: Timestamp when the spec was created updated_at: type: string format: date-time description: Timestamp when the spec was last modified dataset_id: type: string format: uuid nullable: true description: ID of the seed dataset. Null for seedless specs. dataset_name: type: string nullable: true description: Name of the seed dataset. Null for seedless specs. dataset_type: type: string enum: - SINGLE_FILE - MULTI_FILE - MULTI_FOLDER description: Type of dataset. MULTI_FILE for seedless specs. created_by_email: type: string description: Email of the user who created this spec runtime_params: type: object additionalProperties: true description: >- Parameters used during spec generation (model name, distribution settings, etc.) versions: type: array items: $ref: '#/components/schemas/SpecVersionPublic' description: >- All versions of this spec. Only included when include_versions=true. Empty when status is PROCESSING or FAILED. content_yaml: type: string nullable: true description: >- The YAML content from the latest version of this spec. Null when status is PROCESSING or FAILED. error: type: string nullable: true description: Error message when status is FAILED. Null otherwise. SpecVersionPublic: type: object properties: content_yaml: title: Content yaml type: string created_at: title: Created at type: string format: date-time securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API Key description: 'API Key authentication. Format: "Bearer YOUR_API_KEY"' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.