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

# Create an entry version

`POST https://api.andesine.app/entries/{entryID}/versions`

Saves a version of the current entry content, or of supplied document (ProseMirror JSON) or mdx, which must match the editor and the entry's collection schema. Never changes the current content. Optionally assigns a name. Publish the version with publishing.publishEntry. A repeated request with the same Idempotency-Key header returns the first result for 24 hours.

Required API key permissions: versions. 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

- `entryID` (string, required): ID of the entry to version.

### 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 optional.

Content type: `application/json`

- `name` (string, optional): Optional version name.
- `document` (`ContentNodeInput`, optional): ProseMirror JSON of the version; the current content when omitted.
  - `type` (string, required)
  - `attrs` (object, optional)
    - `{key}` (any, optional)
  - `content` (array of `ContentNodeInput`, optional)
  - `marks` (array of `ContentMark`, optional)
  - `text` (string, optional)
- `mdx` (string, optional): Content as MDX: the title as H1, properties as <Property name value /> elements in place, fragments as <Fragment name> elements, and images as asset:<assetID>; frontmatter properties are also read, and entries.update and versions.create import image URLs.

## Responses

### 200

OK

Content type: `application/json`

Type: `EntryVersion`.

- `id` (string, required): ID of the version.
- `entryID` (string, required): ID of the versioned entry.
- `entryName` (string, required): Entry name stored in the version.
- `hash` (string, required): Hash of the version content.
- `name` (any of, required): Optional name of the version.
  - Any of: Option 1 (string)
  - Any of: Option 2 (null)
- `reason` (string, required): Reason why the 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)
- `contributorIDs` (array of string, required): Memberships that contributed to the version.
- `createdAt` (string, required): Time when the version was created.
- `updatedAt` (string, required): Time when the version name was last updated.
- `schema` (any of, required)
  - Any of: `ContentSchemaMetadata`
    - `revisionID` (string, required): Recorded effective schema revision.
    - `hash` (string, required): Hash of the effective schema definition.
  - Any of: Option 2 (null)
- `document` (object, required): ProseMirror JSON stored in the version.
  - `type` (string, required)
  - `attrs` (object, optional)
    - `{key}` (any, optional)
  - `content` (array of `ContentNode`, optional)
    - `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)
  - `marks` (array of `ContentMark`, optional)
  - `text` (string, optional)

### 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: `true`.
  - `code` (constant, required): Value: `"CONTENT_FORMAT_INVALID"`.
  - `status` (constant, required): Value: `400`.
  - `message` (string, required): Default: `"CONTENT_FORMAT_INVALID"`.
  - `data` (object, required)
    - `hints` (array of string, optional): Suggested next steps. Wording can change; use error codes and structured data for program logic.
    - `line` (number, optional): Line of the error in the source.
    - `column` (number, optional): Column of the error in the source.
- One of: Option 3 (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: `"CONTENT_SCHEMA_INVALID"`.
  - `status` (constant, required): Value: `409`.
  - `message` (string, required): Default: `"CONTENT_SCHEMA_INVALID"`.
  - `data` (`ContentSchemaInvalidErrorData`, required)
    - `hints` (array of string, optional): Suggested next steps. Wording can change; use error codes and structured data for program logic.
    - `entryID` (string, optional)
    - `versionID` (string, optional)
    - `revisionID` (any of, required)
      - Any of: Option 1 (string)
      - Any of: Option 2 (null)
    - `issues` (array of `ContentSchemaIssue`, required)
      - `code` (string, required): One of: `"invalid_schema"`, `"invalid_structure"`, `"missing_field"`, `"unknown_field"`, `"duplicate_field"`, `"field_kind_mismatch"`, `"field_key_mismatch"`, `"property_type_mismatch"`, `"invalid_property_value"`, `"invalid_field_options"`, `"invalid_allowed_blocks"`, `"invalid_fragment_content"`.
      - `message` (string, required)
      - `path` (array of any of, required)
        - Any of: Option 1 (string)
        - Any of: Option 2 (number)
      - `fieldID` (string, optional)
- One of: Option 3 (object)
  - `defined` (constant, required): Value: `true`.
  - `code` (constant, required): Value: `"CONTENT_LINK_INVALID"`.
  - `status` (constant, required): Value: `409`.
  - `message` (string, required): Default: `"CONTENT_LINK_INVALID"`.
  - `data` (object, required)
    - `hints` (array of string, optional): Suggested next steps. Wording can change; use error codes and structured data for program logic.
    - `href` (string, required): Link that doesn't point to an entry.
- One of: Option 4 (object)
  - `defined` (constant, required): Value: `true`.
  - `code` (constant, required): Value: `"CONTENT_IMAGE_UNAVAILABLE"`.
  - `status` (constant, required): Value: `409`.
  - `message` (string, required): Default: `"CONTENT_IMAGE_UNAVAILABLE"`.
  - `data` (object, required)
    - `hints` (array of string, optional): Suggested next steps. Wording can change; use error codes and structured data for program logic.
    - `url` (string, required): Image URL in the content.
    - `assetID` (string, required): Imported image.
    - `assetStatus` (string, required): Status of the image when the write stopped waiting.
- One of: Option 5 (object)
  - `defined` (constant, required): Value: `true`.
  - `code` (constant, required): Value: `"IDEMPOTENCY_KEY_IN_PROGRESS"`.
  - `status` (constant, required): Value: `409`.
  - `message` (string, required): Default: `"A request with this Idempotency-Key is in progress"`.
  - `data` (`ErrorData`, required)
- One of: Option 6 (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 7 (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 8 (object)
  - `defined` (constant, required): Value: `false`.
  - `code` (string, required)
  - `status` (number, required)
  - `message` (string, required)
  - `data` (any, optional)

### 422

422

Content type: `application/json`

Type: one of.

- One of: Option 1 (object)
  - `defined` (constant, required): Value: `true`.
  - `code` (constant, required): Value: `"IDEMPOTENCY_KEY_REUSED"`.
  - `status` (constant, required): Value: `422`.
  - `message` (string, required): Default: `"This Idempotency-Key was used with a different request"`.
  - `data` (`ErrorData`, required)
- One of: Option 2 (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)