TypeScript SDK
import { randomUUID } from 'node:crypto';
import { Configuration, ManagedUsersApi } from '@widgetic/api-sdk-ts';
const api = new ManagedUsersApi(new Configuration({ apiKey: 'YOUR_API_KEY' }));
const { data: composition } = await api.createCompositionFromPreset({
id: managedUserId,
key: 'rating',
// Reuse the same key if you retry this call.
idempotencyKey: randomUUID(),
// The request body is camelCase, like every answer of the API.
createCompositionFromPresetRequest: { name: 'Customer rating page', embedSettings: { width: 640, height: 480 }, locale: 'fr-FR' },
});curl --request POST \
--url https://api.widgetic.com/v1/managed-users/{id}/presets/{key}/composition \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"name": "Customer rating page",
"embedSettings": {
"width": 640,
"height": 480
},
"locale": "fr-FR"
}
'import requests
url = "https://api.widgetic.com/v1/managed-users/{id}/presets/{key}/composition"
payload = {
"name": "Customer rating page",
"embedSettings": {
"width": 640,
"height": 480
},
"locale": "fr-FR"
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: 'Customer rating page',
embedSettings: {width: 640, height: 480},
locale: 'fr-FR'
})
};
fetch('https://api.widgetic.com/v1/managed-users/{id}/presets/{key}/composition', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.widgetic.com/v1/managed-users/{id}/presets/{key}/composition",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => 'Customer rating page',
'embedSettings' => [
'width' => 640,
'height' => 480
],
'locale' => 'fr-FR'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.widgetic.com/v1/managed-users/{id}/presets/{key}/composition"
payload := strings.NewReader("{\n \"name\": \"Customer rating page\",\n \"embedSettings\": {\n \"width\": 640,\n \"height\": 480\n },\n \"locale\": \"fr-FR\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.widgetic.com/v1/managed-users/{id}/presets/{key}/composition")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"Customer rating page\",\n \"embedSettings\": {\n \"width\": 640,\n \"height\": 480\n },\n \"locale\": \"fr-FR\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.widgetic.com/v1/managed-users/{id}/presets/{key}/composition")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"Customer rating page\",\n \"embedSettings\": {\n \"width\": 640,\n \"height\": 480\n },\n \"locale\": \"fr-FR\"\n}"
response = http.request(request)
puts response.read_body{
"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>"
]
}
}{
"success": false,
"message": "<string>",
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "Composition not found",
"timestamp": "2026-10-15T10:00:00.000Z",
"param": "name",
"docUrl": "<string>",
"suggestedAction": "<string>",
"retryAfter": 60,
"details": {},
"correlationId": "req_123e4567-e89b-12d3-a456-426614174000"
}
}{
"success": false,
"message": "<string>",
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "Composition not found",
"timestamp": "2026-10-15T10:00:00.000Z",
"param": "name",
"docUrl": "<string>",
"suggestedAction": "<string>",
"retryAfter": 60,
"details": {},
"correlationId": "req_123e4567-e89b-12d3-a456-426614174000"
}
}{
"success": false,
"message": "<string>",
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "Composition not found",
"timestamp": "2026-10-15T10:00:00.000Z",
"param": "name",
"docUrl": "<string>",
"suggestedAction": "<string>",
"retryAfter": 60,
"details": {},
"correlationId": "req_123e4567-e89b-12d3-a456-426614174000"
}
}{
"success": false,
"message": "<string>",
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "Composition not found",
"timestamp": "2026-10-15T10:00:00.000Z",
"param": "name",
"docUrl": "<string>",
"suggestedAction": "<string>",
"retryAfter": 60,
"details": {},
"correlationId": "req_123e4567-e89b-12d3-a456-426614174000"
}
}{
"success": false,
"message": "<string>",
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "Composition not found",
"timestamp": "2026-10-15T10:00:00.000Z",
"param": "name",
"docUrl": "<string>",
"suggestedAction": "<string>",
"retryAfter": 60,
"details": {},
"correlationId": "req_123e4567-e89b-12d3-a456-426614174000"
}
}{
"success": false,
"message": "<string>",
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "Composition not found",
"timestamp": "2026-10-15T10:00:00.000Z",
"param": "name",
"docUrl": "<string>",
"suggestedAction": "<string>",
"retryAfter": 60,
"details": {},
"correlationId": "req_123e4567-e89b-12d3-a456-426614174000"
}
}Managed Users
Create a composition from one of your presets in one call
Validates the name, optional content, design, embed settings and locale, then creates a draft composition filed under the managed user, built on the preset’s widget, in a single insert. A failure never leaves a half-made composition.
The preset’s widget must be published. The managed user must be yours and active.
A widget that keeps what visitors send (a form, a vote, a rating) declares its tables in its own source
(src/lib/meta/database.json); they are made for the composition here, in a schema of its own, as the widget
was when it was last published. A widget that keeps nothing leaves the composition without tables. If the
tables cannot be made just now, or the widget’s file cannot be used, the composition is still created (201)
and meta.warnings says why; the tables are made the next time the widget is generated.
The Idempotency-Key header is required (400 without it). Send the same key when you retry, so one
composition is created, not two.
POST
/
managed-users
/
{id}
/
presets
/
{key}
/
composition
TypeScript SDK
import { randomUUID } from 'node:crypto';
import { Configuration, ManagedUsersApi } from '@widgetic/api-sdk-ts';
const api = new ManagedUsersApi(new Configuration({ apiKey: 'YOUR_API_KEY' }));
const { data: composition } = await api.createCompositionFromPreset({
id: managedUserId,
key: 'rating',
// Reuse the same key if you retry this call.
idempotencyKey: randomUUID(),
// The request body is camelCase, like every answer of the API.
createCompositionFromPresetRequest: { name: 'Customer rating page', embedSettings: { width: 640, height: 480 }, locale: 'fr-FR' },
});curl --request POST \
--url https://api.widgetic.com/v1/managed-users/{id}/presets/{key}/composition \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"name": "Customer rating page",
"embedSettings": {
"width": 640,
"height": 480
},
"locale": "fr-FR"
}
'import requests
url = "https://api.widgetic.com/v1/managed-users/{id}/presets/{key}/composition"
payload = {
"name": "Customer rating page",
"embedSettings": {
"width": 640,
"height": 480
},
"locale": "fr-FR"
}
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: 'Bearer <token>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
name: 'Customer rating page',
embedSettings: {width: 640, height: 480},
locale: 'fr-FR'
})
};
fetch('https://api.widgetic.com/v1/managed-users/{id}/presets/{key}/composition', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.widgetic.com/v1/managed-users/{id}/presets/{key}/composition",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'name' => 'Customer rating page',
'embedSettings' => [
'width' => 640,
'height' => 480
],
'locale' => 'fr-FR'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.widgetic.com/v1/managed-users/{id}/presets/{key}/composition"
payload := strings.NewReader("{\n \"name\": \"Customer rating page\",\n \"embedSettings\": {\n \"width\": 640,\n \"height\": 480\n },\n \"locale\": \"fr-FR\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.widgetic.com/v1/managed-users/{id}/presets/{key}/composition")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"Customer rating page\",\n \"embedSettings\": {\n \"width\": 640,\n \"height\": 480\n },\n \"locale\": \"fr-FR\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.widgetic.com/v1/managed-users/{id}/presets/{key}/composition")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"name\": \"Customer rating page\",\n \"embedSettings\": {\n \"width\": 640,\n \"height\": 480\n },\n \"locale\": \"fr-FR\"\n}"
response = http.request(request)
puts response.read_body{
"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>"
]
}
}{
"success": false,
"message": "<string>",
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "Composition not found",
"timestamp": "2026-10-15T10:00:00.000Z",
"param": "name",
"docUrl": "<string>",
"suggestedAction": "<string>",
"retryAfter": 60,
"details": {},
"correlationId": "req_123e4567-e89b-12d3-a456-426614174000"
}
}{
"success": false,
"message": "<string>",
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "Composition not found",
"timestamp": "2026-10-15T10:00:00.000Z",
"param": "name",
"docUrl": "<string>",
"suggestedAction": "<string>",
"retryAfter": 60,
"details": {},
"correlationId": "req_123e4567-e89b-12d3-a456-426614174000"
}
}{
"success": false,
"message": "<string>",
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "Composition not found",
"timestamp": "2026-10-15T10:00:00.000Z",
"param": "name",
"docUrl": "<string>",
"suggestedAction": "<string>",
"retryAfter": 60,
"details": {},
"correlationId": "req_123e4567-e89b-12d3-a456-426614174000"
}
}{
"success": false,
"message": "<string>",
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "Composition not found",
"timestamp": "2026-10-15T10:00:00.000Z",
"param": "name",
"docUrl": "<string>",
"suggestedAction": "<string>",
"retryAfter": 60,
"details": {},
"correlationId": "req_123e4567-e89b-12d3-a456-426614174000"
}
}{
"success": false,
"message": "<string>",
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "Composition not found",
"timestamp": "2026-10-15T10:00:00.000Z",
"param": "name",
"docUrl": "<string>",
"suggestedAction": "<string>",
"retryAfter": 60,
"details": {},
"correlationId": "req_123e4567-e89b-12d3-a456-426614174000"
}
}{
"success": false,
"message": "<string>",
"error": {
"code": "RESOURCE_NOT_FOUND",
"message": "Composition not found",
"timestamp": "2026-10-15T10:00:00.000Z",
"param": "name",
"docUrl": "<string>",
"suggestedAction": "<string>",
"retryAfter": 60,
"details": {},
"correlationId": "req_123e4567-e89b-12d3-a456-426614174000"
}
}Authorizations
Bearer authentication header of the form Bearer <token>, where <token> is your auth token.
Headers
Required: a call without it is refused with 400. A key of your own that names this one request; a UUID is ideal. It is 8 to 50 characters of letters, digits, - and _. Send the same key again when you retry (after a timeout, a dropped connection or a 5xx) and the call is carried out once: the retry gets the first answer back, marked X-Idempotency-Cached: true. The same key with a different body is refused with 422, and a retry that arrives while the first call is still running with 409 (see Retry-After).
Required string length:
8 - 50Pattern:
^[a-zA-Z0-9_-]{8,50}$Example:
"9b2d6f0a-3c41-4e5a-8d77-1f2e3a4b5c6d"
Body
application/json
Response
Composition created
Always true on a success.
Example:
true
Show child attributes
Show child attributes
Example:
{
"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"
}
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
Show child attributes