Get Embed Schema

Retrieves the definition of the composition’s Embed tab: which settings exist, what each one holds, what it defaults to, and when its control is shown. It is the third tab beside schema/content and schema/design, in the same format (componentGroups → components → propertyGroups → properties, each property with a type, a defaultValue and an inputController), so a client that draws those two tabs draws this one with the same code.

The schema is the same for every composition (it is the one Widgetic’s own Embed Editor draws). The composition id decides who may ask: the caller must be able to read the composition.

Reading and saving the values:

• GET /compositions/{id}/embed-settings returns what the composition saved. A composition whose Embed tab was never saved has nothing to return; seed the form from defaults, which holds the defaultValue of every setting that declares one.
• PUT /compositions/{id} with embedSettings saves them. The gateway stores embedSettings as given and does not check it against this schema; the schema is how a client knows what to put there.

A property’s visibilityCondition says when its control is shown: condition is a comparison of the current values of the properties named in dependsOn (useIframe === false, embedTarget === 'mixed' && keepDimensions === false). While it is false the Embed Editor does not show the control.

A colour picker with showOpacityControls saves its opacity next to the colour, under the key <name>_opacity as a number from 0 to 1 (overlayBackgroundColor → overlayBackgroundColor_opacity). Its defaultTransparency is a percentage and the saved value a fraction (50 → 0.5).

GET /compositions/{id}/schema/embed

Get Embed Schema

cURL

curl --request GET \
  --url https://api.widgetic.com/v1/compositions/{id}/schema/embed \
  --header 'Authorization: Bearer <token>'

200

{
  "success": true,
  "data": {
    "id": "<string>",
    "name": "<string>",
    "version": "<string>",
    "type": "embed",
    "componentGroups": [
      {}
    ],
    "defaults": {}
  },
  "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"

Path Parameters

id · string<uuid> · required

ID of the composition

Response

200

application/json

Embed schema retrieved successfully

success · boolean · required

Always true on a success.

Example:

true

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