FruxonDocs
ApiWorkflow execution

Executes a Workflow with streaming output.

The SSE sibling of M:Fruxon.Server.Controllers.WorkflowExecutionController.Execute(System.String,Fruxon.Model.Agents.AgentExecutionRequest,System.Threading.CancellationToken). Runs the Workflow's deployed revision and returns results as Server-Sent Events for real-time progress updates.

API-Only Endpoint

This endpoint is available via API only and requires a Fruxon bearer token: Authorization: Bearer YOUR_TOKEN. Fill in your parameters below and the code samples will update automatically. To generate a token, see the Settings guide.

POST
/v1/tenants/{tenant}/workflows/{workflow}:stream
AuthorizationBearer <token>

Fruxon token presented as a Bearer token: Authorization: Bearer fx_pat_… (personal) or fx_sat_… (service account). Generate one from Settings → API Access.

In: header

Path Parameters

workflow*string

The unique identifier of the Workflow.

tenant*string

The tenant identifier

The execution parameters and inputs.

parameters?

A dictionary of input parameters for the agent execution. Keys correspond to parameter names defined in the agent's entry point flow step.

attachments?

A list of file attachments included with the execution request. These are files sent by the user (e.g., via a connector) that the agent can access during execution.

deferredAttachments?

P0-3 — inbound media references stamped at the webhook without downloading the bytes there. The worker resolves these into Fruxon.Model.Agents.AgentExecutionRequest.Attachments (and weaves their prompt-links into the Fruxon.Model.Agents.AgentExecutionRequest.UserQueryParameter) just before execution, off the inbound hot path. Empty for the eager path and for non-chat runs. See Fruxon.Model.Storage.DeferredAttachment and the worker's DeferredMediaResolver.

deferredAttachmentBaseText?string|null

P0-3 — the raw message text the rendered Fruxon.Model.Agents.AgentExecutionRequest.UserQueryParameter ends with when this request carries Fruxon.Model.Agents.AgentExecutionRequest.DeferredAttachments (links not yet appended). The worker uses it to splice resolved attachment prompt-links into the query exactly where the eager path would have. Null unless attachments were deferred. See InboundAttachmentPrompt.AppendResolvedLinks.

chatUser?

The chat user initiating the execution, if applicable. Populated when the request originates from a connector (e.g., Slack, Teams).

sessionId?string|null

An optional session ID for maintaining execution context across requests. When provided, the agent can resume a previous conversation session.

participantId?string|null

The resolved participant id for this run's inbound venue, lifted from the task's ParticipantContext metadata by Fruxon.Model.Agents.AgentExecutionService.ExecuteFromQueueAsync and threaded onto Fruxon.Model.Agents.AgentContext.ParticipantId. The venue-precedence winner (the group in a group, the person in a DM). Null on non-queue paths (sync API / test, scheduler) and inbound from senders that matched no participant. See docs/design/identity-profile-normalization.md §6.4.

Formatuuid
senderParticipantId?string|null

§15.3 — the individual sender's participant id (distinct from Fruxon.Model.Agents.AgentExecutionRequest.ParticipantId, the venue, in a group), threaded onto Fruxon.Model.Agents.AgentContext.SenderParticipantId. Null when the sender isn't a known participant. Drives "who am I talking to" / memory subject, never routing.

Formatuuid
participantChannelIdentity?

The addressed person's messaging identity for a participant-directed run, lifted from the task's ParticipantContext (MatchedProvider/MatchedAddress/Kind) by Fruxon.Model.Agents.AgentExecutionService.ExecuteFromQueueAsync and threaded onto Fruxon.Model.Agents.AgentContext.ParticipantChannelIdentity. Lets a user-level integration credential bind to that person when the run carries no Fruxon.Model.Agents.AgentExecutionRequest.ChatUser (consult/topic turns). Null on non-participant paths (sync API / test, scheduler with no consult).

networkId?string

Required Application operating boundary selected for this run. Producers stamp the owning Agent/Application before execution or queue persistence, and queued/resumed requests carry it unchanged.

Formatuuid
runnableBindingId?string|null

The runnable binding that scheduled this execution — for a collection pipeline it is the pipeline id (the pipeline is the shipped runnable binding, build-plan artifact B). Part of the §10 RunnableExecutionContext; null for conversational/ad-hoc runs, which resolve via an Agent membership instead.

Formatuuid
environmentSlug?string|null

Identifies the environment this execution targets. Enables per-environment cost tracking, quota enforcement, and analytics. For system agents, this is automatically set to the calling tenant's slug.

Lengthlength <= 64
mode?string

Integration-config variant this execution resolves against. Defaults to Fruxon.Model.ExecutionEngine.ExecutionMode.Production.

Value in"UNSPECIFIED" | "PRODUCTION" | "SANDBOX"
occurredAt?integer|null

Provider-reported receipt time of the inbound message (Unix ms), the customer's actual send time — set by M:Fruxon.Model.Agents.AgentExecutionRequest.CreateForInboundMessage(Fruxon.Model.Messaging.Dispatch.InboundMessage,System.String,System.Guid) from InboundMessage.Date and threaded onto Fruxon.Model.Agents.AgentContext.OccurredAt so the persisted inbound userFruxon.Model.AgentSessions.AgentMessage.OccurredAt carries the real event time rather than the batch persist time. Null for non-chat runs (API, subtask, scheduler) and when the provider reported no timestamp. Survives the queued-payload round-trip.

Formatint64
messageOrigin?string|null

Origin marker for the user turns this run persists, threaded onto Fruxon.Model.Agents.AgentContext.MessageOrigin and stamped onto Fruxon.Model.AgentSessions.AgentMessage.Origin. Set to Fruxon.Model.AgentSessions.AgentMessage.OrchestrationOrigin by enqueue sites whose user_query is a platform-synthesized orchestration prompt (topic kickoff/resume/relay/interject, background async-op updates) so the conversations transcript can tell it apart from a participant's actual message. Null everywhere else — including synthetic-but-conversational prompts that ARE the exchanged content (an AI-peer consult question is what the peer asked, so it stays visible). Survives the queued-payload round-trip.

channelHandle?string|null

How the agent appears on the channel this run originated from — the provider bot handle (e.g. "@daria_bot"). Set by the inbound receivers from the integration config's Fruxon.Model.Integrations.Configs.ConnectionIdentity; surfaced to the model via Fruxon.Model.Agents.AgentContext.ChannelHandle in the identity preamble. Null for non-channel runs (API, test chat, triggers).

parentExecutionRecordId?string|null

When this run was spawned as a sub-task (e.g. spawn_subtask), the spawning run's execution-record id. Carried on the queued request so the child's execution record can be stamped with it when the worker eventually runs it, connecting the two traces. Null for top-level runs. See Fruxon.Model.ExecutionTraces.AgentExecutionRecord.ParentExecutionRecordId.

Formatuuid
isHeadlessChildRun?boolean

True when this run is a headless copy of the agent — it carries the flow's full system prompt but none of the conversation context (no TopicSession, no live participant dialogue, no inbox). Set only by SubtaskSpawnHelper.EnqueueChildAsync, the single choke point for spawn_subtask(s) fan-out and cross-agent delegation via AgentTaskToolExecutor. Drives ExecutionRequest.IsSpawnedChildRun, which the step executor uses to withhold the conversation-context and fan-out tools in ChildRunToolPolicy.

Declared explicitly rather than inferred from Fruxon.Model.Agents.AgentExecutionRequest.ParentExecutionRecordId != null. That inference conflated two orthogonal questions — "whose run tree do I belong to?" (lineage, observability) and "do I have a conversation?" (capability) — and they only ever agreed while sub-tasks were the sole thing with a parent record. Once TopicSessionRunner began stamping lineage on consult-opening, interject-notice, relay and resume runs so an investigator could walk from a parked consulter to the run that answered it, those genuinely conversation-bearing dialogue runs were misread as headless and stripped of resolve_topic / accept_interject / defer_interject — the very tools their prompts instruct them to call (prod, 2026-07-22 → 07-25: an interject notice asked the agent to accept or defer with neither tool present, so it could only emit prose). Fruxon.Model.Queues.CreateAgentTaskQueue.IsChildRun keeps the lineage-derived meaning — it gates run-credit admission, where "the parent's charge covers its tree" is exactly right.

parentAsyncOperationId?string|null

The parent run's async-operation id this sub-task satisfies (pins the exact spawning call). Null for top-level runs.

Formatuuid
rootExecutionId?string|null

Top-level ancestor of this run's spawn tree (the parent's root, or the parent's own id for a first-level child). Null for top-level runs (the record then roots itself).

Formatuuid
runType?string

What role this run plays in its spawn tree — set alongside the lineage ids above by whoever spawns the run (SubtaskSpawnHelper for delegated children, the consult dispatch paths for advisor runs). Carried on the queued request so the child's execution record can be stamped when the worker eventually runs it. Defaults to Fruxon.Model.ExecutionTraces.ExecutionRunType.Root — an ordinary top-level run.

Value in"UNSPECIFIED" | "ROOT" | "SUB_TASK" | "CONSULT"
subject?string|null

Short label for what this run is being asked to do, set by whoever spawns it when they know a better name than the raw prompt — the consult's goal, the sub-task's assignment. Left null on ordinary runs, where the record derives it from the run's own user_query input. See Fruxon.Model.ExecutionTraces.AgentExecutionRecord.Subject.

actionTypeCeiling?string

Optional per-run cap on the side-effect class of tools the agent may use, carried onto Fruxon.Model.ExecutionEngine.ExecutionRequest.ActionTypeCeiling at execution. Set by collection-pipeline fan-out from RunPolicy.ActionTypeCeiling (design §8.3); null for ordinary runs.

Value in"UNSPECIFIED" | "READ_ONLY" | "REVERSIBLE" | "IRREVERSIBLE"
agentRevision?integer|null

Optional pinned agent revision to run (the IRunnable binding's (AgentId, Revision)): when set, the queue execution runs this exact revision instead of resolving the agent's current one. Set by collection-pipeline fan-out so every item in a run executes the same revision — pinned at run start (design §10.8, "a pipeline pins the whole batch run to one release"); null for ordinary runs, which keep resolving the current revision. Survives the queue payload round-trip so a suspended item resumes on the same revision.

Formatint64
outputContractOverride?

Forces this run's answer into a declared shape, overriding whatever contract the agent's own terminal step carries. Set by a caller driving an agent it does not own — a ledger stage needs its transition verdict parseable, while the agent may promise something else to every other caller. Null leaves the agent's own contract alone.

[key: string]?never

Response Body

curl -X POST "https://api.fruxon.com/v1/tenants/string/workflows/string:stream" \  -H "Content-Type: application/json" \  -d '{}'
"string"
{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}
Empty
Empty
{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "property1": null,
  "property2": null
}