Create Widget

Creates a widget for your account: a named record with a type and some starting content, on a canvas of its own (or one of yours that you name). It costs no credits and has no code yet; the code is generated for it afterwards. The new widget is yours, and you can list it with getWidgets. A widget is a draft until you say otherwise (isDraft: false).

If a step after the widget was saved does not go through, the widget is still created, and data.warnings says what did not. Read it before relying on the widget.

A widget can be placed on one of your canvases (canvasId), in a project you can edit (projectId) or in an organization where you may create widgets (organizationId). Naming anything you cannot use is refused with 403, and the answer is the same whether it exists or not.

To make the widget for one of your managed users, send managedUserId or managedUserExternalId. The widget stays in your account and is yours to edit; the tag lets you list one user’s widgets with getWidgets. 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.

This call has a limit of its own: 120 per minute for each account (ask Widgetic if you need more). Past that the call is answered with 429 and a Retry-After. A widget has no database of its own: what the visitors of a composition leave is kept in the tables of that composition, made when the composition is. The Idempotency-Key header is required; send the same key when you retry, so one widget is created, not two.

POST /widgets

Create Widget

cURL

curl --request POST \
  --url https://api.widgetic.com/v1/widgets \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "name": "New Chart Widget",
  "type": "chart",
  "content": {
    "chartType": "bar",
    "dataSource": "api"
  },
  "isPublic": false,
  "isDraft": false,
  "canvasId": "abc12345-def6-7890-ab12-cd3456ef7890",
  "projectId": "7c1e2f30-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "organizationId": "5e2d3f4a-1b6c-4a1f-8b9c-3c2d4e5f6a7b",
  "workspaceType": "personal",
  "managedUserId": "b7c8d9e0-1f2a-4b3c-8d4e-5f6a7b8c9d0e",
  "managedUserExternalId": "user-8841"
}
'

201

{
  "success": true,
  "data": {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "creatorId": "a4d8b6e9-3c2d-4a1f-8b9c-5e2d3f4a1b6c",
    "name": "Chart Widget",
    "description": "Interactive chart widget for data visualization",
    "type": "chart",
    "content": {
      "chartType": "bar",
      "dataSource": "api"
    },
    "isPublic": false,
    "isDraft": true,
    "shareId": "shwgt_7f1d34acf2",
    "createdAt": "2025-09-15T10:23:00.000Z",
    "updatedAt": "2025-09-16T08:12:45.000Z",
    "jsPath": "/widgets/chart/main.js",
    "canvasId": "9f0c6b54-3e8f-4a2a-8b7d-1c5c6d9e0a1b",
    "repoId": "user/chart-widget",
    "databaseId": "widget_3fa85f64_5717_4562_b3fc_2c963f66afa6",
    "version": 1,
    "lastCommitSha": "a1b2c3d4e5f6g7h8i9j0",
    "organizationId": "5e2d3f4a-1b6c-4a1f-8b9c-3c2d4e5f6a7b",
    "projectFolder": "marketing/q4-launch",
    "workspaceType": "personal",
    "managedUserId": "b7c8d9e0-1f2a-4b3c-8d4e-5f6a7b8c9d0e"
  },
  "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

A unique value (a UUID is fine) that makes a retry of this request safe.

Body

application/json

What a new widget starts from. Only the fields listed here are used. The widget is created without code: it is a record with a name, a type and some starting content, on a canvas (a new one, unless you name one of yours). It has no database: what the visitors of a composition leave is kept in the tables of that composition.

name · string · required

Name of the widget.

Minimum string length: 1

Example:

"New Chart Widget"

type · string · required

What kind of widget this is, as a label of your choosing (for example chart, form, gallery).

Minimum string length: 1

Example:

"chart"

content · object · required

Starting content for the widget. An empty object is fine.

Example:

{ "chartType": "bar", "dataSource": "api" }

isPublic · boolean · default: false

Whether the widget is public.

Example:

false

isDraft · boolean · default: true

Whether the widget starts as a draft. A widget created without this is a draft.

Example:

false

canvasId · string<uuid>

Put the widget on this existing canvas instead of a new one. You must own the canvas.

Example:

"abc12345-def6-7890-ab12-cd3456ef7890"

projectId · string<uuid>

Project to file the widget in. You must be able to edit the project.

Example:

"7c1e2f30-4a5b-4c6d-8e9f-0a1b2c3d4e5f"

organizationId · string<uuid>

Organization the widget belongs to. You must be a member who may create widgets there.

Example:

"5e2d3f4a-1b6c-4a1f-8b9c-3c2d4e5f6a7b"

workspaceType · enum<string>

Whether the widget lives in your personal workspace or in an organization's.

Available options: personal, organization

Example:

"personal"

managedUserId · string<uuid>

Make the widget 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 widget stays in your account; the tag lets you list one user's widgets 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

Widget created successfully

success · boolean · required

data · object · required

Represents a widget in the system.

Show child attributes

Example:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "creatorId": "a4d8b6e9-3c2d-4a1f-8b9c-5e2d3f4a1b6c",
  "name": "Chart Widget",
  "description": "Interactive chart widget for data visualization",
  "type": "chart",
  "content": { "chartType": "bar", "dataSource": "api" },
  "isPublic": false,
  "isDraft": true,
  "shareId": "shwgt_7f1d34acf2",
  "createdAt": "2025-09-15T10:23:00.000Z",
  "updatedAt": "2025-09-16T08:12:45.000Z",
  "jsPath": "/widgets/chart/main.js",
  "canvasId": "9f0c6b54-3e8f-4a2a-8b7d-1c5c6d9e0a1b",
  "repoId": "user/chart-widget",
  "databaseId": "widget_3fa85f64_5717_4562_b3fc_2c963f66afa6",
  "version": 1,
  "lastCommitSha": "a1b2c3d4e5f6g7h8i9j0",
  "organizationId": "5e2d3f4a-1b6c-4a1f-8b9c-3c2d4e5f6a7b",
  "projectFolder": "marketing/q4-launch",
  "workspaceType": "personal",
  "managedUserId": "b7c8d9e0-1f2a-4b3c-8d4e-5f6a7b8c9d0e"
}

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