---
title: "Create new schema"
method: POST
path: "/v4/schemas/"
tags: ["Schemas"]
---

# Create new schema

`POST /v4/schemas/`

## Request

- Base URL: `https://api.kadoa.com`
- URL: `https://api.kadoa.com/v4/schemas/`
- Auth: API key in header `x-api-key`

Create a new data schema with specified fields and entity type

## Request body

- CreateSchemaBody: Request body for creating a new schema
  - `name` string, required: Name of the schema
  - `entity` string: Entity type for the schema
  - `fields` union[], required: Schema fields for extraction - choose from Data Field (typed data) or Classification Field
    - union: Extraction field schema
      - DataField: Extract and structure specific data from web pages with typed values (e.g., product prices, article titles, dates). `description` explains what the field is; optional `instruction` gives the AI field-specific extraction guidance. Use this for actual data you want to capture. Kadoa-managed functions such as job description, job type classification, taxonomy mapping, and stable unique ID are normal `fieldType: SCHEMA` fields with their output `dataType`; their function identity lives in `mapper`. To expose source values such as the page URL, full HTML, or full Markdown, use a normal `fieldType: SCHEMA` field with `params.sourceKey` (for example `link`, `allExtracts.fullHtml`, or `allExtracts.fullMarkdown`).
        - `mapper` 'jobDescription' | 'categoryClassifier' | 'taxonomyMapping' | 'stableUniqueId' | 'linkExtraction' | 'additionalData' | 'categorize': Function that produces this field's value.
        - `mapperConfig` object: Configuration for the selected mapper.
        - `name` string, required: Field name (e.g., productName, 3dListings, listing-count)
        - `description` string, required: Human-readable field description shown in Kadoa.
        - `instruction` string: Optional field-specific AI instruction. Use this for extraction guidance that is more specific than the description.
        - `fieldType` 'SCHEMA': Field role. Use SCHEMA for extracted data fields.
        - `example` union: Example value for the field
          - string
          - string[]
        - `shape` unknown
        - `dataType` 'STRING' | 'NUMBER' | 'BOOLEAN' | 'DATE' | 'DATETIME' | 'MONEY' | 'IMAGE' | 'LINK' | 'OBJECT' | 'ARRAY', required: Output data type for SCHEMA fields. Use uppercase public values: STRING, NUMBER, BOOLEAN, DATE, DATETIME, MONEY, IMAGE, LINK, OBJECT, ARRAY. Classification fields use fieldType=CLASSIFICATION instead of dataType=CLASSIFICATION. Kadoa-managed functions are not data types; they keep a normal output dataType and carry their function identity in mapper, with configuration in mapperConfig.
        - `isKey` boolean: Marks this field as part of the record's primary key. Key fields define row identity across runs and enable data linking (records with the same key values are treated as the same record over time, used for dedupe and change detection). Set true ONLY when the complete key tuple uniquely identifies a logical output record and every component is stable across runs and reliably present (not nullable/missing). Key fields should be scalar STRING, NUMBER, or LINK fields; avoid structured, semantic, boolean, image, and timestamp/date fields as keys. Good candidates: external IDs, SKUs, canonical URLs, posting IDs. Bad candidates: prices, counts, timestamps, free-text titles/descriptions, or anything that can change between runs. Multiple fields may form a composite key; uniqueness applies to their combination, not each component. For derived rows, source-backed grouping dimensions and a deterministic output discriminator may identify the result; measured values and explanations do not. If no supported key tuple satisfies these guarantees, leave isKey unset on every field — data linking will simply be disabled, which is preferable to a wrong key. Choosing a non-stable or non-unique key causes duplicate rows and missed updates.
      - ClassificationField: Categorize extracted data into predefined labels. Classification is a field role (`fieldType: CLASSIFICATION`), not a schema data type. Use this when you want the system to classify content into specific categories you define.
        - `name` string, required: Field name (e.g., category, product-type)
        - `description` string: Optional human-readable field description
        - `fieldType` 'CLASSIFICATION', required: Field role. Use CLASSIFICATION for predefined category labels.
        - `categories` object[], required: List of predefined categories for classification
          - `title` string, required: Short title/label of the category
          - `definition` string, required: Full definition/description of the category

## Response `201`

201

- CreateSchemaResponse: Response for schema creation
  - `error` false, required: Error flag (always false on success)
  - `success` boolean, required: Success flag
  - `schemaId` string, required: ID of the created schema
  - `message` string, required: Success message
  - `createdAt` string: Creation timestamp
  - `updatedAt` string: Last update timestamp

## Other responses

- `400`: 400
- `401`: 401
- `500`: 500

---

[API](https://skmtc.dev/kadoa/apis/kadoa-api.md) · [All operations](https://skmtc.dev/kadoa/apis/kadoa-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kadoa/apis/kadoa-api/revisions/bf7803c927b4?raw)