Create Composition

Creates a new composition.

To make the composition for one of your managed users, send managedUserId or managedUserExternalId. The composition stays in your account and is yours to edit; the tag lets you list one user’s compositions with getAllCompositions. The managed user must be yours and active: one that is not yours, or does not exist, is answered with 404 and MANAGED_USER_NOT_FOUND, and one that is switched off with 409 and MANAGED_USER_INACTIVE. The tag is set here and does not change afterwards. A copy made with duplicateComposition keeps the tag of the original.

An editor session with the creator surface may call this to start a composition of a widget it built: it sends only name, widgetId (a widget made for the session’s managed user) and content, and the composition is always made for that managed user.

Send databaseSchema to give the composition tables of its own for what visitors send it (the shape, the allowed types and the limits are described on the field). A databaseSchema that cannot be used is refused before anything is created, with 400 and INVALID_DATABASE_SCHEMA. If the composition is created but its tables cannot be made just now, the answer is still 201 and meta.warnings says so.

Leave databaseSchema out and the composition gets the tables its widget declares in its own source (src/lib/meta/database.json), if it declares any: they are made the same way, in a schema of the composition’s own. A widget that keeps nothing leaves the composition without tables. If the widget’s file cannot be used, or its tables cannot be made just now, the answer is still 201 and meta.warnings says so. The widget is read as it was when it was last published (as it is now, when it never was).

The Idempotency-Key header is required (400 without it). Send the same key when you retry, so one composition is created, not two.

POST /compositions

TypeScript SDK

TypeScript

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

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

const compositionsApi = new CompositionsApi(config);

try {
  const composition = await compositionsApi.createComposition({
    // The call needs an idempotency key: reuse the same key if you retry this call.
    idempotencyKey: randomUUID(),
    newComposition: {
      name: 'My New Composition',
      widgetId: '123e4567-e89b-12d3-a456-426614174002',
      content: {}
    }
  });
  
  console.log('Created composition:', composition);
} catch (error) {
  if (error instanceof ResponseError && error.response.status === 400) {
    // The body of the answer says what was wrong
    console.error('Invalid input:', await error.response.json());
  } else {
    console.error('Failed to create composition:', error);
  }
}

201

{
  "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

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"

Body

application/json

name · string · required

Name of the composition

Example:

"My New Composition"

widgetId · string<uuid> · required

ID of the widget this composition is based on

Example:

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

creatorId · string<uuid>

ID of the user creating the composition

Example:

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

content · object

Content data for the composition

Example:

{ "key": "value" }

status · string · default: draft

Initial status of the composition

Example:

"draft"

embedSettings · object

Settings for embedding the composition

Example:

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

design · object

Design settings for the composition

Example:

{
  "theme": "light",
  "colors": { "primary": "#0066ff" }
}

databaseSchema · object

The tables this composition keeps what visitors send it in (votes, ratings, answers). They are made when the composition is created, in a schema of their own that no other composition can reach: in Widgetic's database, or in your own Neon database when you have set one with setPartnerDataDatabase. They are deleted with the composition.

The shape is { "tables": [ ... ] }. A table has a name, a list of columns and, optionally, a list of indexes, and optionally countable. A column has a name and a type, and optionally primaryKey, notNull, unique, default and readable. An index has a name and the columns it covers (1 to 8), and optionally unique. Any other key is refused, except source (see below).

countable and readable are the read policy of the composition's own page: nothing the visitors sent can be read back by the page until you say so. countable: true on a table lets the widget show how many rows it has; readable: true on a column lets it show or total that column's values (a tally of votes, an average rating). Mark only what is safe to show to anyone who opens the page. A column whose name holds email, phone, address, token, password, secret, ip or the like, and a json, jsonb or uuid column, cannot be readable.

• Names (tables, columns, indexes) use lower-case letters, digits and underscores, start with a letter and are at most 63 characters long. A name that starts with _ or pg_ is reserved.
• type is one of text, smallint, integer (or int), bigint, numeric, real, double precision, boolean (or bool), date, timestamp, timestamptz (or timestamp with time zone), uuid, json, jsonb, serial, bigserial.
• default is a number, true or false, a text of at most 500 characters (no backslash), a JSON value for a json or jsonb column, or one of now(), current_timestamp and current_date (date and timestamp columns) and gen_random_uuid() (a uuid column). A serial column numbers itself and has no default.
• A composition declares at most 20 tables, with at most 64 columns and 10 indexes each.

A declaration that cannot be used is refused with 400 and INVALID_DATABASE_SCHEMA; error.details.problems lists what to change. Tables that already exist are never changed or dropped: sending more tables later, when you update the composition, adds the ones that are missing. When the composition is saved but its tables cannot be made just now, the answer says so in meta.warnings: send the same databaseSchema again to retry.

Leave it out and the composition gets the tables its widget declares in its own source (src/lib/meta/database.json), if any. Send { "tables": [] } to give the composition no tables and keep it from getting its widget's.

A composition whose tables were made from its widget's own file reads back with "source": "widget" next to tables. When the widget is published again, a table, a field or an index its file gained is added to them; nothing that exists is changed or dropped, and what a page may read does not change. Send source back as it was and it stays. Leave it out and the tables are yours: no widget's file adds anything to them. It is the only value source can have.

Example:

{
  "tables": [
    {
      "name": "votes",
      "columns": [
        {
          "name": "id",
          "type": "serial",
          "primaryKey": true
        },
        {
          "name": "choice",
          "type": "text",
          "notNull": true
        },
        {
          "name": "created_at",
          "type": "timestamptz",
          "default": "now()"
        }
      ],
      "indexes": [
        {
          "name": "votes_choice_idx",
          "columns": ["choice"]
        }
      ]
    }
  ]
}

projectId · string<uuid>

ID of the project this composition belongs to

Example:

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

managedUserId · string<uuid>

Make the composition for one of your managed users, by Widgetic's id for the user. Send this or managedUserExternalId, not both. The managed user must be yours and active. The composition stays in your account; the tag lets you list one user's compositions and keeps it out of the others' lists. It is set here and does not change afterwards.

Example:

"b7c8d9e0-1f2a-4b3c-8d4e-5f6a7b8c9d0e"

managedUserExternalId · string

The same, by your own identifier for the user, the externalId you gave when you created the managed user (answers show it as externalId). Send this or managedUserId, not both.

Maximum string length: 255

Example:

"user-8841"

Response

201

application/json

Composition created 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