# Comerix Flow

> Embeddable chat and forms, flow automation, and the public + server-to-server HTTP APIs of Comerix Flow.

## Docs

- [Failures grouped by node](https://comerix-flow-docs.hryvinskyi.com/api-reference/analytics/failures-grouped-by-node.md): For a single flow, the nodes where executions are failing, over a `d7` or `d30` window (default `d7`). `flow_id` is required.
- [Flow-run summary](https://comerix-flow-docs.hryvinskyi.com/api-reference/analytics/flow-run-summary.md): Aggregate flow-run metrics for the date range. Authenticated by the admin session cookie; the tenant comes from the signed-in user. Requires the `comerix.insights.analytics` permission.
- [Flow-run timeseries](https://comerix-flow-docs.hryvinskyi.com/api-reference/analytics/flow-run-timeseries.md): Per-day flow-run metrics for the range, optionally narrowed to one flow.
- [Top flows by volume](https://comerix-flow-docs.hryvinskyi.com/api-reference/analytics/top-flows-by-volume.md): The busiest flows in the range, capped by `limit` (1–50, default 10).
- [List readable configuration fields](https://comerix-flow-docs.hryvinskyi.com/api-reference/config/list-readable-configuration-fields.md): The discovery call: returns the catalog of configuration fields the caller may read — the `api_readable` schema allowlist intersected with the caller's per-section view permissions (`comerix.config.<section>.view`). No values are returned; read one with `GET /api/v2/config/{path}`.
- [Read one configuration value](https://comerix-flow-docs.hryvinskyi.com/api-reference/config/read-one-configuration-value.md): Resolves one non-secret configuration value by its full slash path (`<section>/<group>/<field>`), inheritance-aware along Global → Organization → Workspace.
- [Report a deferred conversion](https://comerix-flow-docs.hryvinskyi.com/api-reference/conversions/report-a-deferred-conversion.md): Records a conversion against a tenant goal — typically a sale completed after the chat ended. Attach it to a `conversation_id` for attribution, or to an `external_ref` carried through your funnel. Repeated calls for the same conversion are deduplicated.
- [Emit a domain event](https://comerix-flow-docs.hryvinskyi.com/api-reference/engine-api/emit-a-domain-event.md): Emits a named event into the tenant's event bus, starting one execution per matched (and filter-passing) subscription. Pass an `idempotency_key` in the body to make redelivery safe.
- [Read the published intent catalog](https://comerix-flow-docs.hryvinskyi.com/api-reference/engine-api/read-the-published-intent-catalog.md): Returns the tenant's currently-published intents. The response carries a weak `ETag` and a suggested `cache_max_age_seconds`; send the value back in `If-None-Match` to get a `304 Not Modified` when nothing changed.
- [Resume a waiting execution](https://comerix-flow-docs.hryvinskyi.com/api-reference/engine-api/resume-a-waiting-execution.md): Resumes a paused execution by presenting its `wait_token` and any collected `input`. Returns the same execution envelope as trigger. Supports the `Idempotency-Key` header with the same semantics.
- [Trigger a chat intent](https://comerix-flow-docs.hryvinskyi.com/api-reference/engine-api/trigger-a-chat-intent.md): Starts a new execution of the named intent. Returns the standard execution envelope (`ChatReply` shape). Send an `Idempotency-Key` header so a retried trigger returns the cached response (24h TTL); reusing the key with a different payload yields `409 idempotency_conflict`.
- [Record a client-side telemetry event](https://comerix-flow-docs.hryvinskyi.com/api-reference/events/record-a-client-side-telemetry-event.md): Writes a single event row tied to the conversation. Used for lifecycle signals (`widget_open`, `conversation_started`), messaging (`message_sent`, `link_click`), and commerce/goal signals (`add_to_cart`, `purchase` — put the amount in `props.value` and the ISO-4217 code in `props.currency`).
- [Record up to 50 telemetry events at once](https://comerix-flow-docs.hryvinskyi.com/api-reference/events/record-up-to-50-telemetry-events-at-once.md): Batched variant of `POST /events` — send an array of events in one request. Strict: the first invalid event fails the whole batch with a `422` whose `details.index` points at the offending entry. On success every event is recorded and matched against goals exactly as the single-event endpoint.
- [Poll the current state of an execution](https://comerix-flow-docs.hryvinskyi.com/api-reference/executions/poll-the-current-state-of-an-execution.md): Returns the same `Reply` envelope as `/messages`. Used when a flow paused on async work (`status: waiting_time`) and the widget needs to know when it has progressed. Polling is non-destructive — blocks stay in the snapshot, so the widget must dedupe by `block.id`.
- [Claim a source for crawling](https://comerix-flow-docs.hryvinskyi.com/api-reference/knowledge-base/claim-a-source-for-crawling.md): Moves a due source into the `crawling` state and returns its crawl configuration. Claiming a source that is not claimable (e.g. already `crawling`) returns `409 not_claimable`.
- [List sources due to be crawled](https://comerix-flow-docs.hryvinskyi.com/api-reference/knowledge-base/list-sources-due-to-be-crawled.md): Returns knowledge-base sources due to be crawled across all active tenants (the queue is cross-tenant by design). `?limit` caps the page size (default 50). Each item carries the source's crawl configuration and current status.
- [Report live crawl progress](https://comerix-flow-docs.hryvinskyi.com/api-reference/knowledge-base/report-live-crawl-progress.md): Records page counts for a source that is currently `crawling`. Reporting progress for a source that is not crawling returns `409 not_crawling`.
- [Report the crawl outcome](https://comerix-flow-docs.hryvinskyi.com/api-reference/knowledge-base/report-the-crawl-outcome.md): Finalises a crawl, moving the source to `ready` or `failed`. A repeat call reporting the status the source is already in is an idempotent no-op. On `ready` the next crawl time is recomputed from the schedule; on `failed` `last_error` is stored and no re-crawl is scheduled.
- [MCP JSON-RPC endpoint](https://comerix-flow-docs.hryvinskyi.com/api-reference/mcp/mcp-json-rpc-endpoint.md): A single endpoint speaking **JSON-RPC 2.0** (one request envelope per call; batch payloads are rejected). It exposes MCP tools grouped as `analytics.*`, `flows.*`, and `connections.*`. Authenticated by a scoped personal access token (`Bearer cfp_…`); each tool is gated by the intersection of the use…
- [Send a user message — trigger a new flow or resume a waiting one](https://comerix-flow-docs.hryvinskyi.com/api-reference/messages/send-a-user-message-—-trigger-a-new-flow-or-resume-a-waiting-one.md): Body shape decides the call:
- [Read one tenant's publicly readable configuration section](https://comerix-flow-docs.hryvinskyi.com/api-reference/public-config/read-one-tenants-publicly-readable-configuration-section.md): Returns the resolved values of every field of the section that is declared publicly readable (e.g. the widget appearance). Sections with no public fields are indistinguishable from unknown sections. Served from the published edge document when one exists, computed live otherwise.
- [Read the tenant's quick-question prompts, filtered to page types](https://comerix-flow-docs.hryvinskyi.com/api-reference/public-config/read-the-tenants-quick-question-prompts-filtered-to-page-types.md): Returns the one-tap prompts configured for the widget, optionally narrowed to several page types in one request (`?pageTypes=general,category`). Each row carries the intent name the presenting key may trigger; a prompt whose intent the key may not trigger keeps its row with `intentName: null`. Serve…
- [Fetch a render-safe form schema](https://comerix-flow-docs.hryvinskyi.com/api-reference/public-forms/fetch-a-render-safe-form-schema.md): Returns the public schema for an embeddable form — its fields, labels, validation hints, and submit label — so a client can render the form without the admin builder. The key's `form` scope must cover the requested form. The key may be supplied as the `publicKey` query param, the `X-Comerix-Public-K…
- [Fetch the cacheable form schema document](https://comerix-flow-docs.hryvinskyi.com/api-reference/public-forms/fetch-the-cacheable-form-schema-document.md): Cache-friendly sibling of `GET /api/public/v1/forms/{codeOrId}`: the same render-safe schema of one live, embeddable form, but served from the published edge document when one exists (computed live otherwise — identical content; the `X-Edge-Source` response header tells you which) and **never record…
- [Submit a form](https://comerix-flow-docs.hryvinskyi.com/api-reference/public-forms/submit-a-form.md): Records a standalone form submission. Optionally attach it to a chat `conversationId`, dedupe retries with a `clientSubmissionId`, and carry a spam honeypot in `_hp`. Returns `201` for a new submission, `200` when the `clientSubmissionId` was already seen (duplicate).
- [Upload a file for a form field](https://comerix-flow-docs.hryvinskyi.com/api-reference/public-forms/upload-a-file-for-a-form-field.md): Uploads one file for a file-type field on the form, returning a file reference to include in the matching `values` entry of the subsequent submission. Send the file as multipart field `file`; name the target field with the `field` query param.
- [Open a chat session](https://comerix-flow-docs.hryvinskyi.com/api-reference/session/open-a-chat-session.md): Validates the widget key + `Origin`, ensures a `Conversation` for the customer, and returns a signed `sessionToken` along with the list of intents the widget is permitted to trigger. Call this once per visitor session.
- [Your account & security](https://comerix-flow-docs.hryvinskyi.com/guide/admin/account.md)
- [Connections & plugins](https://comerix-flow-docs.hryvinskyi.com/guide/admin/connections.md)
- [Customers — Contacts & Identity](https://comerix-flow-docs.hryvinskyi.com/guide/admin/customers.md)
- [Building Flows (Flow Studio)](https://comerix-flow-docs.hryvinskyi.com/guide/admin/flows.md)
- [Forms](https://comerix-flow-docs.hryvinskyi.com/guide/admin/forms.md)
- [Goals & Conversions](https://comerix-flow-docs.hryvinskyi.com/guide/admin/goals.md)
- [Identity rules & merge review](https://comerix-flow-docs.hryvinskyi.com/guide/admin/identity-rules.md)
- [Flow Marketplace (Templates)](https://comerix-flow-docs.hryvinskyi.com/guide/admin/marketplace.md)
- [Admin panel](https://comerix-flow-docs.hryvinskyi.com/guide/admin/overview.md)
- [Public keys](https://comerix-flow-docs.hryvinskyi.com/guide/admin/public-keys.md)
- [Settings](https://comerix-flow-docs.hryvinskyi.com/guide/admin/settings.md)
- [Training base](https://comerix-flow-docs.hryvinskyi.com/guide/admin/training.md)
- [Transcripts — Conversations & Runs](https://comerix-flow-docs.hryvinskyi.com/guide/admin/transcripts.md)
- [Users, roles & permissions](https://comerix-flow-docs.hryvinskyi.com/guide/admin/users-roles.md)
- [Embedding the chat widget](https://comerix-flow-docs.hryvinskyi.com/guide/admin/widget.md)
- [Workspace, members & security policy](https://comerix-flow-docs.hryvinskyi.com/guide/admin/workspace.md)
- [Analytics Hub](https://comerix-flow-docs.hryvinskyi.com/guide/analytics-hub.md)
- [Concepts](https://comerix-flow-docs.hryvinskyi.com/guide/concepts.md)
- [Conversation lifecycle](https://comerix-flow-docs.hryvinskyi.com/guide/lifecycle.md)
- [End-to-end scenario](https://comerix-flow-docs.hryvinskyi.com/guide/scenario.md)
- [Comerix Flow — Public Chat API](https://comerix-flow-docs.hryvinskyi.com/index.md)
- [Blocks reference](https://comerix-flow-docs.hryvinskyi.com/reference/blocks.md)
- [Configuration read API](https://comerix-flow-docs.hryvinskyi.com/reference/config-api.md)
- [Engine API](https://comerix-flow-docs.hryvinskyi.com/reference/engine-api.md)
- [Errors](https://comerix-flow-docs.hryvinskyi.com/reference/errors.md)
- [MCP gateway](https://comerix-flow-docs.hryvinskyi.com/reference/mcp-api.md)
- [Operate](https://comerix-flow-docs.hryvinskyi.com/reference/operate.md)
- [Public read API](https://comerix-flow-docs.hryvinskyi.com/reference/public-read-api.md)
- [Webhooks](https://comerix-flow-docs.hryvinskyi.com/reference/webhooks.md)

## OpenAPI Specs

- [openapi](https://comerix-flow-docs.hryvinskyi.com/openapi.yaml)