Integrate with Flowcore REST services

Flowcore v2 uses domain-specific REST services rather than one universal API endpoint. Each service owns its routes, authentication modes, request schemas, pagination, and OpenAPI description.

The TypeScript SDK is the preferred client because its commands encode those differences. Use raw HTTP when your application runs in another language, an integration platform cannot use the SDK, or you need a service contract not yet represented by your installed package.

Treat each service as a separate API

Flowcore domains include services for:

• Data cores, flow types, and event types
• Event ingestion
• Event and time-bucket queries
• IAM
• API keys, variables, and secrets
• Data Pathways control plane and worker operations
• AI Agent Coordinator
• Legacy GraphQL compatibility

Do not assume that one host, path prefix, or authentication header works for all domains.

The managed ingestion service uses https://webhook.api.flowcore.io. GraphQL compatibility uses the GraphQL service. Other domains have dedicated service hosts selected by SDK commands.

Dedicated Flowcore installations may expose different hostnames. Use the installation's service discovery and OpenAPI documentation.

Use OpenAPI for raw HTTP contracts

For a raw REST integration, obtain the current Swagger or OpenAPI document for the exact service and environment.

Use it to confirm:

• Base URL
• API version and path
• HTTP method
• Authentication scheme
• Required headers
• Request-body schema
• Response-body schema
• Pagination fields
• Error model
• Operation-specific limits

Do not derive a route by reading an SDK class name or copying a path from a different service version.

Generate a client from the approved OpenAPI document when your language ecosystem supports it, but review generated retry, timeout, and authentication behavior before production use.

Choose the correct authentication scheme

API key

Use application API keys for supported REST, ingestion, and worker operations.

Store the key in a secret manager and attach it exactly as the service contract requires. The ingestion service has historically used raw API-key authorization behavior that the SDK handles automatically.

Bearer token

Use OAuth bearer tokens for user or administrative APIs that require user context, GraphQL compatibility, and AI Agent Coordinator operations.

Refresh tokens through the approved identity flow. Do not hard-code a short-lived user access token in a service.

Delivery endpoint credentials

Managed Data Pathway delivery credentials authenticate Flowcore workers to your endpoint. They are not the same as the application's Flowcore API key.

Use a separate secret or signature, validate it before processing, and rotate it independently.

Keep tenant and resource scope explicit

Flowcore requests often require a tenant plus a resource ID or resource name.

A 404 can mean the resource does not exist, the tenant scope is wrong, or the caller cannot resolve the resource under that scope. Log the non-sensitive identifiers used by the request.

Do not accept an arbitrary tenant from an untrusted browser and forward it with an administrator credential. The application must authorize tenant scope before constructing the Flowcore request.

Send the correct content type

Use JSON content types for JSON APIs and the exact multipart or binary contract for supported file endpoints.

Validate outbound payloads before sending them. A 422 response usually indicates a schema or semantic validation problem, not a transient network failure.

Do not stringify a schema object twice or send JSON Schema as an escaped string when the API expects an object.

Understand pagination styles

Flowcore services use more than one pagination model.

Cursor pagination

Event listing returns a nextCursor. Pass that cursor to the next request until it is absent.

Do not calculate or decode an opaque cursor.

Time-bucket pagination

List available time buckets, then page through events within each bucket. Maintain separate progress for bucket pages and event pages.

Numeric cursor pagination

Some time-bucket lists use numeric cursors. Pass the returned value rather than incrementing by the requested page size unless the service explicitly documents offset semantics.

Limit and offset pagination

Administrative list endpoints such as some Data Pathway resources use limit and offset, and may return a total count.

Follow the endpoint's specific response. Do not reuse one pagination helper across incompatible models merely because all requests contain a limit field.

Keep page sizes bounded

A maximum accepted page size is not necessarily the best operational size.

Choose a page that:

• Fits comfortably in memory
• Completes before request deadlines
• Lets progress commit frequently
• Does not overload downstream processing
• Limits repeated work after failure

Apply server-side filters for tenant, status, event type, range, or pathway whenever available. Fetching a broad result and filtering in memory increases latency and may expose data the application did not need.

Preserve event positions

For ascending event processing, store the current time bucket and last safely processed event ID.

Use afterEventId when resuming after a completed event. Do not combine mutually exclusive range fields such as fromEventId and afterEventId.

Descending event reads are for recent inspection. They can have different filter and pagination behavior and should not be used as a durable replay loop.

Interpret common HTTP statuses

400 Bad Request

The request shape, parameter combination, or syntax is invalid. Correct the caller.

401 Unauthorized

Authentication is missing, invalid, expired, or not supported by this endpoint. Check the authentication scheme and token/key value.

403 Forbidden

Authentication succeeded but IAM does not permit the action. Identify the missing action and resource scope. Do not loop retries.

404 Not Found

The path, tenant, resource ID, or resource name is wrong, or the resource is unavailable in the caller's scope.

409 Conflict

The request conflicts with resource state, such as delete protection, an existing identity, or an asynchronous lifecycle operation.

422 Unprocessable Content

The body is syntactically valid JSON but fails domain or schema validation. Inspect field-level errors and correct the payload.

429 Too Many Requests

The caller exceeded a rate or capacity limit. Respect Retry-After when supplied, reduce concurrency, and preserve idempotency across retries.

5xx Service Error

The service failed to complete the request. Use bounded backoff for safe operations and retain correlation details for support.

A timeout or connection reset has an uncertain outcome. Verify state or retry with stable operation identity.

Design idempotency per operation

Read operations can normally be retried safely.

Create, ingest, restart, delete, and side-effecting operations require more care.

Some APIs use client-generated IDs and idempotent PUT behavior, such as Data Pathway creation. Ingestion returns event IDs but does not make repeated business commands identical automatically.

Use stable source IDs, command IDs, or client-generated resource IDs where the API supports them. Do not generate a new identity on every retry.

Respect asynchronous lifecycle operations

Deletion, truncation, restart, and some operational commands are request-and-monitor workflows.

An accepted response can mean the operation was queued, not completed. Capture the operation or resource status, poll or wait through the documented API, and verify final state.

Do not hold a short browser request open indefinitely while waiting for fleet-wide pathway restart or destructive deletion.

Handle correlation and diagnostics safely

Record:

• Service domain and operation
• HTTP status
• Tenant and non-sensitive resource IDs
• Request or correlation ID returned by the service
• Attempt count and duration
• Retry decision

Do not log:

• API keys or bearer tokens
• Delivery secrets
• Complete sensitive event payloads
• Secret values returned during creation
• Unredacted error bodies that may contain protected fields

Important current limits and defaults

High-impact values documented by current SDK and Pathways sources include:

• SDK batch ingestion: up to 25 events per request
• Single-event webhook body: maximum 64 KB, including envelope overhead
• SDK retry default: 250 ms delay and three attempts
• Pathways global handler timeout default: commonly 10 seconds unless configured
• Managed Data Pathway size classes: small, medium, and high
• Delivery semantics: at least once, so duplicate delivery is possible
• Event history access: time buckets plus cursor or event-ID pagination

These are integration defaults, not workload guarantees. Account quotas, product plans, dedicated-cluster capacity, and package versions can change effective limits.

Verify limits at the right source

Before encoding a limit into validation or capacity planning, check:

1. The installed SDK or Pathways type and release notes
2. The service's current OpenAPI schema
3. Tenant quota and account plan
4. Dedicated-installation configuration where applicable
5. Observed production behavior under representative load

Marketing throughput figures are not a per-handler service-level guarantee. Endpoint latency, payload size, retry rate, and downstream capacity all affect real throughput.

Use SDK types as a versioned reference

For TypeScript integrations, inspect the command input and output types exported by your installed @flowcore/sdk version. They provide the exact field names expected by that package.

If package types and a deployed OpenAPI service disagree, do not guess. Confirm compatible versions or use the service contract intentionally, then document the discrepancy.

Prefer narrow integration adapters

Create one adapter per service domain rather than a generic unrestricted HTTP proxy.

A narrow adapter can own:

• Base URL and authentication
• Request and response validation
• Pagination
• Error mapping
• Retry and timeout policy
• Tenant authorization
• Metrics and audit logging

This keeps raw platform details out of business code and makes migrations between SDK or REST versions manageable.

Return to Use SDK command families for typed operations by domain.