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

apiKeyhttp, bearer, Andesine API key

Use an Andesine API key as a Bearer token

oauthhttp, bearer, Andesine OAuth access token

Use an OAuth access token with andesine:api scope. Send x-workspace-id for workspace operations. Current user permissions apply.

Path parameters

schemaID*string

ID of the local collection schema

Headers

x-workspace-idstring

Required for OAuth: ID of the workspace to access. API keys use their own workspace.

Request body *

application/json

Bodyobject

2 fields

definition*object

The draft's own fields

2 fields

formatVersion*constant

Value: 1

fields*array of any of

Options

Any of

SchemaPropertyobject

id*string

kind*constant

Value: "property"

label*string

type*string

One of: "text", "number", "checkbox", "date", "url", "select", "multi-select"

initialValue*SchemaPropertyValue

Options

Any of

Option 1boolean

Option 2string

Option 3array of string

options*array of string

optionalboolean

Option 2object

id*string

kind*constant

Value: "fragment"

label*string

allowedBlocks*array of SchemaBlockType

initialContent*array of ContentNodeInput

5 fields

type*string

attrsobject

1 field

{key}any

contentarray of ContentNodeInput

Repeats ContentNodeInput

marksarray of ContentMark

2 fields

type*string

attrsobject

1 field

{key}any

textstring

optionalboolean

expectedHashstring

Draft hash from schemas.get; the update fails if the draft changed since

Responses

200OKapplication/json

Bodyobject

10 fields

id*string

ID of the local collection schema

collectionID*string

ID of the collection

enabled*boolean

Whether the collection currently defines a local schema

draft*any of

Current local schema draft

Options

Any of

SchemaDraftDefinitionobject

formatVersion*constant

Value: 1

fields*array of SchemaField

Options

Any of

SchemaPropertyobject

id*string

kind*constant

Value: "property"

label*string

type*string

One of: "text", "number", "checkbox", "date", "url", "select", "multi-select"

initialValue*SchemaPropertyValue

Options

Any of

Option 1boolean

Option 2string

Option 3array of string

options*array of string

optionalboolean

SchemaFragmentobject

id*string

kind*constant

Value: "fragment"

label*string

allowedBlocks*array of SchemaBlockType

initialContent*array of ContentNode

5 fields

type*string

attrsobject

1 field

{key}any

contentarray of ContentNode

Repeats ContentNode

marksarray of ContentMark

2 fields

type*string

attrsobject

1 field

{key}any

textstring

optionalboolean

Option 2null

draftDocument*any of

Current draft projected as an editor document

Options

Any of

ContentNodeobject

type*string

attrsobject

1 field

{key}any

contentarray of ContentNode

Repeats ContentNode

marksarray of ContentMark

2 fields

type*string

attrsobject

1 field

{key}any

textstring

Option 2null

draftHash*any of

Hash of the current local schema draft

Options

Any of

Option 1string

Option 2null

hasUnappliedChanges*boolean

Whether the draft differs from the active version

activeVersion*any of

Options

Any of

SchemaVersionSummaryobject

id*string

ID of the schema version

schemaID*string

ID of the local collection schema

collectionID*string

ID of the collection

version*number

Sequential schema version number

hash*string

Hash of the schema definition

name*any of

Optional schema version name

Options

Any of

Option 1string

Option 2null

reason*string

Reason why the schema version was created

One of: "auto", "manual", "revert", "schema-migration", "import"

sourceVersionID*any of

Source version used for a revert

Options

Any of

Option 1string

Option 2null

active*boolean

Whether this is the active local schema version

appliedBy*any of

Membership that applied the schema version

Options

Any of

Option 1string

Option 2null

contributorIDs*array of string

Memberships that contributed to the schema version

createdAt*string

Time when the schema version was created

updatedAt*string

Time when the schema version name was last updated

Option 2null

createdAt*string

Time when the local schema was first created

updatedAt*string

Time when the local schema draft was last updated

400Bad Requestapplication/json

Bodyone of

Options

One of

Option 1object

defined*constant

Value: true

code*constant

Value: "BAD_REQUEST"

status*constant

Value: 400

message*string

Default: "Bad Request"

dataValidationErrorData

2 fields

hintsarray of string

Suggested next steps. Wording can change; use error codes and structured data for program logic.

issuesarray of ValidationIssue

3 fields

message*string

codestring

patharray of any of

Options

Any of

Option 1string

Option 2number

Option 3object

key*any of

Options

Any of

Option 1string

Option 2number

Option 2object

defined*constant

Value: false

code*string

status*number

message*string

dataany

401Unauthorizedapplication/json

Bodyone of

Options

One of

Option 1object

defined*constant

Value: true

code*constant

Value: "UNAUTHORIZED"

status*constant

Value: 401

message*string

Default: "Unauthorized"

dataErrorData

1 field

hintsarray of string

Suggested next steps. Wording can change; use error codes and structured data for program logic.

Option 2object

defined*constant

Value: false

code*string

status*number

message*string

dataany

403Forbiddenapplication/json

Bodyone of

Options

One of

Option 1object

defined*constant

Value: true

code*constant

Value: "FORBIDDEN"

status*constant

Value: 403

message*string

Default: "Forbidden"

dataForbiddenErrorData

4 fields

hintsarray of string

Suggested next steps. Wording can change; use error codes and structured data for program logic.

missingPermissionsarray of string

requiredPlanconstant

Value: "pro"

actionstring

The requested action that was denied

Option 2object

defined*constant

Value: false

code*string

status*number

message*string

dataany

404Not Foundapplication/json

Bodyone of

Options

One of

Option 1object

defined*constant

Value: true

code*constant

Value: "NOT_FOUND"

status*constant

Value: 404

message*string

Default: "Not Found"

dataErrorData

1 field

hintsarray of string

Suggested next steps. Wording can change; use error codes and structured data for program logic.

Option 2object

defined*constant

Value: false

code*string

status*number

message*string

dataany

409Conflictapplication/json

Bodyone of

Options

One of

Option 1object

defined*constant

Value: true

code*constant

Value: "CONFLICT"

status*constant

Value: 409

message*string

Default: "Conflict"

dataErrorData

1 field

hintsarray of string

Suggested next steps. Wording can change; use error codes and structured data for program logic.

Option 2object

defined*constant

Value: true

code*constant

Value: "SCHEMA_FIELD_KEY_CONFLICT"

status*constant

Value: 409

message*string

Default: "SCHEMA_FIELD_KEY_CONFLICT"

data*SchemaFieldKeyConflictErrorData

4 fields

hintsarray of string

Suggested next steps. Wording can change; use error codes and structured data for program logic.

key*string

kind*string

One of: "fragment", "property"

fieldIDs*array of string

Option 3object

defined*constant

Value: true

code*constant

Value: "SCHEMA_MIGRATION_IN_PROGRESS"

status*constant

Value: 409

message*string

Default: "A schema migration is in progress for this collection"

data*SchemaMigrationErrorData

2 fields

hintsarray of string

Suggested next steps. Wording can change; use error codes and structured data for program logic.

migrationID*string

Option 4object

defined*constant

Value: true

code*constant

Value: "CONTENT_PRECONDITION_FAILED"

status*constant

Value: 409

message*string

Default: "CONTENT_PRECONDITION_FAILED"

data*object

3 fields

hintsarray of string

Suggested next steps. Wording can change; use error codes and structured data for program logic.

field*string

Expected field that didn't match

current*any of

Current value of the field

Options

Any of

Option 1string

Option 2null

Option 5object

defined*constant

Value: false

code*string

status*number

message*string

dataany

429Too Many Requestsapplication/json

Bodyone of

Options

One of

Option 1object

defined*constant

Value: true

code*constant

Value: "TOO_MANY_REQUESTS"

status*constant

Value: 429

message*string

Default: "Too Many Requests"

dataRateLimitErrorData

3 fields

hintsarray of string

Suggested next steps. Wording can change; use error codes and structured data for program logic.

limitstring

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"

retryAfterSecondsnumber

Minimum delay before another attempt, in seconds. Also sent in Retry-After.

Option 2object

defined*constant

Value: false

code*string

status*number

message*string

dataany

500Internal Server Errorapplication/json

Bodyone of

Options

One of

Option 1object

defined*constant

Value: true

code*constant

Value: "INTERNAL_SERVER_ERROR"

status*constant

Value: 500

message*string

Default: "Internal Server Error"

dataErrorData

1 field

hintsarray of string

Suggested next steps. Wording can change; use error codes and structured data for program logic.

Option 2object

defined*constant

Value: false

code*string

status*number

message*string

dataany

503Service Unavailableapplication/json

Bodyone of

Options

One of

Option 1object

defined*constant

Value: true

code*constant

Value: "SERVICE_UNAVAILABLE"

status*constant

Value: 503

message*string

Default: "Service Unavailable"

dataErrorData

1 field

hintsarray of string

Suggested next steps. Wording can change; use error codes and structured data for program logic.

Option 2object

defined*constant

Value: false

code*string

status*number

message*string

dataany

Request

bash

curl --request POST \
  --url 'https://api.andesine.app/schemas/sch_example/draft' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "definition": {
    "formatVersion": 1,
    "fields": [
      {
        "id": "summary",
        "kind": "property",
        "label": "Summary",
        "type": "text",
        "initialValue": "",
        "options": []
      }
    ]
  }
}'

javascript

const response = await fetch("https://api.andesine.app/schemas/sch_example/draft", {
  method: "POST",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "definition": {
      "formatVersion": 1,
      "fields": [
        {
          "id": "summary",
          "kind": "property",
          "label": "Summary",
          "type": "text",
          "initialValue": "",
          "options": []
        }
      ]
    }
  })
});

const data = await response.json();

python

import requests

response = requests.post(
    "https://api.andesine.app/schemas/sch_example/draft",
    headers={
        "Authorization": "Bearer <token>",
        "Content-Type": "application/json",
    },
    json={
        "definition": {
            "formatVersion": 1,
            "fields": [
                {
                    "id": "summary",
                    "kind": "property",
                    "label": "Summary",
                    "type": "text",
                    "initialValue": "",
                    "options": [],
                },
            ],
        },
    },
)

print(response.json())

typescript

import { createClient } from "@andesine/sdk";

const client = createClient({ apiKey: process.env.ANDESINE_API_KEY });

await client.schemas.updateDraft({
  schemaID: "sch_example",
  definition: {
    formatVersion: 1,
    fields: [
      {
        id: "summary",
        kind: "property",
        label: "Summary",
        type: "text",
        initialValue: "",
        options: []
      }
    ]
  }
});

Response

json

{
  "id": "string",
  "collectionID": "string",
  "enabled": true,
  "draft": {
    "formatVersion": 1,
    "fields": [
      {
        "id": "string",
        "kind": "property",
        "label": "string",
        "type": "text",
        "initialValue": true,
        "options": [
          "string"
        ],
        "optional": true
      }
    ]
  },
  "draftDocument": {
    "type": "string",
    "attrs": {},
    "content": [],
    "marks": [
      {
        "type": "string",
        "attrs": {}
      }
    ],
    "text": "string"
  },
  "draftHash": "string",
  "hasUnappliedChanges": true,
  "activeVersion": {
    "id": "string",
    "schemaID": "string",
    "collectionID": "string",
    "version": 0,
    "hash": "string",
    "name": "string",
    "reason": "auto",
    "sourceVersionID": "string",
    "active": true,
    "appliedBy": "string",
    "contributorIDs": [
      "string"
    ],
    "createdAt": "string",
    "updatedAt": "string"
  },
  "createdAt": "string",
  "updatedAt": "string"
}

json

{
  "defined": true,
  "code": "BAD_REQUEST",
  "status": 400,
  "message": "Bad Request",
  "data": {
    "hints": [
      "string"
    ],
    "issues": [
      {
        "message": "string",
        "code": "string",
        "path": [
          "string"
        ]
      }
    ]
  }
}

json

{
  "defined": true,
  "code": "UNAUTHORIZED",
  "status": 401,
  "message": "Unauthorized",
  "data": {
    "hints": [
      "string"
    ]
  }
}

json

{
  "defined": true,
  "code": "FORBIDDEN",
  "status": 403,
  "message": "Forbidden",
  "data": {
    "hints": [
      "string"
    ],
    "missingPermissions": [
      "string"
    ],
    "requiredPlan": "pro",
    "action": "string"
  }
}

json

{
  "defined": true,
  "code": "NOT_FOUND",
  "status": 404,
  "message": "Not Found",
  "data": {
    "hints": [
      "string"
    ]
  }
}

json

{
  "defined": true,
  "code": "CONFLICT",
  "status": 409,
  "message": "Conflict",
  "data": {
    "hints": [
      "string"
    ]
  }
}

json

{
  "defined": true,
  "code": "TOO_MANY_REQUESTS",
  "status": 429,
  "message": "Too Many Requests",
  "data": {
    "hints": [
      "string"
    ],
    "limit": "rate",
    "retryAfterSeconds": 0
  }
}

json

{
  "defined": true,
  "code": "INTERNAL_SERVER_ERROR",
  "status": 500,
  "message": "Internal Server Error",
  "data": {
    "hints": [
      "string"
    ]
  }
}

json

{
  "defined": true,
  "code": "SERVICE_UNAVAILABLE",
  "status": 503,
  "message": "Service Unavailable",
  "data": {
    "hints": [
      "string"
    ]
  }
}