Update Composition

Updates a specific composition.

The Idempotency-Key header is required (400 without it). Send the same key when you retry.

An editor session (see createManagedUserEditorSession) can send only name, content, design and embedSettings, and only for a composition made for its managed user. A body that names any other field is refused with 403 and EDITOR_SESSION_FIELD_NOT_ALLOWED.

Send databaseSchema to add tables to the composition: the tables that are missing are made, and the ones that exist are left as they are. A databaseSchema that cannot be used is refused before anything is saved, with 400 and INVALID_DATABASE_SCHEMA. If the composition is saved but its tables cannot be made just now, the answer is still 200 and meta.warnings says so.

When several people edit the same composition. A save that carries content can name the content version it started from in the If-Match header (the contentVersion of the composition you read, or the ETag of an earlier answer). If somebody saved the content since, nothing is overwritten: the save is refused with 412 and CONTENT_VERSION_MISMATCH, and error.details.currentVersion is the version to start again from. For a composition a team shares, error.details also says who got there first: lastEditedBy ({ id, name }, or null when nobody can be named) and lastEditedAt. An editor session, or a call made for one managed user, is told the version only. A save without If-Match still goes through, and the other person’s change is replaced, as it always was.

PUT /compositions/{id}

TypeScript SDK

TypeScript

import { randomUUID } from 'node:crypto';
import { Configuration, CompositionsApi } from '@widgetic/api-sdk-ts';

const config = new Configuration({
  apiKey: 'YOUR_API_KEY'
});

const compositionsApi = new CompositionsApi(config);

try {
  const composition = await compositionsApi.updateComposition({
    id: 'composition_123',
    // The call needs an idempotency key: reuse the same key if you retry this call.
    idempotencyKey: randomUUID(),
    updateComposition: {
      name: 'Updated Composition',
      content: {
        // Updated content object
      },
      embedSettings: {
        width: '800',
        height: '600'
      }
    }
  });
  console.log('Updated composition:', composition.data);
} catch (error) {
  if (error.response?.status === 404) {
    console.error('Composition not found');
  } else {
    console.error('Failed to update composition:', error);
  }
}

200

{
  "success": true,
  "data": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "creatorId": "123e4567-e89b-12d3-a456-426614174001",
    "widgetId": "123e4567-e89b-12d3-a456-426614174002",
    "name": "My Composition",
    "content": {
      "key": "value"
    },
    "contentVersion": 3,
    "status": "draft",
    "createdAt": "2023-01-01T00:00:00Z",
    "updatedAt": "2023-01-02T00:00:00Z",
    "embedSettings": {
      "width": "100%",
      "height": "500px"
    },
    "design": {
      "theme": "light",
      "colors": {
        "primary": "#0066ff"
      }
    },
    "databaseId": "123e4567-e89b-12d3-a456-426614174003",
    "projectId": "123e4567-e89b-12d3-a456-426614174004",
    "managedUserId": "b7c8d9e0-1f2a-4b3c-8d4e-5f6a7b8c9d0e",
    "direct": true,
    "lastEditedBy": {},
    "lastEditedAt": "2026-10-28T14:32:00Z"
  },
  "meta": {
    "page": 1,
    "size": 20,
    "total": 135,
    "limit": 20,
    "offset": 0,
    "hasNextPage": true,
    "hasPreviousPage": false,
    "nextCursor": "<string>",
    "warnings": [
      "<string>"
    ]
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

If-Match · string

Optional content version from contentVersion or an ETag ("3", 3, or *). Read only when the body has content.

Idempotency-Key · string · required

Required: a call without it is refused with 400. A key of your own that names this one request; a UUID is ideal. It is 8 to 50 characters of letters, digits, - and _. Send the same key again when you retry (after a timeout, a dropped connection or a 5xx) and the call is carried out once: the retry gets the first answer back, marked X-Idempotency-Cached: true. The same key with a different body is refused with 422, and a retry that arrives while the first call is still running with 409 (see Retry-After).

Required string length: 8 - 50

Pattern: ^[a-zA-Z0-9_-]{8,50}$

Example:

"9b2d6f0a-3c41-4e5a-8d77-1f2e3a4b5c6d"

X-Managed-User-Id · string<uuid>

The id Widgetic gave the managed user (POST /managed-users). Makes this call for one of your managed users, so that a mistake in your own code cannot reach another customer's work. Send this header, or the other one, never both. Left out, the call works on your whole account, as it always has. With it, the call reaches only that user's compositions and workflows: a list shows only theirs, a composition or a workflow the call makes is filed under them, and one of another user, or one that does not exist, answers 404 (the same answer, so the call cannot be used to find out what another customer has). A managed user that is not yours answers 404 with MANAGED_USER_NOT_FOUND. An empty, repeated or malformed header is 400 with MANAGED_USER_SCOPE_INVALID; an empty header is never read as no header. A call that is about the whole account, such as the list of your managed users, is refused with 403 and MANAGED_USER_SCOPE_ROUTE_NOT_AVAILABLE: send it without the header. Only your API key can send it. The header is a limit the call asks for: whoever holds the key can leave it out, so for a credential that a customer's browser holds, use an editor session. An Idempotency-Key is kept apart for each managed user.

Example:

"3f2b8c1e-7a4d-4e0b-9c55-2d1a6b7e8f90"

X-Managed-User-External-Id · string

Your own id for the managed user (its externalId), when you do not keep Widgetic's. Makes this call for one of your managed users, so that a mistake in your own code cannot reach another customer's work. Send this header, or the other one, never both. Left out, the call works on your whole account, as it always has. With it, the call reaches only that user's compositions and workflows: a list shows only theirs, a composition or a workflow the call makes is filed under them, and one of another user, or one that does not exist, answers 404 (the same answer, so the call cannot be used to find out what another customer has). A managed user that is not yours answers 404 with MANAGED_USER_NOT_FOUND. An empty, repeated or malformed header is 400 with MANAGED_USER_SCOPE_INVALID; an empty header is never read as no header. A call that is about the whole account, such as the list of your managed users, is refused with 403 and MANAGED_USER_SCOPE_ROUTE_NOT_AVAILABLE: send it without the header. Only your API key can send it. The header is a limit the call asks for: whoever holds the key can leave it out, so for a credential that a customer's browser holds, use an editor session. An Idempotency-Key is kept apart for each managed user.

Required string length: 1 - 255

Example:

"customer-1042"

Path Parameters

id · string<uuid> · required

Composition ID

Body

application/json

name · string

Updated name of the composition

Example:

"Updated Composition Name"

widgetId · string<uuid>

Updated widget ID

Example:

"123e4567-e89b-12d3-a456-426614174002"

content · object

Updated content data

Example:

{ "key": "new value" }

status · string

Updated status

Example:

"published"

embedSettings · object

Updated embed settings

Example:

{ "width": "100%", "height": "600px" }

design · object

Updated design settings

Example:

{
  "theme": "dark",
  "colors": { "primary": "#0044cc" }
}

databaseSchema · object

Tables to make for the composition, in the shape createComposition takes ({ "tables": [ ... ] }, with the same names, types, defaults and limits). Only the tables that are missing are made. A table that already exists is never changed or dropped: it keeps its columns, so a column added to the declaration is not added to it. (Tables made from the widget's own file are the one exception, brought up to date when the widget is published; see source on createComposition.) A declaration that cannot be used is refused with 400 and INVALID_DATABASE_SCHEMA. When the composition is saved but its tables cannot be made just now, meta.warnings says so: send the same databaseSchema again to retry.

projectId · string<uuid>

Updated project ID

Example:

"123e4567-e89b-12d3-a456-426614174004"

Response

200

application/json

Composition updated successfully

success · boolean · required

Always true on a success.

Example:

true

data · object · required

Show child attributes

Example:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "creatorId": "123e4567-e89b-12d3-a456-426614174001",
  "widgetId": "123e4567-e89b-12d3-a456-426614174002",
  "name": "My Composition",
  "content": { "key": "value" },
  "contentVersion": 3,
  "status": "draft",
  "createdAt": "2023-01-01T00:00:00Z",
  "updatedAt": "2023-01-02T00:00:00Z",
  "embedSettings": { "width": "100%", "height": "500px" },
  "design": {
    "theme": "light",
    "colors": { "primary": "#0066ff" }
  },
  "databaseId": "123e4567-e89b-12d3-a456-426614174003",
  "projectId": "123e4567-e89b-12d3-a456-426614174004",
  "managedUserId": "b7c8d9e0-1f2a-4b3c-8d4e-5f6a7b8c9d0e",
  "direct": true,
  "lastEditedBy": {},
  "lastEditedAt": "2026-10-28T14:32:00Z"
}

meta · object

Extra information about the answer: where a page sits in a list, the cursor of the next page, or warnings about a call that succeeded with a caveat.

Show child attributes