Duplicate Composition

Creates a duplicate of an existing composition for the authenticated user.

The duplicate is made after the answer: the call returns 202 with an operationId. Ask GET /operations/{id} for that operation until its status is completed; the new composition is named in metadata.newCompositionId. A problem with the duplicate’s database (for example, tables that could not be made just now) is listed in metadata.warnings, which is absent when there is none.

The Idempotency-Key header is required (400 without it). Send the same key when you retry, so one duplicate is made, not two.

POST /compositions/{id}/duplicate

TypeScript SDK

TypeScript

import { randomUUID } from 'node:crypto';
import { Configuration, CompositionsApi, OperationsApi } from '@widgetic/api-sdk-ts';

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

const compositionsApi = new CompositionsApi(config);
const operationsApi = new OperationsApi(config);

try {
  const started = await compositionsApi.duplicateComposition({
    id: 'composition_123',
    // The call needs an idempotency key: reuse the same key if you retry this call.
    idempotencyKey: randomUUID(),
    duplicateCompositionRequest: {
      name: 'My Duplicated Composition',
      includeDatabase: false
    }
  });
  
  // The duplicate is made after the answer: ask for the operation until it has finished
  const operationId = started.data?.operationId;
  if (!operationId) throw new Error('The answer has no operationId');
  
  const finalStatuses = ['completed', 'failed', 'cancelled'];
  let operation = await operationsApi.getOperation({ id: operationId });
  while (!finalStatuses.includes(operation.data.status ?? '')) {
    await new Promise((resolve) => setTimeout(resolve, 1000));
    operation = await operationsApi.getOperation({ id: operationId });
  }
  
  if (operation.data.status !== 'completed') {
    console.error('Duplication did not finish:', operation.data.status, operation.data.error);
  } else {
    console.log('Duplicated composition:', operation.data.metadata?.newCompositionId);
    if (operation.data.metadata?.warnings?.length) {
      console.warn('Warnings:', operation.data.metadata.warnings);
    }
  }
} catch (error) {
  if (error.response?.status === 404) {
    console.error('Source composition not found');
  } else {
    console.error('Failed to duplicate composition:', error);
  }
}

202

{
  "success": true,
  "data": {
    "operationId": "123e4567-e89b-12d3-a456-426614174000"
  },
  "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

Idempotency-Key · string · required

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 - 50

Pattern: ^[a-zA-Z0-9_-]{8,50}$

Example:

"9b2d6f0a-3c41-4e5a-8d77-1f2e3a4b5c6d"

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 to duplicate

Body

application/json

name · string

Optional new name for the duplicate (defaults to "Copy of [original name]")

Example:

"My Duplicated Composition"

includeDatabase · boolean · default: false

Whether the duplicate gets the tables the original declares (databaseSchema), empty and in a schema of their own (default false). What visitors left in the original is never copied, and the duplicate never shares the original's data.

Response

202

application/json

Composition duplication initiated successfully

success · boolean · required

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