tdx

SDK API Reference / SegmentSDK

Class: SegmentSDK ​

Segment operations API

Methods ​

createActivation() ​

createActivation(parentId, segmentId, request): Promise<ActivationResponse>

Create a new activation for a segment

Parameters ​

parentId ​

string

Parent segment ID

segmentId ​

string

Segment ID

request ​

CreateActivationRequest

Activation creation request

Returns ​

Promise<ActivationResponse>

Created activation details

Throws ​

When the creation fails

Example ​

typescript
// Create activation
const activation = await segment.createActivation('123', '456', {
  name: 'Send to Salesforce',
  connectionId: 789,
  allColumns: true,
  scheduleType: 'daily',
});

createFolder() ​

createFolder(parentIdOrName, request): Promise<CreateSegmentFolderResponse>

Create a new segment folder for organization

Parameters ​

parentIdOrName ​

string

Parent segment ID or name

request ​

CreateSegmentFolderRequest

Folder creation request

Returns ​

Promise<CreateSegmentFolderResponse>

Created folder details

Throws ​

When the creation fails

Example ​

typescript
// Create top-level folder
const folder = await segment.createFolder('123', {
  name: 'Q1 2024 Campaigns',
  description: 'Campaign segments for Q1'
});

// Create nested folder
const folder = await segment.createFolder('My Audience', {
  name: 'West Region',
  parentFolderId: '789'
});

createFolderForAudience() ​

createFolderForAudience(audience, request): Promise<CreateSegmentFolderResponse>

Create a segment folder under an audience of either kind.

CDPApiClient.createSegmentFolder takes one of two routes depending on whether the request carries a parentFolderId. With one it uses POST /entities/folders, whose controller resolves the parent folder's audience polymorphically (SegmentFolder#get_audience) and sets created_by_v5 — this is the route the console itself uses for composable folders, and the one CASApiClient.createFolder deliberately shares. Without one it falls back to POST /audiences/:id/folders, which is scoped to the audiences table: for a composable id that either 404s or lands the folder under an unrelated complete audience sharing the id.

So a composable folder create must carry a parent, and the audience's root folder is the parent for a top-level one. Refuse rather than take the fallback — a folder in the wrong table is what makes the journey write that follows it land on the complete controller.

Parameters ​

audience ​

ResolvedAudience

request ​

CreateSegmentFolderRequest

Returns ​

Promise<CreateSegmentFolderResponse>

Throws ​

JOURNEY_FOLDER_REQUIRED when a composable create has no parent folder

createJourneyLocalSegmentForAudience() ​

createJourneyLocalSegmentForAudience(audience, request): Promise<string>

Create a journey-local segment (one owned by a journey rather than authored by a user) on whichever route the audience kind requires.

  • complete: POST /entities/segments with type: segment-journey and journeyId
  • composable: POST /entities/composable_segments with kind: 'journey' and composableJourneyId

Parameters ​

audience ​

ResolvedAudience

request ​

CreateJourneySegmentRequest

Returns ​

Promise<string>

The new segment's id

createJourneySegment() ​

createJourneySegment(request): Promise<string>

Create a journey-local segment that is associated with a specific journey. This uses the /entities/segments endpoint to create a segment-journey type (kind=3).

The workflow for creating journeys with entry criteria:

  1. Create the journey WITHOUT entry criteria first
  2. Call this method to create the segment with the journey's ID
  3. Update the journey to add entry criteria referencing this segment

Parameters ​

request ​

CreateJourneySegmentRequest

Journey segment creation request including journeyId

Returns ​

Promise<string>

Created segment ID

Throws ​

When the creation fails

createParent() ​

createParent(request): Promise<CreateParentSegmentResponse>

Create a new parent segment (audience)

Parameters ​

request ​

CreateParentSegmentRequest

Parent segment creation request

Returns ​

Promise<CreateParentSegmentResponse>

Created parent segment details

Throws ​

When the creation fails

Example ​

typescript
// Create minimal parent segment
const parent = await segment.createParent({
  name: 'My Audience',
  master: {
    parentDatabaseName: 'mydb',
    parentTableName: 'customers'
  }
});

// Create with attributes and behaviors
const parent = await segment.createParent({
  name: 'Customer 360',
  description: 'Complete customer view',
  scheduleType: 'daily',
  scheduleOption: '03:00',
  master: {
    parentDatabaseName: 'customer_data',
    parentTableName: 'customers'
  },
  attributes: [
    {
      name: 'Lifetime Value',
      type: 'number',
      parentDatabaseName: 'customer_data',
      parentTableName: 'metrics',
      parentColumn: 'ltv',
      parentKey: 'customer_id',
      foreignKey: 'customer_id'
    }
  ]
});

createSegment() ​

createSegment(parentId, request): Promise<CreateSegmentResponse>

Create a new child segment with filtering rules

Parameters ​

parentId ​

string

Parent segment ID

request ​

CreateSegmentRequest

Segment creation request

Returns ​

Promise<CreateSegmentResponse>

Created segment details

Throws ​

When the creation fails

Example ​

typescript
// Create segment with simple rule
const segment = await segment.createSegment('123', {
  name: 'High Value Customers',
  description: 'Customers with LTV > 1000',
  rule: {
    type: 'And',
    conditions: [
      {
        type: 'Value',
        leftValue: { name: 'Lifetime Value' },
        operator: { type: 'Greater', rightValue: 1000 }
      }
    ]
  }
});

// Create segment in folder
const segment = await segment.createSegment('123', {
  name: 'US Customers',
  segmentFolderId: '789',
  rule: {
    type: 'And',
    conditions: [
      {
        type: 'Value',
        leftValue: { name: 'Country' },
        operator: { type: 'Equal', rightValue: 'US' }
      }
    ]
  }
});

deleteActivation() ​

deleteActivation(parentId, segmentId, activationId): Promise<void>

Delete an activation

Parameters ​

parentId ​

string

Parent segment ID

segmentId ​

string

Segment ID

activationId ​

string

Activation ID

Returns ​

Promise<void>

Throws ​

When the deletion fails

Example ​

typescript
// Delete activation
await segment.deleteActivation('123', '456', '789');

deleteSegment() ​

deleteSegment(segmentId): Promise<void>

Delete a child segment

Parameters ​

segmentId ​

string

Segment ID to delete

Returns ​

Promise<void>

Throws ​

When the deletion fails

Example ​

typescript
// Delete segment by ID
await segment.deleteSegment('456');

detectResourceType() ​

detectResourceType(parentId, name): Promise<"folder" | "segment" | "ambiguous">

Detect resource type by name (folder, segment, or ambiguous)

Parameters ​

parentId ​

string

Parent segment ID

name ​

string

Resource name to detect

Returns ​

Promise<"folder" | "segment" | "ambiguous">

'folder', 'segment', or 'ambiguous' if both exist

Example ​

typescript
const type = await segment.detectResourceType('123', 'Marketing');
if (type === 'ambiguous') {
  // Prompt user to choose
}

detectResourceTypeInFolder() ​

detectResourceTypeInFolder(parentId, name, folderId?): Promise<"folder" | "segment" | "ambiguous">

Detect resource type by name within a specific folder

Parameters ​

parentId ​

string

Parent segment ID

name ​

string

Resource name to detect

folderId? ​

string

Folder ID to search within (undefined = root level)

Returns ​

Promise<"folder" | "segment" | "ambiguous">

'folder', 'segment', or 'ambiguous' if both exist

getActivation() ​

getActivation(parentId, segmentId, activationId): Promise<ActivationResponse>

Get activation details

Parameters ​

parentId ​

string

Parent segment ID

segmentId ​

string

Segment ID

activationId ​

string

Activation ID

Returns ​

Promise<ActivationResponse>

Activation details

Throws ​

When the activation is not found

Example ​

typescript
// Get activation details
const activation = await segment.getActivation('123', '456', '789');
console.log(activation.name);

getBehaviorNames() ​

getBehaviorNames(parentId): Promise<string[]>

Get behavior names from a parent segment

Parameters ​

parentId ​

string

Parent segment ID

Returns ​

Promise<string[]>

Array of behavior names

getFolder() ​

getFolder(folderId): Promise<SegmentFolderDetails>

Get segment folder details by folder ID

Parameters ​

folderId ​

string

Folder ID

Returns ​

Promise<SegmentFolderDetails>

Folder details in JSON:API format

Throws ​

When the get operation fails

Example ​

typescript
// Get folder details
const folder = await segment.getFolder('456');
console.log(folder);

getOutputDatabaseName() ​

getOutputDatabaseName(parentId): string

Get the output database name for a parent segment

Parameters ​

parentId ​

string

Parent segment ID

Returns ​

string

Output database name (cdp_audience_{id})

getParent() ​

getParent(parentId): Promise<ParentSegment>

Get parent segment details

Parameters ​

parentId ​

string

Parent segment ID

Returns ​

Promise<ParentSegment>

Parent segment details

Throws ​

When the get operation fails

Example ​

typescript
// Get parent segment details
const parent = await segment.getParent('123');
console.log(parent);

getParentFull() ​

getParentFull(parentIdOrName): Promise<CreateParentSegmentResponse>

Get full parent segment details including attributes and behaviors

Parameters ​

parentIdOrName ​

string

Parent segment ID or name

Returns ​

Promise<CreateParentSegmentResponse>

Full parent segment details

Throws ​

When the get operation fails

Example ​

typescript
// Get full details by ID
const parent = await segment.getParentFull('123');

// Get full details by name
const parent = await segment.getParentFull('My Audience');
console.log(parent.attributes, parent.behaviors);

getParentSQL() ​

getParentSQL(parentId): Promise<string>

Get SQL query for parent segment

Parameters ​

parentId ​

string

Parent segment ID

Returns ​

Promise<string>

SQL query string

Throws ​

When the SQL retrieval fails

Example ​

typescript
// Get SQL for parent segment
const sql = await segment.getParentSQL('123');
console.log(sql);

getSegment() ​

getSegment(parentId, segmentId): Promise<SegmentResponse>

Get segment details

Parameters ​

parentId ​

string

Parent segment ID

segmentId ​

string

Segment ID

Returns ​

Promise<SegmentResponse>

Segment details

Throws ​

When the get operation fails

Example ​

typescript
// Get segment details
const segment = await segment.getSegment('123', '456');
console.log(segment);

getSegmentEntity() ​

getSegmentEntity(segmentId): Promise<SegmentResponse>

Get segment details via /entities/segments endpoint. Works for ALL segment types including journey-type (kind=3).

Parameters ​

segmentId ​

string

Returns ​

Promise<SegmentResponse>

getSegmentForAudience() ​

getSegmentForAudience(audience, audienceId, segmentId): Promise<{ isJourneyLocal: boolean; segment: SegmentResponse; }>

Fetch the segment a journey step references, from whichever route the audience kind requires, normalised to the complete-side SegmentResponse shape so everything downstream (rule → YAML conversion, naming, consolidation) is identical for both kinds.

The composable route is /entities/composable_segments/:id, which needs no audience id and — unlike cas.listSegments — does return journey-local segments. Journey-local is detected from the JSON:API resource type there, since composable segments carry no numeric kind.

kind is deliberately left unset for composable segments: batch/realtime/funnel_stage is a complete-side concept, and setting it would emit a kind: field the composable API cannot accept back on push.

Dormant while composable audiences are hidden from these commands (CAS-978) — see listFoldersForAudience.

Parameters ​

audience ​

ResolvedAudience

audienceId ​

string

segmentId ​

string

Returns ​

Promise<{ isJourneyLocal: boolean; segment: SegmentResponse; }>

getSegmentSQL() ​

getSegmentSQL(parentId, segmentId): Promise<string>

Get SQL query for a segment with filtering

Parameters ​

parentId ​

string

Parent segment ID

segmentId ​

string

Segment ID

Returns ​

Promise<string>

SQL query string

Throws ​

When the SQL retrieval fails

Example ​

typescript
// Get SQL for segment
const sql = await segment.getSegmentSQL('123', '456');
console.log(sql);

getSegmentSQLFromRule() ​

getSegmentSQLFromRule(parentId, rule): Promise<string>

Get SQL query from a rule directly, without fetching a segment first. Useful for local YAML files that haven't been pushed to the server yet.

Parameters ​

parentId ​

string

Parent segment ID

rule ​

SegmentRule

Segment rule in API format

Returns ​

Promise<string>

SQL query string

getSegmentSQLFromYaml() ​

getSegmentSQLFromYaml(yamlContent, parentSegmentName, segmentName): Promise<string>

Get SQL query from a local YAML file content. Parses the YAML, resolves segment references, converts to API format, and queries the API.

Parameters ​

yamlContent ​

string

Raw YAML string content

parentSegmentName ​

string

Parent segment name to resolve

segmentName ​

string

Segment name (used to exclude self-references during resolution)

Returns ​

Promise<string>

SQL query string

listActivations() ​

listActivations(parentId, segmentId): Promise<ActivationResponse[]>

List activations for a segment

Parameters ​

parentId ​

string

Parent segment ID

segmentId ​

string

Segment ID

Returns ​

Promise<ActivationResponse[]>

Array of activations

Throws ​

When the list operation fails

Example ​

typescript
// List activations for segment
const activations = await segment.listActivations('123', '456');
console.log(activations);

listAllAudienceEntities() ​

listAllAudienceEntities(): Promise<AudienceEntityListing>

List the audiences these commands address, as raw entities tagged with their kind.

Use this wherever a listing offers audiences to pick from: it keeps the listed set and the accepted set identical, so a name shown here is a name resolveAudienceContext takes. Complete audiences only — composable ones are listed by tdx cas list (CAS-978).

Returns ​

Promise<AudienceEntityListing>

listFields() ​

listFields(parentIdOrName): Promise<ParentSegmentField[]>

List available fields for a parent segment (for segmentation)

Extracts fields from parent segment's attributes and behaviors by calling GET /audiences/{id} and parsing the response.

Parameters ​

parentIdOrName ​

string

Parent segment ID or name

Returns ​

Promise<ParentSegmentField[]>

Array of available fields (attributes, behaviors)

Throws ​

When the list operation fails

Example ​

typescript
// List fields by ID
const fields = await segment.listFields('123');

// List fields by name
const fields = await segment.listFields('My Audience');
console.log(fields);

listFolders() ​

listFolders(parentId): Promise<SegmentFolder[]>

List segment folders under a parent segment

Parameters ​

parentId ​

string

Parent segment ID

Returns ​

Promise<SegmentFolder[]>

Array of segment folders

Throws ​

When the list operation fails

Example ​

typescript
// List segment folders
const folders = await segment.listFolders('123');
console.log(folders);

listFoldersForAudience() ​

listFoldersForAudience(audience): Promise<FolderLike[]>

List an audience's folders from whichever route its kind requires.

Composable folders live under /composable_audiences/:id/folders, not the v4 folder API this class's own listFolders calls — the two shapes are structurally compatible (see FolderLike), so callers that only need id/name/parentFolderId (folder-path building) can treat the result the same way regardless of kind.

The composable branch is dormant while composable audiences are hidden from these commands (CAS-978): kind is always complete at runtime today. Kept for the consolidation.

Parameters ​

audience ​

ResolvedAudience

Returns ​

Promise<FolderLike[]>

listOutputTables() ​

listOutputTables(parentId): Promise<object[]>

List all tables in the parent segment output database

Parameters ​

parentId ​

string

Parent segment ID

Returns ​

Promise<object[]>

Array of table names with their types (customers or behavior)

listParents() ​

listParents(): Promise<ParentSegment[]>

List all parent segments (audiences)

Returns ​

Promise<ParentSegment[]>

Array of parent segments

Throws ​

When the list operation fails

Example ​

typescript
// List all parent segments
const segments = await segment.listParents();
console.log(segments);

listRecursive() ​

listRecursive(parentId, folderId?, _depth?, maxDepth?): Promise<SegmentTreeNode[]>

Build a tree structure recursively from a parent or folder

Uses the /entities/by-folder API for efficient single-call retrieval of all entities (folders, segments, journeys) under a folder.

Parameters ​

parentId ​

string

Parent segment ID

folderId? ​

string

Optional folder ID to start from

_depth? ​

number

maxDepth? ​

number = 10

Maximum depth to traverse (default: 10, max: 32)

Returns ​

Promise<SegmentTreeNode[]>

Tree nodes with nested children (folders, segments, and journeys)

Deprecated ​

No longer used. Tree is built from single API response.

Example ​

typescript
// Build full tree recursively
const tree = await segment.listRecursive('123');
console.log(tree);

listSegments() ​

listSegments(parentId): Promise<SegmentResponse[]>

List segments under a parent segment

Parameters ​

parentId ​

string

Parent segment ID

Returns ​

Promise<SegmentResponse[]>

Array of child segments

Throws ​

When the list operation fails

Example ​

typescript
// List segments under parent
const segments = await segment.listSegments('123');
console.log(segments);

listSegmentsForAudience() ​

listSegmentsForAudience(audience): Promise<SegmentResponse[]>

List an audience's segments from whichever route its kind requires, normalised to SegmentResponse (see composableSegmentToSegmentResponse).

Note the composable route excludes journey-local segments — cas.listSegments crawls the folder tree and keeps only composable-segment resources, and a journey's own step segments are not in any folder listing. Callers that need those must go through getSegmentForAudience by id, which is what journey push's deterministic-name and rule-content matching does.

Parameters ​

audience ​

ResolvedAudience

Returns ​

Promise<SegmentResponse[]>

listUnifiedWithJourneys() ​

listUnifiedWithJourneys(parentId, folderId?): Promise<{ folders: SegmentFolder[]; journeys: JourneyListItem[]; segments: SegmentResponse[]; }>

List folders, segments, and journeys under a parent or within a folder (unified view)

Uses the /entities/by-folder API for efficient single-call retrieval.

Parameters ​

parentId ​

string

Parent segment ID

folderId? ​

string

Optional folder ID to list contents of a specific folder

Returns ​

Promise<{ folders: SegmentFolder[]; journeys: JourneyListItem[]; segments: SegmentResponse[]; }>

Object with folders, segments, and journeys arrays

Example ​

typescript
const { folders, segments, journeys } = await segment.listUnifiedWithJourneys('123');
console.log(`Found ${folders.length} folders, ${segments.length} segments, ${journeys.length} journeys`);

moveSegment() ​

moveSegment(segmentId, folderId): Promise<MoveSegmentResponse>

Move one segment to a different folder, safely. Convenience wrapper around moveSegments for the single-segment case.

Parameters ​

segmentId ​

string

Segment ID to move

folderId ​

string

Target folder ID

Returns ​

Promise<MoveSegmentResponse>

moveSegments() ​

moveSegments(segmentIds, folderId, dryRun?): Promise<MoveSegmentResponse[]>

Move one or more segments to a different folder, safely.

Uses the v5 PATCH path, which sends only the target folder relationship and never the rule — so the move cannot wipe segment rules (the CS-13647 failure mode). Batch segments only; the API rejects others.

Batch semantics (mirrors Claude Code's MultiEdit): every segment is read in a pre-flight pass BEFORE any write — if any segment is missing, nothing is moved. Then each is moved and its rule re-read and verified; on any rule drift the run stops and reports how many had already completed.

Parameters ​

segmentIds ​

string[]

Segment IDs to move (at least one)

folderId ​

string

Target folder ID

dryRun? ​

boolean = false

If true, run the pre-flight checks and report what would move, but issue no writes (honors the global --dry-run flag)

Returns ​

Promise<MoveSegmentResponse[]>

One result per segment, in order

previewParentYaml() ​

previewParentYaml(yamlContent, options?): Promise<PreviewResult>

Preview parent segment YAML sample data

Fetches sample data from tables - no validation, just raw data. Requires one of: master, attribute, behavior, or enriched option.

Parameters ​

yamlContent ​

string | ParentSegmentDef

YAML configuration string or parsed object

options? ​

PreviewOptions = {}

Preview options (one required: master, attribute, behavior, enriched)

Returns ​

Promise<PreviewResult>

Preview result with sample data

pullParentYaml() ​

pullParentYaml(parentIdOrName): Promise<string>

Pull parent segment configuration as YAML string

Parameters ​

parentIdOrName ​

string

Parent segment ID or name

Returns ​

Promise<string>

YAML configuration string

Throws ​

When the parent segment is not found

Example ​

typescript
const yaml = await segment.pullParentYaml('Customer 360');
console.log(yaml);

pullSegments() ​

pullSegments(parentIdOrName, options?): Promise<PullSegmentsResult>

Pull child segments and journeys from Treasure AI to YAML format.

This method fetches all child segments and journeys for a parent segment, converts them to YAML format, and calculates diffs against existing files.

The caller is responsible for:

  • Confirming with the user
  • Writing files to disk using the returned file data

Parameters ​

parentIdOrName ​

string

Parent segment ID or name

options? ​

PullSegmentsOptions = {}

Pull options (targetDir, verbose, onProgress)

Returns ​

Promise<PullSegmentsResult>

Pull result with files and statistics

Example ​

typescript
// Pull all segments/journeys for a parent
const result = await segment.pullSegments('My Audience', {
  targetDir: 'segments/my-audience',
  onProgress: (phase) => console.log(phase)
});

// Check results
console.log(`${result.counts.segments} segments, ${result.counts.journeys} journeys`);
console.log(`${result.newFiles} new, ${result.changedFiles} changed`);

// Write files (caller responsibility)
for (const file of result.files) {
  if (file.isNew || file.hasChanges) {
    fs.mkdirSync(path.dirname(file.absolutePath), { recursive: true });
    fs.writeFileSync(file.absolutePath, file.content);
  }
}

pushParentYaml() ​

pushParentYaml(yamlContent): Promise<PushParentYamlResult & object>

Push parent segment configuration from YAML

This method compares the YAML configuration with the existing parent segment (if any) and returns diff information. It does NOT apply the changes automatically. Use the apply method on the result or call createParent/updateParent to apply.

Parameters ​

yamlContent ​

string | ParentSegmentDef

YAML configuration string or parsed object

Returns ​

Promise<PushParentYamlResult & object>

Push result with diff information and apply method

Throws ​

When YAML parsing fails or validation errors occur

Example ​

typescript
// Preview changes
const result = await segment.pushParentYaml(yamlContent);
if (result.hasChanges) {
  console.log(result.diffFormatted);
  // Apply changes
  await result.apply();
}

resolveAudienceContext() ​

resolveAudienceContext(nameOrId): Promise<ResolvedAudience>

Resolve an audience name or id to its id and its kind, for complete audiences.

Prefer this over resolveParentId anywhere the result then reaches a kind-specific route: it verifies a numeric id instead of trusting it, and it carries the root folder id, so the caller skips a GET /audiences/:id that 404s for anything it does not own.

Composable audiences are deliberately not resolvable here — naming one fails with a message pointing at tdx cas (CAS-978). See sdk/segment/audience-context.ts for the full contract.

Parameters ​

nameOrId ​

string

Audience name (exact, case-sensitive) or numeric id

Returns ​

Promise<ResolvedAudience>

The audience with its kind and root folder id

Throws ​

When not found, when the input names a composable audience, or when a name matches more than one audience

resolveEntitiesInParent() ​

resolveEntitiesInParent(parentIdOrName, items): Promise<ResolvedEntity[]>

Resolve several parent-relative names/paths under one parent to v5 ids, fetching the parent and the v5 tree once (avoids an N+1 round-trip when a command resolves multiple names — e.g. several segments plus a target folder).

Parameters ​

parentIdOrName ​

string

Parent segment (audience) id or name

items ​

object[]

Parent-relative names with an optional expected type each

Returns ​

Promise<ResolvedEntity[]>

Resolved entities, in the same order as items

Throws ​

When any name is invalid, not found, or ambiguous

resolveEntity() ​

resolveEntity(parentIdOrName, name, expectType?): Promise<ResolvedEntity>

Resolve a parent-relative name/path to a concrete v5 entity id.

This is the v5 counterpart to resolvePathToResource. It walks the v5 entity tree (/entities/by-folder via listRecursive) instead of the v4 folder API, so the id it returns is the one the v5 PATCH endpoints (e.g. sg move) actually require. v4 and v5 use different id-spaces for the same entity — do not feed a v4 id to a v5 endpoint.

name is relative to parentIdOrName (e.g. "VIPs" or "Marketing/VIPs"), mirroring the sg show/sg desc contract (always parent-relative). Matching is case-insensitive (an exact-case match wins a true case collision). A name that matches more than one entity at its level is an error that lists the candidates with their ids — never a silent pick.

To resolve several names under the same parent, prefer resolveEntitiesInParent — it fetches the tree once.

Parameters ​

parentIdOrName ​

string

Parent segment (audience) id or name

name ​

string

Parent-relative name or path (e.g. "VIPs", "Marketing/VIPs")

expectType? ​

"folder" | "segment"

Constrain the target to a folder or a segment; omit for either

Returns ​

Promise<ResolvedEntity>

The resolved entity with its v5 id

Throws ​

When the name is invalid, not found, or ambiguous

resolveFolderId() ​

resolveFolderId(parentId, name): Promise<string>

Resolve folder name to ID within a parent

Parameters ​

parentId ​

string

Parent segment ID

name ​

string

Folder name (case-sensitive)

Returns ​

Promise<string>

Folder ID

Throws ​

When the folder is not found

Example ​

typescript
// Resolve folder name to ID
const folderId = await segment.resolveFolderId('123', 'Marketing');
console.log(folderId); // '789'

resolveParentId() ​

resolveParentId(name): Promise<string>

Resolve parent segment name to ID

Parameters ​

name ​

string

Parent segment name (case-sensitive)

Returns ​

Promise<string>

Parent segment ID

Throws ​

When the parent segment is not found

Example ​

typescript
// Resolve parent name to ID
const parentId = await segment.resolveParentId('My Audience');
console.log(parentId); // '123'

resolvePathToResource() ​

resolvePathToResource(path): Promise<ResolvedSegmentPath>

Resolve a path string to a resource

Parameters ​

path ​

string

Path string (e.g., "My Audience/Marketing/High Value")

Returns ​

Promise<ResolvedSegmentPath>

Resolved path with IDs and type

Throws ​

When path is invalid or resource not found

Example ​

typescript
// Resolve path to segment or folder
const resolved = await segment.resolvePathToResource('My Audience/Marketing');
console.log(resolved.type); // 'folder'
console.log(resolved.folderId); // '456'

resolveSegmentId() ​

resolveSegmentId(parentId, name): Promise<string>

Resolve child segment name to ID within a parent

Parameters ​

parentId ​

string

Parent segment ID

name ​

string

Child segment name (case-sensitive)

Returns ​

Promise<string>

Child segment ID

Throws ​

When the child segment is not found

Example ​

typescript
// Resolve child segment name to ID
const segmentId = await segment.resolveSegmentId('123', 'High Value Users');
console.log(segmentId); // '456'

runParent() ​

runParent(parentIdOrName): Promise<AudienceExecution>

Run workflow to (re)generate a parent segment

Parameters ​

parentIdOrName ​

string

Parent segment ID or name

Returns ​

Promise<AudienceExecution>

Workflow execution details

Throws ​

When the parent segment is not found or run fails

Example ​

typescript
// Run parent segment workflow by name
const execution = await segment.runParent('My Audience');
console.log(`Workflow started: ${execution.workflowSessionId}`);

traversePath() ​

traversePath(pathSegments): Promise<ResolvedSegmentPath>

Traverse a multi-level path and resolve to final resource

Parameters ​

pathSegments ​

string[]

Array of path components (e.g., ['My Audience', 'Marketing', 'Campaigns'])

Returns ​

Promise<ResolvedSegmentPath>

Resolved path with IDs and type

Example ​

typescript
const resolved = await segment.traversePath(['My Audience', 'Marketing', 'High Value']);
console.log(resolved.type); // 'folder' or 'segment'

updateActivation() ​

updateActivation(parentId, segmentId, activationId, request): Promise<ActivationResponse>

Update an existing activation

Parameters ​

parentId ​

string

Parent segment ID

segmentId ​

string

Segment ID

activationId ​

string

Activation ID

request ​

UpdateActivationRequest

Activation update request

Returns ​

Promise<ActivationResponse>

Updated activation details

Throws ​

When the update fails

Example ​

typescript
// Update activation
const activation = await segment.updateActivation('123', '456', '789', {
  name: 'Updated Name',
  scheduleType: 'hourly',
});

updateJourneyLocalSegmentForAudience() ​

updateJourneyLocalSegmentForAudience(audience, segmentId, request): Promise<void>

Update a journey-local segment on whichever route the audience kind requires.

The composable route takes no audience id, and refuses the update with a 400 when the owning journey is launched ("Segments associated with the launched journey cannot be modified") — that message is mapped for the user by journey push's error handling.

Parameters ​

audience ​

ResolvedAudience

segmentId ​

string

request ​

UpdateSegmentRequest

Returns ​

Promise<void>

updateParent() ​

updateParent(parentIdOrName, request): Promise<CreateParentSegmentResponse>

Update an existing parent segment (audience)

Parameters ​

parentIdOrName ​

string

Parent segment ID or name

request ​

CreateParentSegmentRequest

Parent segment update request

Returns ​

Promise<CreateParentSegmentResponse>

Updated parent segment details

Throws ​

When the update fails

Example ​

typescript
// Update by ID
const updated = await segment.updateParent('123', {
  description: 'Updated description',
  attributes: [...] // Add new attributes
});

// Update by name
const updated = await segment.updateParent('My Audience', {
  scheduleType: 'weekly',
  scheduleOption: '0' // Sunday
});

updateSegmentById() ​

updateSegmentById(parentId, segmentId, request): Promise<UpdateSegmentResponse>

Update an existing child segment

Parameters ​

parentId ​

string

Parent segment ID

segmentId ​

string

Child segment ID

request ​

UpdateSegmentRequest

Segment update request

Returns ​

Promise<UpdateSegmentResponse>

Updated segment details

Throws ​

When the update fails

Example ​

typescript
// Update segment name and description
const updated = await segment.updateSegmentById('123', '456', {
  name: 'Super High Value',
  description: 'LTV > 5000'
});

// Update segment rule
const updated = await segment.updateSegmentById('123', '456', {
  rule: {
    type: 'And',
    conditions: [
      {
        type: 'Value',
        leftValue: { name: 'Lifetime Value' },
        operator: { type: 'Greater', rightValue: 5000 }
      }
    ]
  }
});

validateParentYaml() ​

validateParentYaml(yamlContent, options?): Promise<PreviewResult>

Validate parent segment YAML configuration

Validates schema and gathers statistics for a parent segment YAML before pushing. Does NOT fetch sample data - use previewParentYaml for that.

Parameters ​

yamlContent ​

string | ParentSegmentDef

YAML configuration string or parsed object

options? ​

ValidateOptions = {}

Validate options for filtering what to validate

Returns ​

Promise<PreviewResult>

Preview result with validation and statistics

Copyright 2024-present Treasure AI