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

`POST https://api.andesine.app/entries`

Creates an entry and its initial document, in the collection given by collectionID, collectionPath, or collectionSlugPath (the top level by default). The name defaults to Untitled, or comes from the title of the supplied document or mdx. fields sets property values and fragment MDX by field name or key. path places the entry at a full name path and creates missing parent collections; a name already used there is a conflict. A repeated request with the same Idempotency-Key header returns the first result for 24 hours. Creation selects an available sibling name with a numeric suffix when needed. Names are trimmed and NFC-normalized. Derived URL slugs must be unique across sibling entries and collections, including case and punctuation variants. Names cannot contain a slash or equal a single dot or two dots. A collection schema sets the initial content without a document; a document must match it.

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

### 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`

- `id` (string, optional): ID of the entry.
- `name` (string, optional): Name of the entry.
- `collectionID` (string, optional): ID of the collection this entry belongs to.
- `document` (object, optional): ProseMirror JSON of the entry document, which must match the editor and the collection schema.
  - `type` (string, required)
  - `attrs` (object, optional)
    - `{key}` (any, optional)
  - `content` (array of `ContentNodeInput`, optional)
    - `type` (string, required)
    - `attrs` (object, optional)
      - `{key}` (any, optional)
    - `content` (array of `ContentNodeInput`, 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)
- `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.
- `fields` (object, optional): Field values by name or key, set on the initial content.
  - `{key}` (any of, optional): Property value, or MDX for a fragment.
    - Any of: Option 1 (string)
    - Any of: Option 2 (number)
    - Any of: Option 3 (boolean)
    - Any of: Option 4 (array of string)
    - Any of: Option 5 (null)
- `path` (string, optional): Full name path of the entry, for example /Guides/Setup.
- `collectionPath` (string, optional): Name path of an existing parent collection.
- `collectionSlugPath` (string, optional): Slug path of an existing parent collection.

## Responses

### 200

OK

Content type: `application/json`

Type: `EntrySummary`.

- `id` (string, required): ID of the entry.
- `name` (string, required): Name of the entry.
- `order` (string, required): LexoRank order of the entry.
- `collectionID` (string, optional): ID of the collection this entry belongs to.
- `path` (string, required)
- `slugPath` (string, required)

### 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_NAME_CONFLICT"`.
  - `status` (constant, required): Value: `409`.
  - `message` (string, required): Default: `"CONTENT_NAME_CONFLICT"`.
  - `data` (`ContentNameConflictErrorData`, required)
    - `hints` (array of string, optional): Suggested next steps. Wording can change; use error codes and structured data for program logic.
    - `name` (string, required)
    - `slug` (string, required): Conflicting URL slug derived from the name.
    - `parentID` (any of, required)
      - Any of: Option 1 (string)
      - Any of: Option 2 (null)
- One of: Option 3 (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 4 (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 5 (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 6 (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 7 (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 8 (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 9 (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)