Core API

The core @lytics/lio-client provides three main APIs for interacting with Lytics.

Workflows API

Monitor and query workflow execution status.

`workflows.list(options?)`

List all workflow jobs, optionally filtered by workflow name:


// All workflows
const allJobs = await lio.workflows.list();
 
// Filter by workflow name (kebab-case converted to snake_case)
const syncJobs = await lio.workflows.list({ 
  workflow: 'contentstack-import' 
});

Response:


{
  data: Array<{
    id: string;
    name: string;
    workflow: string;
    status: 'sleeping' | 'running' | 'completed' | 'failed';
    created: string;
    updated: string;
  }>
}

`workflows.get(jobId)`

Get details for a specific workflow job:


const job = await lio.workflows.get('job-abc123');

`workflows.getLogs(jobId, options?)`

Retrieve logs for a workflow job:


const logs = await lio.workflows.getLogs('job-abc123', {
  limit: 100,
  offset: 0
});

Workflow Name Conversion: lio-client automatically converts kebab-case names (e.g., contentstack-import) to snake_case (e.g., contentstack_import) for the API.

Content API

Query content entities enriched by Lytics.

`content.getByUrl(url)`

Fetch a content entity by URL:


const content = await lio.content.getByUrl('example.com/blog/post');

URL Normalization: Protocols are automatically stripped (both https://example.com/page and example.com/page work).

Response:


{
  url: string;
  hashedurl: string;
  uid: string;           // UID from content import workflow
  title?: string;
  description?: string;
  lytics?: {             // Lytics-generated topics
    [topic: string]: number;
  };
  _segments?: string[];  // Segments this content belongs to
  // ... other fields from your content schema
}

`content.scan(options?)`

Scan content entities using ad-hoc SegmentQL queries:


// Scan all content (default filter: *)
for await (const batch of lio.content.scan()) {
  console.log(`Processing ${batch.length} items`);
  for (const item of batch) {
    console.log(item.url, item.title);
  }
}
 
// Filter with SegmentQL
for await (const batch of lio.content.scan({
  filter: 'AND (EXISTS title, aspects = "article")',
  limit: 50
})) {
  // Process only articles with titles
}
 
// Filter by date
for await (const batch of lio.content.scan({
  filter: '_created > "now-30d"',
  limit: 100
})) {
  // Process content from last 30 days
}

Options:

filter (string): SegmentQL filter expression (default: * for all content)
limit (number): Results per page (default: 100)
fields (string[]): Specific fields to return

SegmentQL Syntax: Use Lytics SegmentQL for filtering: EXISTS field, field = "value", AND (...), OR (...). See Lytics SegmentQL docs for full syntax.

`content.scanSegment(segmentId, options?)`

Scan content from a saved segment (created in Lytics UI):


// Scan the 'all_documents' segment (created automatically by Lytics)
for await (const batch of lio.content.scanSegment('all_documents')) {
  console.log(`Got ${batch.length} documents`);
}
 
// Scan custom segment by ID or slug
for await (const batch of lio.content.scanSegment('blog_articles')) {
  // Process blog articles defined in Lytics segment
}
 
// Export high-performing content to another system
const allContent = [];
for await (const batch of lio.content.scanSegment('high_performing_content', { limit: 50 })) {
  allContent.push(...batch);
}
await exportToContentful(allContent);

Parameters:

segmentId (string): Segment ID or slug from Lytics
options.limit (number): Results per page (default: 100)
options.fields (string[]): Specific fields to return

Reuse Business Logic: scanSegment() lets you reuse complex SegmentQL queries defined in Lytics UI, avoiding duplication in your code.

Memory Efficient: Both scan() and scanSegment() use async generators to avoid loading all content into memory at once.

Schema API

Introspect Lytics data schemas with automatic caching.

`schema.get(tableName, options?)`

Get schema definition for a table:


const contentSchema = await lio.schema.get('content');

Response:


{
  columns: Array<{
    name: string;
    type: string;
    description?: string;
  }>;
  // ... other schema metadata
}

Caching:

Schemas are cached in-memory for 1 hour by default
Reduces unnecessary API calls
Clear cache manually if needed

`schema.clearCache()`

Clear the schema cache:


lio.schema.clearCache();

Cache Benefits: Schema rarely changes, so caching improves performance and reduces API load.

Error Handling

All APIs follow consistent error patterns:


try {
  const content = await lio.content.getByUrl('example.com/page');
} catch (error) {
  console.error('Status:', error.status);      // HTTP status code
  console.error('Message:', error.message);    // Error message
  console.error('Request ID:', error.request_id); // Lytics request ID for debugging
}

Type Safety

All APIs have full TypeScript definitions:


import type {
  WorkflowListResponse,
  WorkflowGetResponse,
  ContentEntity,
  SchemaResponse
} from '@lytics/lio-client';

Next Steps

Plugins - Extend with CMS-specific functionality
Examples - Real-world integration patterns