Updating entries or compositions via API: Understanding draft vs published states

When updating entries through the Uniform API, it's important to understand how the state parameter affects which version of your entry gets updated.

The Issue

If you're making API updates to entries and the changes aren't appearing in the editor interface, you may be updating only the published version while viewing the draft version in the editor.

Understanding Entry States

Uniform entries have two states:

• Draft state (CANVAS_DRAFT_STATE = 0) — The working version visible in the editor

• Published state (CANVAS_PUBLISHED_STATE = 64) — The live version served to your website

Solution

To ensure your updates are visible in both the editor and on your live site, you need to update both states.

Updating Entries (ContentClient)

import {

  ContentClient,

  CANVAS_DRAFT_STATE,

  CANVAS_PUBLISHED_STATE,

} from "@uniformdev/canvas";

const client = new ContentClient({

  apiKey: API_KEY,

  projectId: PROJECT_ID,

});

// Fetch the entry (defaults to published state)

const { entries } = await client.getEntries({

  entryIDs: [entryId],

  state: CANVAS_DRAFT_STATE,

});

const entry = entries[0];

// Modify the entry as needed

entry.entry.fields.myField = { type: "text", value: "updated value" };

// Update the draft version (visible in the editor)

await client.upsertEntry({

  state: CANVAS_DRAFT_STATE,

  entry: entry.entry,

});

// If you also want to publish the change immediately:

await client.upsertEntry({

  state: CANVAS_PUBLISHED_STATE,

  entry: entry.entry,

});

Tip: The @uniformdev/canvas package exports a convertEntryToPutEntry(entry) helper that strips read-only properties (like _author) from a GET response, producing a clean body for upsertEntry.

Updating Compositions (CanvasClient)

import {

  CanvasClient,

  CANVAS_DRAFT_STATE,

  CANVAS_PUBLISHED_STATE,

} from "@uniformdev/canvas";

const client = new CanvasClient({

  apiKey: API_KEY,

  projectId: PROJECT_ID,

});

// Fetch the composition

const composition = await client.getCompositionById({

  compositionId,

  state: CANVAS_DRAFT_STATE,

  skipDataResolution: true,

});

// Modify the composition as needed

// ...

// Update the draft version (visible in the editor)

await client.updateComposition({

  state: CANVAS_DRAFT_STATE,

  composition: composition.composition,

});

// If you also want to publish the change immediately:

await client.updateComposition({

  state: CANVAS_PUBLISHED_STATE,

  composition: composition.composition,

});

Best Practice

For most use cases, it's recommended to update the draft version first (CANVAS_DRAFT_STATE) and then publish (CANVAS_PUBLISHED_STATE) if needed. This ensures your changes are visible in the editor and maintains a proper content workflow.