> ## Documentation Index > Fetch the complete documentation index at: https://docs.dataframer.ai/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: [] tags: - name: Seed Datasets description: Manage seed datasets for generation - name: Specs description: Data specifications for sample generation - name: Runs description: Generation runs and results - name: Evaluations description: Evaluate generated sample quality - name: Red Teaming description: Security testing and adversarial prompts - name: Spec Creation description: Create specs from datasets or from scratch (seedless) - name: Generation description: Synthetic data generation - name: API Keys description: API key management and rotation - name: Health description: Health check endpoints - name: Models description: Available AI models externalDocs: description: Complete API Guide url: https://docs.dataframer.ai/dataframer paths: /api/dataframer/specs/: post: tags: - Specs 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). 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. For databricks/ models, you must also provide databricks_client_id, databricks_client_secret, and databricks_api_base. type: string enum: - anthropic/claude-opus-4-6-thinking - anthropic/claude-sonnet-4-6-thinking - gemini/gemini-3.1-pro-preview-thinking - openai/gpt-5.4-thinking - databricks/databricks-claude-haiku-4-5 - databricks/databricks-claude-haiku-4-5-thinking - databricks/databricks-claude-opus-4-6 - databricks/databricks-claude-opus-4-6-thinking - databricks/databricks-claude-sonnet-4-6 - databricks/databricks-claude-sonnet-4-6-thinking - databricks/databricks-gemini-3-1-pro - databricks/databricks-gemini-3-1-pro-thinking - databricks/databricks-gpt-5-4 - databricks/databricks-gpt-5-4-thinking default: anthropic/claude-opus-4-6-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: type: string description: >- Description of the spec's purpose (optional, for data organization purposes only) databricks_client_id: type: string description: >- Databricks service principal application (client) ID. Required when using databricks/ models. databricks_client_secret: type: string description: >- Databricks service principal secret. Required when using databricks/ models. databricks_api_base: type: string description: >- Databricks Model Serving endpoint URL (e.g. https://adb-xxx.azuredatabricks.net/serving-endpoints). Required when using databricks/ models. 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-4-5 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-4-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. Poll GET /api/dataframer/specs/{id}/ until status is SUCCEEDED or FAILED. content: application/json: schema: $ref: '#/components/schemas/AnalyzeCreateResponse' examples: spec_creation_started: value: id: 550e8400-e29b-41d4-a716-446655440000 '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: JavaScript source: |- import Dataframer from 'dataframer'; const client = new Dataframer({ apiKey: process.env['DATAFRAMER_API_KEY'], // This is the default and can be omitted }); const spec = await client.dataframer.specs.create({ name: 'Customer Support Conversations Spec', dataset_id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890', extrapolate_values: true, generate_distributions: true, spec_generation_model_name: 'anthropic/claude-sonnet-4-5', }); console.log(spec.id); - 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-4-5", ) print(spec.id) components: schemas: AnalyzeCreateResponse: type: object properties: id: type: string format: uuid description: ID of the newly created spec securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API Key description: 'API Key authentication. Format: "Bearer YOUR_API_KEY"' ````