Use SDK command families

The Flowcore SDK groups commands by platform domain. Most resource families follow consistent verbs such as list, fetch, create, update, exists, and request delete.

Use this guide as a map to the command families. The installed SDK's exported TypeScript input types remain the exact reference for fields supported by your version.

Tenant commands

Tenant commands discover accessible tenants and support tenant administration where permitted.

Typical operations include:

• Listing tenants visible to the caller
• Fetching a tenant by stable identity or name
• Managing users and service identities
• Enabling or inspecting tenant-level Sensitive Data behavior

Tenant administration often represents a user or privileged platform action. Confirm whether the command requires bearer authentication rather than an application key.

Do not list all tenants on every application request. Resolve the configured tenant once and cache stable identifiers appropriately.

Data-core commands

The data-core family creates and governs top-level event containers.

import {
  DataCoreCreateCommand,
  DataCoreFetchCommand,
  DataCoreListCommand,
  DataCoreUpdateCommand,
} from "@flowcore/sdk"
 
const dataCore = await client.execute(
  new DataCoreCreateCommand({
    tenantId,
    name: "commerce",
    description: "Durable commerce event history",
    accessControl: "private",
    deleteProtection: true,
  }),
)

Production data cores should normally be private and delete-protected.

Fetch by ID when your application already resolved the resource. Name-based fetch is convenient in provisioning tools where names are the declared identity.

Deletion is asynchronous and destructive. Keep request-delete commands in controlled administrative workflows rather than normal application routes.

Flow-type commands

Flow types group related event types inside a data core.

import { FlowTypeCreateCommand } from "@flowcore/sdk"
 
const flowType = await client.execute(
  new FlowTypeCreateCommand({
    dataCoreId: dataCore.id,
    name: "order.0",
    description: "Order lifecycle events",
  }),
)

The family also includes list, fetch, exists, update, and request-delete operations.

Deleting a flow type affects its event types and consumers. Treat it as a lifecycle operation, not cleanup after a test call.

Event-type commands

Event-type commands manage one durable fact type:

import { EventTypeCreateCommand } from "@flowcore/sdk"
 
const eventType = await client.execute(
  new EventTypeCreateCommand({
    flowTypeId: flowType.id,
    name: "order.placed.0",
    description: "An order was accepted for processing",
  }),
)

Related operations include:

• List and fetch
• Existence checks
• Description updates
• Sensitive Data masks and enablement
• Event-type information and recent event inspection
• Sensitive-field removal or scrambling
• Truncation requests
• Deletion requests

Truncation removes retained history and is not equivalent to retiring an event version. Keep destructive commands behind explicit approval and audit records.

Sensitive Data commands

Event-type create and update commands can accept a sensitive-data mask. Separate commands can request field removal or scrambling and list previous removal operations.

Use them as part of a complete privacy workflow that also addresses projections, exports, caches, and backups.

Requesting sensitive data in an event query may require additional authorization. Keep includeSensitiveData false unless the operation needs the values.

Single-event ingestion

import { IngestEventCommand } from "@flowcore/sdk"
 
const eventId = await client.execute(
  new IngestEventCommand({
    tenantName: "acme-production",
    dataCoreId: dataCore.id,
    flowTypeName: "order.0",
    eventTypeName: "order.placed.0",
    eventData: payload,
    metadata: {
      source: "checkout-api",
      correlationId,
    },
    eventTime: new Date().toISOString(),
    validTime: new Date().toISOString(),
    isEphemeral: false,
  }),
)

The command handles the ingestion service's authentication behavior. Validate payloads in application code before executing the command.

A timeout can leave the outcome uncertain. Use stable command or source identities where duplicate publication would be harmful.

Batch ingestion

IngestBatchCommand accepts up to 25 events per request.

import { IngestBatchCommand } from "@flowcore/sdk"
 
await client.execute(
  new IngestBatchCommand({
    dataCoreId: dataCore.id,
    flowTypeName: "order.0",
    eventTypeName: "order.imported.0",
    events: sourceRecords.slice(0, 25),
    metadata: {
      source: "legacy-import",
      importBatchId,
    },
  }),
)

Chunk larger sources and reconcile accepted batches. Batch ingestion does not give downstream consumers one transaction across all events.

Discover time buckets

Use TimeBucketListCommand with event type IDs or EventsFetchTimeBucketsByNamesCommand with resource names.

import { TimeBucketListCommand } from "@flowcore/sdk"
 
const { timeBuckets, nextCursor } = await client.execute(
  new TimeBucketListCommand({
    tenant: "acme-production",
    eventTypeId: eventType.id,
    fromTimeBucket: "20260701h000000",
    order: "asc",
    pageSize: 100,
  }),
)

Iterate bucket pagination separately from event pagination.

Fetch retained events

EventListCommand reads by event type IDs. EventsFetchCommand reads using flow and event type names.

import { EventListCommand } from "@flowcore/sdk"
 
let cursor: string | undefined
 
do {
  const page = await client.execute(
    new EventListCommand({
      tenant: "acme-production",
      eventTypeId: [orderPlacedId, orderCancelledId],
      timeBucket,
      cursor,
      pageSize: 500,
      order: "asc",
      includeSensitiveData: false,
    }),
  )
 
  await processPage(page.events)
  cursor = page.nextCursor
} while (cursor)

Use ascending order for replay and projection work. Descending reads are intended for recent inspection and have different filter and pagination behavior.

Persist the time bucket and last safe event ID for resumable processing. Use Data Pathways rather than hand-written query loops for continuous production consumers.

IAM commands

The SDK covers roles, policies, bindings or associations, permission discovery, and Flowcore resource names.

Use IAM commands in administrative tools that can explain and audit the requested access change. Do not expose a generic “execute policy JSON” endpoint to browser clients.

Resolve least-privilege actions before creating a role. Separate application publishing, querying, provisioning, pathway operations, and destructive administration.

API keys, variables, and secrets

The SDK includes command families for application credentials and tenant-scoped configuration.

When creating an API key, store the returned secret value immediately. Do not expect to retrieve the same secret later.

Variables are configuration values and secrets are protected values; do not treat naming alone as sufficient protection. Restrict who can list metadata, create values, rotate them, and bind them to workloads.

Data Pathway lifecycle commands

Pathway control-plane commands can create, fetch, list, and disable Data Pathways.

import { DataPathwayCreateCommand } from "@flowcore/sdk"
 
await bearerClient.execute(
  new DataPathwayCreateCommand({
    id: pathwayId,
    tenant: "acme-production",
    dataCore: "commerce",
    sizeClass: "small",
    enabled: true,
    priority: 10,
    labels: {
      name: "Order projection",
      owner: "orders-team",
    },
    config: pathwayConfig,
  }),
)

Pathway creation uses a client-provided ID with idempotent PUT behavior. Administrative pathway commands use bearer authentication in the current command family.

Disable a pathway during unsafe delivery or maintenance instead of deleting configuration immediately.

Slot and assignment commands

Managed Data Pathway workers use slots for capacity and assignments for leased work.

Worker operations include:

• Registering and deregistering slots
• Sending slot heartbeats
• Fetching slot state
• Requesting the next assignment
• Sending assignment heartbeats
• Completing or failing assignments
• Expiring abandoned leases

These use API-key authentication and are normally implemented by platform workers, not business applications.

Assignment heartbeats can report fetched and delivered totals, errors, buffer depth, and lag. A lease expires if the worker stops extending it, allowing recovery by another slot.

Restart, command, capacity, quota, and pump-state operations

The extended Data Pathway command family supports operational control:

• Requesting pathway restarts
• Targeting pathways, flow types, or labels
• Dispatching restart or stop commands
• Reporting worker command phases
• Querying available and used size-class capacity
• Managing tenant quotas
• Fetching and saving assignment pump state

A restart request can specify a time bucket or event ID. Treat it as a replay-capable operation and inspect accepted versus skipped targets before assuming all workers changed position.

Assignment generation protects newer assignments from stale commands. Include and verify generation information in worker control flows.

Pump state should be saved after successful processing, not before.

Choose the right abstraction

Use direct SDK resource commands for administrative backends, provisioning services, and focused tools.

Use v2 manifests and the CLI when desired state belongs in source control and review.

Use Pathways when application contracts and processing runtime belong in code.

Use Data Pathways for continuous delivery rather than maintaining a custom event-query loop.

Continue with Integrate with Flowcore REST services for raw HTTP, pagination, errors, and limits.