Executes a Workflow using its currently deployed revision.
Runs the Workflow graph synchronously and returns the complete result. The Workflow must have a deployed revision; requests against an undeployed Workflow are rejected.
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.
Authorization
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
The unique identifier of the Workflow.
The tenant identifier
The execution parameters and inputs.
A dictionary of input parameters for the agent execution. Keys correspond to parameter names defined in the agent's entry point flow step.
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.
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.
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.
The chat user initiating the execution, if applicable. Populated when the request originates from a connector (e.g., Slack, Teams).
An optional session ID for maintaining execution context across requests. When provided, the agent can resume a previous conversation session.
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.
uuid§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.
uuidThe 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).
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.
uuidThe 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.
uuidIdentifies 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.
length <= 64Integration-config variant this execution resolves against. Defaults to Fruxon.Model.ExecutionEngine.ExecutionMode.Production.
"UNSPECIFIED" | "PRODUCTION" | "SANDBOX"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.
int64Origin 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.
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).
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.
uuidTrue 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.
The parent run's async-operation id this sub-task satisfies (pins the exact spawning call). Null for top-level runs.
uuidTop-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).
uuidWhat 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.
"UNSPECIFIED" | "ROOT" | "SUB_TASK" | "CONSULT"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.
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.
"UNSPECIFIED" | "READ_ONLY" | "REVERSIBLE" | "IRREVERSIBLE"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.
int64Forces 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.
Response Body
curl -X POST "https://api.fruxon.com/v1/tenants/string/workflows/string:execute" \ -H "Content-Type: application/json" \ -d '{}'{
"response": "string",
"trace": {
"agentId": "string",
"agentRevision": 0,
"createdAt": 0,
"parameters": {},
"startTime": 0,
"endTime": 0,
"duration": 0,
"traces": [
{
"id": "string",
"displayName": "string",
"type": "UNSPECIFIED",
"llmStepTrace": null,
"toolTrace": null,
"hitlTrace": null,
"steps": [],
"result": null,
"status": "UNSPECIFIED",
"error": "string",
"startTime": 0,
"endTime": 0,
"duration": 0
}
],
"result": {
"strValue": "string",
"jsonValue": null,
"fileLink": "string",
"flowControl": null
},
"inputCost": 0,
"outputCost": 0,
"totalCost": 0
},
"sessionId": "string",
"links": [
{
"fileId": "string",
"fileType": "string",
"displayName": "string",
"promptLink": "<string:string/>"
}
],
"executionRecordId": "00000000-0000-0000-0000-000000000000",
"status": "COMPLETED",
"humanApprovalRequestId": "00000000-0000-0000-0000-000000000000",
"suppressOutbound": false,
"messageBlocks": []
}{
"type": "string",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"property1": null,
"property2": null
}{
"type": "string",
"title": "string",
"status": 0,
"detail": "string",
"instance": "string",
"property1": null,
"property2": null
}