> ## Documentation Index > Fetch the complete documentation index at: https://widgetic.com/llms.txt > Use this file to discover all available pages before exploring further. # List Widgets > Lists the widgets your account owns, newest first. A widget is the reusable piece a composition is made from; this is your own library, not a catalogue of Widgetic's widgets. Pass `page` (counting from 1) and `size` (1 to 100, 20 when left out) to read the list one page at a time. `meta` then carries `total`, `hasNextPage` and `hasPreviousPage`, so a client can walk the list to its end. A page past the end is an empty list. Without `page` and `size` the call returns the whole list in one response, which only suits an account with a few widgets. Pass `canvasId` to list only the widgets on one of your canvases. That list is always returned whole, whatever `page` and `size` say. Pass `managedUserId` (Widgetic's id for one of your managed users) or `managedUserExternalId` (your own identifier for the user) to list only the widgets made for that managed user. The widgets of your other managed users, and your own, are left out. It combines with `page`, `size` and `canvasId`. A managed user that is not yours, or does not exist, is answered with 404 and `MANAGED_USER_NOT_FOUND`. ## OpenAPI ````yaml /openapi/widgetic-api-public.json get /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: get: tags: - Widgets summary: List Widgets description: > Lists the widgets your account owns, newest first. A widget is the reusable piece a composition is made from; this is your own library, not a catalogue of Widgetic's widgets. Pass `page` (counting from 1) and `size` (1 to 100, 20 when left out) to read the list one page at a time. `meta` then carries `total`, `hasNextPage` and `hasPreviousPage`, so a client can walk the list to its end. A page past the end is an empty list. Without `page` and `size` the call returns the whole list in one response, which only suits an account with a few widgets. Pass `canvasId` to list only the widgets on one of your canvases. That list is always returned whole, whatever `page` and `size` say. Pass `managedUserId` (Widgetic's id for one of your managed users) or `managedUserExternalId` (your own identifier for the user) to list only the widgets made for that managed user. The widgets of your other managed users, and your own, are left out. It combines with `page`, `size` and `canvasId`. A managed user that is not yours, or does not exist, is answered with 404 and `MANAGED_USER_NOT_FOUND`. operationId: getWidgets parameters: - in: query name: page schema: type: integer minimum: 1 description: >- Page to return, counting from 1. Giving `page` or `size` turns paging on. - in: query name: size schema: type: integer minimum: 1 maximum: 100 description: >- How many widgets a page holds (20 when `page` is given without it). Giving `page` or `size` turns paging on. - in: query name: canvasId schema: type: string format: uuid description: List only the widgets on this canvas. The list is returned whole. - in: query name: managedUserId schema: type: string format: uuid description: >- List only the widgets made for this managed user (Widgetic's id for the user). Send this or `managedUserExternalId`, not both. - in: query name: managedUserExternalId schema: type: string maxLength: 255 description: >- List only the widgets made for the managed user you registered with this `externalId` (your own identifier for the user). Send this or `managedUserId`, not both. responses: '200': description: List of widgets content: application/json: schema: type: object properties: success: type: boolean data: type: array items: $ref: '#/components/schemas/Widget' meta: $ref: '#/components/schemas/ResponseMeta' required: - success - data '400': description: >- A parameter is not valid (for example `size` above 100, a `canvasId` or `managedUserId` that is not a UUID, or both `managedUserId` and `managedUserExternalId`). 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. 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' '429': description: Too many requests. See the Retry-After header. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - apiKeyAuth: [] components: schemas: 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.