---
title: "Draft"
method: POST
path: "/knowledge/definition-proposals"
tags: ["knowledge"]
---

# Draft

`POST /knowledge/definition-proposals`

## Request

- Base URL: `https://api-docs.upsmith.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api-docs.upsmith.com/knowledge/definition-proposals`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

## Headers

- `timezone` string
- `x-user-id` string, nullable
- `x-actor-email` string, nullable
- `x-request-source` string, nullable
- `x-operation-id` string, nullable
- `x-commit-message` string, nullable
- `x-confirmation-id` string, nullable
- `x-chat-id` string, nullable
- `organization-id` string, nullable

## Request body

- DefinitionDraftInput
  - `scope` 'core' | 'shop', required
  - `definition` union, required
    - EntityDefinition
      - `kind` 'entity_type', required
      - `id` string, required
      - `key` string, required
      - `label` string, required
      - `identity_rule` string, required
      - `match_facts` string[]
      - `documentation` DefinitionDocumentation, required
        - `schema_version` 1
        - `label` string, nullable
        - `description` string, nullable
        - `guidance` string, nullable
    - PropertyDefinitionInput
      - `kind` 'property_type', required
      - `id` string, required
      - `key` string, required
      - `label` string, required
      - `entity_type_id` string, required
      - `meaning` string, required
      - `answer_type` 'text' | 'identifier' | 'number' | 'date' | 'bool' | 'choice' | 'entity', required
      - `many_valued` boolean
      - `is_unique` boolean
      - `target_entity_type_id` string, nullable
      - `choice_list_id` string, nullable
      - `documentation` DefinitionDocumentation, required
        - `schema_version` 1
        - `label` string, nullable
        - `description` string, nullable
        - `guidance` string, nullable
  - `expected_revision` string, nullable
  - `reuse_justification` string, required
  - `vocabulary_reference` string, required
  - `vocabulary_rationale` string, required
  - `synonyms` string[]

## Response `200`

Successful Response

- DefinitionProposalResponse
  - `review` ReviewRecord, required
    - `organization_id` string, required
    - `id` string, required
    - `request_hash` string, required
    - `request` ReviewRequest, required
      - `target_kind` 'entity' | 'fact' | 'link' | 'evidence' | 'source' | 'checkpoint_run' | 'checkpoint_rule' | 'model_answer' | 'pipeline_run', required
      - `target_id` string, required
      - `reason` 'question' | 'low_confidence' | 'audit', required
      - `question` string, required
      - `context` object
      - `sampling_probability` number, nullable
    - `target_snapshot` object, required
    - `opened_by` string, required
    - `created_at` string, date-time, required
    - `status` 'open' | 'resolved', required
    - `resolution` ReviewDecision, required
      - `decision` 'accept' | 'reject', required
      - `note` string, required
      - `answer` unknown
    - `resolved_by` string, nullable, required
    - `resolved_at` string, date-time, nullable, required
    - `resolution_evidence_id` string, nullable, required
  - `draft` DefinitionDraftOutput, required
    - `scope` 'core' | 'shop', required
    - `definition` union, required
      - EntityDefinition
        - `kind` 'entity_type', required
        - `id` string, required
        - `key` string, required
        - `label` string, required
        - `identity_rule` string, required
        - `match_facts` string[]
        - `documentation` DefinitionDocumentation, required
          - `schema_version` 1
          - `label` string, nullable
          - `description` string, nullable
          - `guidance` string, nullable
      - UpsmithKnowledgeContractsDefinitionProposalsPropertyDefinition
        - `kind` 'property_type', required
        - `id` string, required
        - `key` string, required
        - `label` string, required
        - `entity_type_id` string, required
        - `meaning` string, required
        - `answer_type` 'text' | 'identifier' | 'number' | 'date' | 'bool' | 'choice' | 'entity', required
        - `many_valued` boolean
        - `is_unique` boolean
        - `target_entity_type_id` string, nullable
        - `choice_list_id` string, nullable
        - `documentation` DefinitionDocumentation, required
          - `schema_version` 1
          - `label` string, nullable
          - `description` string, nullable
          - `guidance` string, nullable
    - `expected_revision` string, nullable
    - `reuse_justification` string, required
    - `vocabulary_reference` string, required
    - `vocabulary_rationale` string, required
    - `synonyms` string[]
  - `closest` DefinitionCandidate[], required
    - `kind` 'entity_type' | 'property_type', required
    - `id` string, required
    - `key` string, required
    - `label` string, required
    - `description` string, nullable, required
    - `synonyms` string[]
    - `revision` string, required
    - `score` number, required

## Other responses

- `422`: Validation Error

---

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