> ## Documentation Index > Fetch the complete documentation index at: https://widgetic.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /openapi/widgetic-api-public.json post /widgets openapi: 3.0.0 info: title: Widgetic API Gateway version: 1.0.0 description: API documentation for the Widgetic API Gateway license: name: Widgetic Integration License url: https://docs.widgetic.com/resources/license servers: - url: https://api.widgetic.com/v1 description: Production server variables: env: default: production description: Environment apiUrl: default: https://api.widgetic.com description: API URL apiVersion: default: /v1 description: API Version path prefix security: [] tags: [] paths: /widgets: post: tags: - Widgets summary: Create Widget description: > 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. operationId: createWidget parameters: - in: header name: Idempotency-Key required: true schema: type: string description: >- A unique value (a UUID is fine) that makes a retry of this request safe. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NewWidget' responses: '201': description: Widget created successfully content: application/json: schema: type: object properties: success: type: boolean data: allOf: - $ref: '#/components/schemas/Widget' - type: object properties: warnings: type: array description: >- What did not go through, when the widget was created without all of its parts (for example, the canvas it sits on could not be told that this is its main widget). Absent when everything did. items: type: string meta: $ref: '#/components/schemas/ResponseMeta' required: - success - data '400': description: Invalid request, or the `Idempotency-Key` header is missing. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: > The key's role may not use this endpoint, or `canvasId`, `projectId` or `organizationId` names something you may not use. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: >- The managed user named by `managedUserId` or `managedUserExternalId` is not one of yours (`MANAGED_USER_NOT_FOUND`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: >- The managed user is switched off, so nothing new can be made for it (`MANAGED_USER_INACTIVE`). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Too many widgets created in a minute. See the Retry-After header. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - apiKeyAuth: [] components: schemas: NewWidget: type: object description: > 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. required: - name - type - content properties: name: type: string minLength: 1 description: Name of the widget. example: New Chart Widget type: type: string minLength: 1 description: >- What kind of widget this is, as a label of your choosing (for example chart, form, gallery). example: chart content: type: object description: Starting content for the widget. An empty object is fine. additionalProperties: true example: chartType: bar dataSource: api isPublic: type: boolean default: false description: Whether the widget is public. example: false isDraft: type: boolean default: true description: >- Whether the widget starts as a draft. A widget created without this is a draft. example: false canvasId: type: string format: uuid description: >- Put the widget on this existing canvas instead of a new one. You must own the canvas. example: abc12345-def6-7890-ab12-cd3456ef7890 projectId: type: string format: uuid description: Project to file the widget in. You must be able to edit the project. example: 7c1e2f30-4a5b-4c6d-8e9f-0a1b2c3d4e5f organizationId: type: string format: uuid description: >- Organization the widget belongs to. You must be a member who may create widgets there. example: 5e2d3f4a-1b6c-4a1f-8b9c-3c2d4e5f6a7b workspaceType: type: string enum: - personal - organization description: >- Whether the widget lives in your personal workspace or in an organization's. example: personal managedUserId: type: string format: uuid description: >- 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: type: string maxLength: 255 description: >- 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. example: user-8841 example: 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 Widget: type: object description: Represents a widget in the system. properties: id: type: string format: uuid description: Unique identifier for the widget. example: 3fa85f64-5717-4562-b3fc-2c963f66afa6 creatorId: type: string format: uuid description: ID of the user who created the widget. example: a4d8b6e9-3c2d-4a1f-8b9c-5e2d3f4a1b6c name: type: string description: Name of the widget. example: Chart Widget description: type: string nullable: true description: Description of the widget's purpose and functionality. example: Interactive chart widget for data visualization type: type: string description: Type of widget (e.g., chart, form, gallery). example: chart content: type: object description: Content configuration for the widget. additionalProperties: true example: chartType: bar dataSource: api isPublic: type: boolean description: Whether the widget is publicly available. example: false isDraft: type: boolean description: Whether the widget is a draft. example: true shareId: type: string nullable: true description: Unique ID for sharing the widget publicly. example: shwgt_7f1d34acf2 createdAt: type: string format: date-time description: When the widget was created. example: '2025-09-15T10:23:00.000Z' updatedAt: type: string format: date-time description: When the widget was last updated. example: '2025-09-16T08:12:45.000Z' jsPath: type: string nullable: true description: Path to the JavaScript file for this widget. example: /widgets/chart/main.js canvasId: type: string format: uuid nullable: true description: ID of the canvas associated with this widget. example: 9f0c6b54-3e8f-4a2a-8b7d-1c5c6d9e0a1b repoId: type: string nullable: true description: Repository identifier for source code. example: user/chart-widget databaseId: type: string nullable: true description: >- Legacy. The name of a Neon database that an earlier version made for this widget. A widget has no database now (what the visitors of a composition leave is kept in the tables of that composition), so widgets made now have none. example: widget_3fa85f64_5717_4562_b3fc_2c963f66afa6 version: type: number format: float nullable: true description: Version number of the widget. example: 1 lastCommitSha: type: string nullable: true description: Latest Git commit SHA of the widget's code repository. example: a1b2c3d4e5f6g7h8i9j0 organizationId: type: string format: uuid nullable: true description: Organization ID if created in an organization workspace. example: 5e2d3f4a-1b6c-4a1f-8b9c-3c2d4e5f6a7b projectFolder: type: string nullable: true description: Project folder reference for organization widgets. example: marketing/q4-launch workspaceType: type: string enum: - personal - organization nullable: true description: Workspace type when created. example: personal managedUserId: type: string format: uuid nullable: true description: >- The managed user the widget was made for, or null when it is your own. List one managed user's widgets with the `managedUserId` or `managedUserExternalId` query parameter of `getWidgets`. example: b7c8d9e0-1f2a-4b3c-8d4e-5f6a7b8c9d0e 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 ResponseMeta: type: object description: >- 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. additionalProperties: true properties: page: type: integer description: The page that was read, counting from 1. example: 1 size: type: integer description: How many items one page holds. example: 20 total: type: integer description: How many items the whole list has. example: 135 limit: type: integer description: The same as `size`. example: 20 offset: type: integer description: How many items come before this page. example: 0 hasNextPage: type: boolean example: true hasPreviousPage: type: boolean example: false nextCursor: type: string nullable: true description: >- Pass this as `cursor` to read the next page of a list that is read by cursor. `null` on the last page. warnings: type: array items: type: string description: >- Things the call did not do, though it succeeded (for example a table that could not be created just now). ErrorResponse: type: object required: - success - message - error additionalProperties: true properties: success: type: boolean description: Always `false` on a failure. example: false message: type: string description: The same text as `error.message`, for a caller that reads one line. error: $ref: '#/components/schemas/ErrorDetail' ErrorDetail: type: object required: - code - message - timestamp properties: code: type: string description: Machine-readable error code. example: RESOURCE_NOT_FOUND message: type: string description: Human-readable explanation. example: Composition not found param: type: string description: The field that caused the error, when one did. example: name docUrl: type: string description: Where this error is explained. suggestedAction: type: string description: What to do about it. retryAfter: type: integer description: >- Seconds to wait before trying again (rate limits). The same number is in the `Retry-After` header. example: 60 details: type: object additionalProperties: true description: >- More about the error: the fields that failed, a limit that was reached. correlationId: type: string description: Quote this when you ask support about the call. example: req_123e4567-e89b-12d3-a456-426614174000 timestamp: type: string format: date-time example: '2026-10-15T10:00:00.000Z' securitySchemes: apiKeyAuth: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.