Update an entry

put

https://api.andesine.app/entries/{id}

Renames the entry, replaces its content with document or mdx, or edits it with operations (with name, also renames). document and mdx need expectedHash, the hash of the content they replace (from entries.get); a different current hash returns CONTENT_HASH_MISMATCH. Operations anchor on block IDs, unique text, and field keys from entries.get with contentFormat blocks; expectedHash is optional for them, and a missing or ambiguous anchor returns CONTENT_OPERATION_INVALID. Only the changed blocks change, so live edits elsewhere are kept. Current content without a version is first saved as an auto version. version also saves the new content as a named version. Rejects names already used by a sibling entry or collection. expectedName applies the update only when the entry still has that name. An active schema migration can block this action. A repeated request with the same Idempotency-Key header returns the first result for 24 hours.

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

id*string

ID of the entry to be updated

Headers

x-workspace-idstring

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

Request body

application/json

Bodyobject

7 fields

namestring

New name of the entry

documentobject

ProseMirror JSON of the entry document, which must match the editor and the collection schema

5 fields

type*string

attrsobject

1 field

{key}any

contentarray 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

marksarray of ContentMark

2 fields

type*string

attrsobject

1 field

{key}any

textstring

mdxstring

Content as MDX: the title as H1, properties as elements in place, fragments as elements, and images as asset:; frontmatter properties are also read, and entries.update and versions.create import image URLs

operationsarray of any of

Edit operations, applied in order; all or none apply

Options

Any of

Option 1object

Replace text in one block

type*constant

Value: "replaceText"

find*string

Text that occurs exactly once in the MDX of one block

replace*string

Replacement text

Option 2object

Replace a block with zero or more blocks

type*constant

Value: "replaceBlock"

id*string

mdx*string

Blocks as MDX, without a title

Option 3object

Insert blocks

type*constant

Value: "insertBlocks"

mdx*string

Blocks as MDX, without a title

beforestring

ID of the block to insert before

afterstring

ID of the block to insert after

positionstring

Insert at the start or the end

One of: "start", "end"

fragmentstring

Fragment key for position

Option 4object

Delete blocks

type*constant

Value: "deleteBlocks"

ids*array of string

Option 5object

Set a property value or the content of a fragment

type*constant

Value: "setField"

key*string

Field name or key

value*any of

Property value, or MDX for a fragment

Options

Any of

Option 1string

Option 2number

Option 3boolean

Option 4array of string

Option 5null

expectedHashstring

Hash of the content that the change is based on

expectedNamestring

Name the entry must still have

versionobject

Also save the new content as a version

1 field

namestring

Version name

Responses

200OKapplication/json

Bodyobject

2 fields

hash*string

Hash of the current content after the update

versionEntryVersionSummary

The version saved with version

10 fields

id*string

ID of the version

entryID*string

ID of the versioned entry

entryName*string

Entry name stored in the version

hash*string

Hash of the version content

name*any of

Optional name of the version

Options

Any of

Option 1string

Option 2null

reason*string

Reason why the 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

contributorIDs*array of string

Memberships that contributed to the version

createdAt*string

Time when the version was created

updatedAt*string

Time when the version name 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: true

code*constant

Value: "CONTENT_FORMAT_INVALID"

status*constant

Value: 400

message*string

Default: "CONTENT_FORMAT_INVALID"

data*object

3 fields

hintsarray of string

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

linenumber

Line of the error in the source

columnnumber

Column of the error in the source

Option 3object

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: "CONTENT_NAME_CONFLICT"

status*constant

Value: 409

message*string

Default: "CONTENT_NAME_CONFLICT"

data*ContentNameConflictErrorData

4 fields

hintsarray of string

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

name*string

slug*string

Conflicting URL slug derived from the name

parentID*any of

Options

Any of

Option 1string

Option 2null

Option 3object

defined*constant

Value: true

code*constant

Value: "CONTENT_SCHEMA_INVALID"

status*constant

Value: 409

message*string

Default: "CONTENT_SCHEMA_INVALID"

data*ContentSchemaInvalidErrorData

5 fields

hintsarray of string

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

entryIDstring

versionIDstring

revisionID*any of

Options

Any of

Option 1string

Option 2null

issues*array of ContentSchemaIssue

4 fields

code*string

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

path*array of any of

Options

Any of

Option 1string

Option 2number

fieldIDstring

Option 4object

defined*constant

Value: true

code*constant

Value: "CONTENT_HASH_MISMATCH"

status*constant

Value: 409

message*string

Default: "CONTENT_HASH_MISMATCH"

data*object

3 fields

hintsarray of string

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

hash*string

Hash of the current content

changedIDsarray of string

Entries of a bulk call that kept the change, because they were edited meanwhile

Option 5object

defined*constant

Value: true

code*constant

Value: "CONTENT_OPERATION_INVALID"

status*constant

Value: 409

message*string

Default: "CONTENT_OPERATION_INVALID"

data*object

3 fields

hintsarray of string

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

index*number

Index of the operation that failed

reason*string

Why the operation's anchor didn't match

One of: "not_found", "ambiguous"

Option 6object

defined*constant

Value: true

code*constant

Value: "CONTENT_LINK_INVALID"

status*constant

Value: 409

message*string

Default: "CONTENT_LINK_INVALID"

data*object

2 fields

hintsarray of string

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

href*string

Link that doesn't point to an entry

Option 7object

defined*constant

Value: true

code*constant

Value: "CONTENT_IMAGE_UNAVAILABLE"

status*constant

Value: 409

message*string

Default: "CONTENT_IMAGE_UNAVAILABLE"

data*object

4 fields

hintsarray of string

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

url*string

Image URL in the content

assetID*string

Imported image

assetStatus*string

Status of the image when the write stopped waiting

Option 8object

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 9object

defined*constant

Value: true

code*constant

Value: "IDEMPOTENCY_KEY_IN_PROGRESS"

status*constant

Value: 409

message*string

Default: "A request with this Idempotency-Key is in progress"

data*ErrorData

1 field

hintsarray of string

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

Option 10object

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 11object

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 12object

defined*constant

Value: false

code*string

status*number

message*string

dataany

422Unprocessable Contentapplication/json

Bodyone of

Options

One of

Option 1object

defined*constant

Value: true

code*constant

Value: "IDEMPOTENCY_KEY_REUSED"

status*constant

Value: 422

message*string

Default: "This Idempotency-Key was used with a different request"

data*ErrorData

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

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 PUT \
  --url 'https://api.andesine.app/entries/ent_example' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
  "name": "Installation"
}'

javascript

const response = await fetch("https://api.andesine.app/entries/ent_example", {
  method: "PUT",
  headers: {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "name": "Installation"
  })
});

const data = await response.json();

python

import requests

response = requests.put(
    "https://api.andesine.app/entries/ent_example",
    headers={
        "Authorization": "Bearer <token>",
        "Content-Type": "application/json",
    },
    json={
        "name": "Installation",
    },
)

print(response.json())

typescript

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

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

await client.entries.update({
  id: "ent_example",
  name: "Installation"
});

Response

json

{
  "hash": "string",
  "version": {
    "id": "string",
    "entryID": "string",
    "entryName": "string",
    "hash": "string",
    "name": "string",
    "reason": "auto",
    "sourceVersionID": "string",
    "contributorIDs": [
      "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": "IDEMPOTENCY_KEY_REUSED",
  "status": 422,
  "message": "This Idempotency-Key was used with a different request",
  "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"
    ]
  }
}