> ## Documentation index
>
> Fetch the complete documentation index at: https://andesine.app/docs/llms.txt
> Use it to find all pages before you explore further.

# Update a schema draft

`POST https://api.andesine.app/schemas/{schemaID}/draft`

Replaces the fields of the local schema draft. People editing the draft see the change live. Fields keep their content in entries by ID, so reuse the IDs from schemas.get. Inherited fields stay as they are; don't include them. Entries don't change until schemas.apply.

Required API key permissions: collections. Write permissions also grant read access for the same resource.

## Authentication

Use one of:

- `apiKey` (http, bearer, Andesine API key)
- `oauth` (http, bearer, Andesine OAuth access token)

## Parameters

### Path

- `schemaID` (string, required): ID of the local collection schema.

### Header

- `x-workspace-id` (string, optional): Required for OAuth: ID of the workspace to access. API keys use their own workspace.

## Request body

The body is required.

Content type: `application/json`

- `definition` (object, required): The draft's own fields.
  - `formatVersion` (constant, required): Value: `1`.
  - `fields` (array of any of, required)
    - Any of: `SchemaProperty`
    - Any of: Option 2 (object)
      - `id` (string, required)
      - `kind` (constant, required): Value: `"fragment"`.
      - `label` (string, required)
      - `allowedBlocks` (array of `SchemaBlockType`, required)
      - `initialContent` (array of `ContentNodeInput`, required)
        - `type` (string, required)
        - `attrs` (object, optional)
          - `{key}` (any, optional)
        - `content` (array of `ContentNodeInput`, optional)
        - `marks` (array of `ContentMark`, optional)
        - `text` (string, optional)
      - `optional` (boolean, optional)
- `expectedHash` (string, optional): Draft hash from schemas.get; the update fails if the draft changed since.

## Responses

### 200

OK

Content type: `application/json`

Type: `LocalCollectionSchema`.

- `id` (string, required): ID of the local collection schema.
- `collectionID` (string, required): ID of the collection.
- `enabled` (boolean, required): Whether the collection currently defines a local schema.
- `draft` (any of, required): Current local schema draft.
  - Any of: `SchemaDraftDefinition`
    - `formatVersion` (constant, required): Value: `1`.
    - `fields` (array of `SchemaField`, required)
      - Any of: `SchemaProperty`
        - `id` (string, required)
        - `kind` (constant, required): Value: `"property"`.
        - `label` (string, required)
        - `type` (string, required): One of: `"text"`, `"number"`, `"checkbox"`, `"date"`, `"url"`, `"select"`, `"multi-select"`.
        - `initialValue` (`SchemaPropertyValue`, required)
          - Any of: Option 1 (boolean)
          - Any of: Option 2 (string)
          - Any of: Option 3 (array of string)
        - `options` (array of string, required)
        - `optional` (boolean, optional)
      - Any of: `SchemaFragment`
        - `id` (string, required)
        - `kind` (constant, required): Value: `"fragment"`.
        - `label` (string, required)
        - `allowedBlocks` (array of `SchemaBlockType`, required)
        - `initialContent` (array of `ContentNode`, required)
          - `type` (string, required)
          - `attrs` (object, optional)
            - `{key}` (any, optional)
          - `content` (array of `ContentNode`, optional)
          - `marks` (array of `ContentMark`, optional)
            - `type` (string, required)
            - `attrs` (object, optional)
              - `{key}` (any, optional)
          - `text` (string, optional)
        - `optional` (boolean, optional)
  - Any of: Option 2 (null)
- `draftDocument` (any of, required): Current draft projected as an editor document.
  - Any of: `ContentNode`
  - Any of: Option 2 (null)
- `draftHash` (any of, required): Hash of the current local schema draft.
  - Any of: Option 1 (string)
  - Any of: Option 2 (null)
- `hasUnappliedChanges` (boolean, required): Whether the draft differs from the active version.
- `activeVersion` (any of, required)
  - Any of: `SchemaVersionSummary`
    - `id` (string, required): ID of the schema version.
    - `schemaID` (string, required): ID of the local collection schema.
    - `collectionID` (string, required): ID of the collection.
    - `version` (number, required): Sequential schema version number.
    - `hash` (string, required): Hash of the schema definition.
    - `name` (any of, required): Optional schema version name.
      - Any of: Option 1 (string)
      - Any of: Option 2 (null)
    - `reason` (string, required): Reason why the schema version was created. One of: `"auto"`, `"manual"`, `"revert"`, `"schema-migration"`, `"import"`.
    - `sourceVersionID` (any of, required): Source version used for a revert.
      - Any of: Option 1 (string)
      - Any of: Option 2 (null)
    - `active` (boolean, required): Whether this is the active local schema version.
    - `appliedBy` (any of, required): Membership that applied the schema version.
      - Any of: Option 1 (string)
      - Any of: Option 2 (null)
    - `contributorIDs` (array of string, required): Memberships that contributed to the schema version.
    - `createdAt` (string, required): Time when the schema version was created.
    - `updatedAt` (string, required): Time when the schema version name was last updated.
  - Any of: Option 2 (null)
- `createdAt` (string, required): Time when the local schema was first created.
- `updatedAt` (string, required): Time when the local schema draft was last updated.

### 400

400

Content type: `application/json`

Type: one of.

- One of: Option 1 (object)
  - `defined` (constant, required): Value: `true`.
  - `code` (constant, required): Value: `"BAD_REQUEST"`.
  - `status` (constant, required): Value: `400`.
  - `message` (string, required): Default: `"Bad Request"`.
  - `data` (`ValidationErrorData`, optional)
    - `hints` (array of string, optional): Suggested next steps. Wording can change; use error codes and structured data for program logic.
    - `issues` (array of `ValidationIssue`, optional)
      - `message` (string, required)
      - `code` (string, optional)
      - `path` (array of any of, optional)
        - Any of: Option 1 (string)
        - Any of: Option 2 (number)
        - Any of: Option 3 (object)
          - `key` (any of, required)
            - Any of: Option 1 (string)
            - Any of: Option 2 (number)
- One of: Option 2 (object)
  - `defined` (constant, required): Value: `false`.
  - `code` (string, required)
  - `status` (number, required)
  - `message` (string, required)
  - `data` (any, optional)

### 401

401

Content type: `application/json`

Type: one of.

- One of: Option 1 (object)
  - `defined` (constant, required): Value: `true`.
  - `code` (constant, required): Value: `"UNAUTHORIZED"`.
  - `status` (constant, required): Value: `401`.
  - `message` (string, required): Default: `"Unauthorized"`.
  - `data` (`ErrorData`, optional)
    - `hints` (array of string, optional): Suggested next steps. Wording can change; use error codes and structured data for program logic.
- One of: Option 2 (object)
  - `defined` (constant, required): Value: `false`.
  - `code` (string, required)
  - `status` (number, required)
  - `message` (string, required)
  - `data` (any, optional)

### 403

403

Content type: `application/json`

Type: one of.

- One of: Option 1 (object)
  - `defined` (constant, required): Value: `true`.
  - `code` (constant, required): Value: `"FORBIDDEN"`.
  - `status` (constant, required): Value: `403`.
  - `message` (string, required): Default: `"Forbidden"`.
  - `data` (`ForbiddenErrorData`, optional)
    - `hints` (array of string, optional): Suggested next steps. Wording can change; use error codes and structured data for program logic.
    - `missingPermissions` (array of string, optional)
    - `requiredPlan` (constant, optional): Value: `"pro"`.
    - `action` (string, optional): The requested action that was denied.
- One of: Option 2 (object)
  - `defined` (constant, required): Value: `false`.
  - `code` (string, required)
  - `status` (number, required)
  - `message` (string, required)
  - `data` (any, optional)

### 404

404

Content type: `application/json`

Type: one of.

- One of: Option 1 (object)
  - `defined` (constant, required): Value: `true`.
  - `code` (constant, required): Value: `"NOT_FOUND"`.
  - `status` (constant, required): Value: `404`.
  - `message` (string, required): Default: `"Not Found"`.
  - `data` (`ErrorData`, optional)
- One of: Option 2 (object)
  - `defined` (constant, required): Value: `false`.
  - `code` (string, required)
  - `status` (number, required)
  - `message` (string, required)
  - `data` (any, optional)

### 409

409

Content type: `application/json`

Type: one of.

- One of: Option 1 (object)
  - `defined` (constant, required): Value: `true`.
  - `code` (constant, required): Value: `"CONFLICT"`.
  - `status` (constant, required): Value: `409`.
  - `message` (string, required): Default: `"Conflict"`.
  - `data` (`ErrorData`, optional)
- One of: Option 2 (object)
  - `defined` (constant, required): Value: `true`.
  - `code` (constant, required): Value: `"SCHEMA_FIELD_KEY_CONFLICT"`.
  - `status` (constant, required): Value: `409`.
  - `message` (string, required): Default: `"SCHEMA_FIELD_KEY_CONFLICT"`.
  - `data` (`SchemaFieldKeyConflictErrorData`, required)
    - `hints` (array of string, optional): Suggested next steps. Wording can change; use error codes and structured data for program logic.
    - `key` (string, required)
    - `kind` (string, required): One of: `"fragment"`, `"property"`.
    - `fieldIDs` (array of string, required)
- One of: Option 3 (object)
  - `defined` (constant, required): Value: `true`.
  - `code` (constant, required): Value: `"SCHEMA_MIGRATION_IN_PROGRESS"`.
  - `status` (constant, required): Value: `409`.
  - `message` (string, required): Default: `"A schema migration is in progress for this collection"`.
  - `data` (`SchemaMigrationErrorData`, required)
    - `hints` (array of string, optional): Suggested next steps. Wording can change; use error codes and structured data for program logic.
    - `migrationID` (string, required)
- One of: Option 4 (object)
  - `defined` (constant, required): Value: `true`.
  - `code` (constant, required): Value: `"CONTENT_PRECONDITION_FAILED"`.
  - `status` (constant, required): Value: `409`.
  - `message` (string, required): Default: `"CONTENT_PRECONDITION_FAILED"`.
  - `data` (object, required)
    - `hints` (array of string, optional): Suggested next steps. Wording can change; use error codes and structured data for program logic.
    - `field` (string, required): Expected field that didn't match.
    - `current` (any of, required): Current value of the field.
      - Any of: Option 1 (string)
      - Any of: Option 2 (null)
- One of: Option 5 (object)
  - `defined` (constant, required): Value: `false`.
  - `code` (string, required)
  - `status` (number, required)
  - `message` (string, required)
  - `data` (any, optional)

### 429

429

Content type: `application/json`

Type: one of.

- One of: Option 1 (object)
  - `defined` (constant, required): Value: `true`.
  - `code` (constant, required): Value: `"TOO_MANY_REQUESTS"`.
  - `status` (constant, required): Value: `429`.
  - `message` (string, required): Default: `"Too Many Requests"`.
  - `data` (`RateLimitErrorData`, optional)
    - `hints` (array of string, optional): Suggested next steps. Wording can change; use error codes and structured data for program logic.
    - `limit` (string, optional): The limit that was reached: a short-term rate limit, or a monthly API call, AI credit, or spending limit. One of: `"rate"`, `"api-calls"`, `"ai-credits"`, `"spending"`.
    - `retryAfterSeconds` (number, optional): Minimum delay before another attempt, in seconds. Also sent in Retry-After.
- One of: Option 2 (object)
  - `defined` (constant, required): Value: `false`.
  - `code` (string, required)
  - `status` (number, required)
  - `message` (string, required)
  - `data` (any, optional)

### 500

500

Content type: `application/json`

Type: one of.

- One of: Option 1 (object)
  - `defined` (constant, required): Value: `true`.
  - `code` (constant, required): Value: `"INTERNAL_SERVER_ERROR"`.
  - `status` (constant, required): Value: `500`.
  - `message` (string, required): Default: `"Internal Server Error"`.
  - `data` (`ErrorData`, optional)
- One of: Option 2 (object)
  - `defined` (constant, required): Value: `false`.
  - `code` (string, required)
  - `status` (number, required)
  - `message` (string, required)
  - `data` (any, optional)

### 503

503

Content type: `application/json`

Type: one of.

- One of: Option 1 (object)
  - `defined` (constant, required): Value: `true`.
  - `code` (constant, required): Value: `"SERVICE_UNAVAILABLE"`.
  - `status` (constant, required): Value: `503`.
  - `message` (string, required): Default: `"Service Unavailable"`.
  - `data` (`ErrorData`, optional)
- One of: Option 2 (object)
  - `defined` (constant, required): Value: `false`.
  - `code` (string, required)
  - `status` (number, required)
  - `message` (string, required)
  - `data` (any, optional)