Get All Compositions

Retrieves all compositions with pagination support.

Pass managedUserId (Widgetic’s id for one of your managed users) or managedUserExternalId (your own identifier for the user) to list only the compositions made for that managed user. The compositions of your other managed users, and your own, are left out. It combines with the other filters and with paging. A managed user that is not yours, or does not exist, is answered with 404 and MANAGED_USER_NOT_FOUND.

An editor session with the creator surface may call this to list the compositions of ONE widget it built: it must send widgetId, and the answer holds only the compositions made for the session’s managed user.

GET /compositions

TypeScript SDK

TypeScript

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

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

const compositionsApi = new CompositionsApi(config);

try {
  const response = await compositionsApi.getAllCompositions({
    page: 1,
    size: 20,
    sort: 'createdAt:desc'
  });
  
  // The paging numbers are in meta
  console.log('Compositions:', response.data);
  console.log('Total:', response.meta?.total);
  console.log('Current page:', response.meta?.page);
} catch (error) {
  if (error.response?.status === 401) {
    console.error('Authentication required');
  } else {
    console.error('Failed to fetch compositions:', 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

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"

Query Parameters

page · integer · default: 1

Page number for pagination

Required range: x >= 1

size · integer · default: 20

Number of items per page

Required range: 1 <= x <= 100

sort · string

The order of the list, as <field>:<asc|desc>. The field is createdAt, updatedAt, name or status (the snake_case spelling, such as created_at, is read too). asc or desc alone orders by createdAt. Default: createdAt:desc. Any other field is a 400.

Example:

"createdAt:desc"

widgetId · string<uuid>

Filter compositions by widget ID

workspace · enum<string>

Filter by workspace

Available options: true, false

projectFolder · string<uuid>

Only the compositions in this project (the project's id).

status · enum<string>

Only the compositions in this status. Without it, every status is listed.

Available options: draft, published, archived

managedUserId · string<uuid>

List only the compositions made for this managed user (Widgetic's id for the user). Send this or managedUserExternalId, not both. Send it as managedUserId; the snake_case spelling managed_user_id is refused with a 400, not ignored.

managedUserExternalId · string

List only the compositions made for the managed user you registered with this externalId (your own identifier for the user). Send this or managedUserId, not both.

Maximum string length: 255

Response

200

application/json

List of compositions retrieved successfully

success · boolean · required

data · object[] · required

Show child attributes

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