Workflow assistant

The conversational assistant embedded in the Workflow AI canvas (the "Super Agent"). It can build and modify workflows from a prompt, run tools directly, answer questions about a table, and remembers facts and reusable skills across conversations.

Endpoints

Method	Path	Purpose
POST	`/microservices/prompt-2-workflow/agent/`	Talk to the workflow copilot
POST	`/microservices/workflow/agent-message/`	Reply to a running agent node
POST	`/microservices/workflow/agent-message/clear/`	Reset a node's agent conversation
GET	`/microservices/workflow/agent-message/skills/`	List skills
POST	`/microservices/workflow/agent-message/skills/`	Create a text skill
GET	`/microservices/workflow/agent-message/skills/{name}/`	Get a skill
PUT	`/microservices/workflow/agent-message/skills/{name}/`	Update a skill
DELETE	`/microservices/workflow/agent-message/skills/{name}/`	Delete a skill
POST	`/microservices/workflow/agent-message/skills/import/`	Import a packaged skill (zip)
GET	`/microservices/workflow/agent-message/skills/{name}/export/`	Export a skill as a zip
GET	`/microservices/workflow/agent-message/memory/`	List my memories
POST	`/microservices/workflow/agent-message/memory/`	Remember something
DELETE	`/microservices/workflow/agent-message/memory/`	Forget everything
GET	`/microservices/workflow/agent-message/memory/{memory_id}/`	Get one memory
DELETE	`/microservices/workflow/agent-message/memory/{memory_id}/`	Forget one memory

POST `/microservices/prompt-2-workflow/agent/`

Talk to the workflow copilot

The conversational assistant in the Workflow AI sidebar. Give it a prompt and it builds a workflow definition, modifies the open one, asks clarifying questions, or just answers. The platform adds context the copilot needs (your documents, the workflow's schedule and last run) automatically.

Streaming. With stream: true the response is Server-Sent Events:

event	data
`progress`	`{"message": "…"}` — a status line
`skeleton`	`{"json_spec": …}` — the graph structure, before parameters are filled
`workflow`	`{"status": "ok", "route": "build"\|"modify", "summary": "…", "json_spec": …, "warnings": […], "suggestions": […], "directives": […]}` or `{"status": "needs_clarification", "questions": [{"text": "…"}], "assistant_message": "…"}`
`message`	`{"assistant_message": "…"}` — a conversational reply
`error`	`{"error": "…"}`
`done`	end of turn

Without stream, the final workflow/message payload is returned as JSON.

Directives in a workflow payload are actions the copilot wants the app to take on its behalf (schedule, attach_file, revert); the app applies them through the ordinary endpoints (e.g. POST /microservices/workflow/schedule/).

Accounts with a running Dedicated Agent get 202 {"status": "started", …, "transport": "socket"} instead: the turn runs on their agent and the conversation arrives on ws/dedicated-agent/{agent_id}/.

Auth: Session token · In the app: Workflow AI → assistant sidebar

Request body (application/json)

Field	Type	Required	Description
`prompt`	string	yes
`stream`	boolean	no	Default: `false`.
`chat_history`	object[]	no	Prior turns `[{"role": "user"\|"assistant", "text": "…"}]`.
`current_workflow`	object	no	The workflow definition (`json_spec`). A directed graph of nodes; each node runs one catalogue tool (`kind` = the tool's `name` from `GET /microservices/apis/`) with its `params`. Execution starts at `entry`, follows `next`, and a node whose `requires.wait_for` names other nodes waits for them to finish first. Parameters may reference earlier outputs: - `"{{_output.<node_id>.<field>}}"` inside a string (interpolated), or - `{"$ref": "_output.<node_id>.<field>"}` as a whole value.
`current_workflow.name`	string	no
`current_workflow.version`	string	no
`current_workflow.entry`	string[]	no	Node ids that start the run.
`current_workflow.nodes`	object[]	yes
`current_workflow.nodes[].id`	string	yes	Unique within the workflow (the app uses `step1`, `step2`, …).
`current_workflow.nodes[].kind`	string	yes	Tool name from the catalogue.
`current_workflow.nodes[].name`	string	no	Display label (max 100 chars).
`current_workflow.nodes[].params`	object	no	Tool parameters, per the tool's `parameters` schema.
`current_workflow.nodes[].next`	string[]	no	Node ids to run after this one.
`current_workflow.nodes[].requires`	object	no
`current_workflow.nodes[].requires.wait_for`	string[]	no
`current_workflow.nodes[].save_output`	boolean	no	Keep this node's output as a persistent Output (Apps → outputs).
`current_workflow.nodes[].export_output`	boolean	no	Include the output in exports.
`current_workflow.edges`	object[]	no	Canvas edges (kept for the editor; execution follows `next`).
`workflow_id`	string (uuid)	no	The open workflow, for platform context.
`max_steps`	integer	no

json

{
  "prompt": "Every Monday search the web for competitor news and email me a summary.",
  "stream": true
}

Response 200 — SSE stream (stream: true) or the final JSON payload.

Content type: text/event-stream

text

event: progress
data: {"message": "Designing the workflow…"}

event: skeleton
data: {"json_spec": {"nodes": [{"id": "step1", "kind": "web_search"}, {"id": "step2", "kind": "llm_prompt"}, {"id": "step3", "kind": "send_email"}]}}

event: workflow
data: {"status": "ok", "route": "build", "summary": "Searches the web, summarises the results and emails them.", "json_spec": {"name": "Weekly competitor digest", "entry": ["step1"], "nodes": [ … ]}, "directives": [{"type": "schedule", "payload": {"type": "cron", "minute": "0", "hour": "8", "day_of_week": "1"}}]}

event: done
data: {}

Response 202 — The turn runs on the user's Dedicated Agent; listen on its socket.

Field	Type	Description
`status`	string (`"started"`)
`agent_id`	string
`chat_session_id`	integer, nullable
`session_id`	string, nullable
`transport`	string (`"socket"`)

Response 400 — prompt missing.

json

{
  "error": "path is required"
}

Response 503 — The copilot service is unreachable.

json

{
  "error": "path is required"
}

Example

bash

curl -X POST "https://api.example.com/microservices/prompt-2-workflow/agent/" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Every Monday search the web for competitor news and email me a summary.","stream":true}'

POST `/microservices/workflow/agent-message/`

Reply to a running agent node

Some tools are conversational: while their node is RUNNING they can ask the user something (an interrupt). This forwards the user's reply to that node's service; the node answers through the run's callback channel, which the canvas shows on the ws/workflow/{id}/nodes/ socket (agent_response frames).

Auth: Session token · In the app: Canvas → node chat bubble

Request body (application/json)

Field	Type	Required	Description
`workflow_id`	string (uuid)	yes
`node_id`	string (uuid)	yes	The node execution id.
`message`	string	yes
`interrupt_id`	string	no	Echo the interrupt id the node sent, when replying to a specific question.
`chat_history`	object[]	no
`attached_files`	object[]	no

Response 200 — Forwarded (empty body).

Response 400 — Missing fields or the node is not running.

json

{
  "error": "Node is not in RUNNING state (current: COMPLETED). Agent conversation may have ended."
}

Response 403 — Not your workflow.

Response 404 — Node not found, or its service is not registered.

Example

bash

curl -X POST "https://api.example.com/microservices/workflow/agent-message/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST `/microservices/workflow/agent-message/clear/`

Reset a node's agent conversation

Auth: Session token

Request body (application/json)

Field	Type	Required	Description
`workflow_id`	string (uuid)	yes
`node_id`	string (uuid)	yes

Response 200 — The service's response.

Response 503 — Service unreachable.

Response 504 — Service timed out.

Example

bash

curl -X POST "https://api.example.com/microservices/workflow/agent-message/clear/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET `/microservices/workflow/agent-message/skills/`

List skills

Auth: Session token · In the app: Chat AI / canvas → skill picker

Response 200 — Skills.

Field	Type	Description
`success`	boolean
`count`	integer
`skills`	object[]
`skills[].name`	string	Unique key.
`skills[].description`	string
`skills[].persona`	string	System-prompt style instructions.
`skills[].body`	string	The skill's procedure (Markdown).
`skills[].routing`	string	When the assistant should pick this skill automatically.
`skills[].allowed_tools`	string[]	Tool names the skill may call.
`skills[].enforce_allowed_tools`	boolean	Refuse tools outside `allowed_tools`.
`skills[].sticky`	boolean	Stay in this skill for the rest of the conversation.
`skills[].required_workspace`	string[]
`skills[].tool_params`	object	Default parameters per tool.
`skills[].locked_tool_params`	object	Parameters the user cannot change.
`skills[].kind`	string	`text` or `packaged`.
`skills[].created_at`	string (date-time)
`skills[].updated_at`	string (date-time)

Response 502 — Agent service unreachable.

json

{
  "error": "path is required"
}

Example

bash

curl -X GET "https://api.example.com/microservices/workflow/agent-message/skills/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST `/microservices/workflow/agent-message/skills/`

Create a text skill

Auth: Session token

Request body (application/json)

Field	Type	Required	Description
`name`	string	no	Unique key.
`description`	string	no
`persona`	string	no	System-prompt style instructions.
`body`	string	no	The skill's procedure (Markdown).
`routing`	string	no	When the assistant should pick this skill automatically.
`allowed_tools`	string[]	no	Tool names the skill may call.
`enforce_allowed_tools`	boolean	no	Refuse tools outside `allowed_tools`.
`sticky`	boolean	no	Stay in this skill for the rest of the conversation.
`required_workspace`	string[]	no
`tool_params`	object	no	Default parameters per tool.
`locked_tool_params`	object	no	Parameters the user cannot change.
`kind`	string	no	`text` or `packaged`.
`created_at`	string (date-time)	no
`updated_at`	string (date-time)	no

json

{
  "name": "weekly-report",
  "description": "Build the weekly KPI report from the finance tables.",
  "persona": "You are a meticulous financial analyst.",
  "body": "1. Query the orders table for the last 7 days.\n2. Compute revenue by region.\n3. Produce a dashboard and a one-page summary.\n",
  "allowed_tools": [
    "advance_sql_search",
    "dashboard",
    "file_writer"
  ],
  "enforce_allowed_tools": true,
  "sticky": false,
  "kind": "text"
}

Response 200 — Created (the agent service's response).

Response 409 — A skill with that name exists.

Example

bash

curl -X POST "https://api.example.com/microservices/workflow/agent-message/skills/" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"weekly-report","description":"Build the weekly KPI report from the finance tables.","persona":"You are a meticulous financial analyst.","body":"1. Query the orders table for the last 7 days.\n2. Compute revenue by region.\n3. Produce a dashboard and a one-page summary.\n","allowed_tools":["advance_sql_search","dashboard","file_writer"],"enforce_allowed_tools":true,"sticky":false,"kind":"text"}'

GET `/microservices/workflow/agent-message/skills/{name}/`

Get a skill

Auth: Session token

Path parameters

Field	Type	Required	Description
`name`	string	yes

Response 200 — The skill.

Field	Type	Description
`skill`	object	A saved procedure the assistant can run in ("skill mode"). Text skills are created here; packaged skills (a zip with `SKILL.md` and working files) are imported.
`skill.name`	string	Unique key.
`skill.description`	string
`skill.persona`	string	System-prompt style instructions.
`skill.body`	string	The skill's procedure (Markdown).
`skill.routing`	string	When the assistant should pick this skill automatically.
`skill.allowed_tools`	string[]	Tool names the skill may call.
`skill.enforce_allowed_tools`	boolean	Refuse tools outside `allowed_tools`.
`skill.sticky`	boolean	Stay in this skill for the rest of the conversation.
`skill.required_workspace`	string[]
`skill.tool_params`	object	Default parameters per tool.
`skill.locked_tool_params`	object	Parameters the user cannot change.
`skill.kind`	string	`text` or `packaged`.
`skill.created_at`	string (date-time)
`skill.updated_at`	string (date-time)

Response 404 — Unknown skill.

Example

bash

curl -X GET "https://api.example.com/microservices/workflow/agent-message/skills/weekly-report/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

PUT `/microservices/workflow/agent-message/skills/{name}/`

Update a skill

Auth: Session token

Path parameters

Field	Type	Required	Description
`name`	string	yes

Request body (application/json)

Field	Type	Required	Description
`name`	string	no	Unique key.
`description`	string	no
`persona`	string	no	System-prompt style instructions.
`body`	string	no	The skill's procedure (Markdown).
`routing`	string	no	When the assistant should pick this skill automatically.
`allowed_tools`	string[]	no	Tool names the skill may call.
`enforce_allowed_tools`	boolean	no	Refuse tools outside `allowed_tools`.
`sticky`	boolean	no	Stay in this skill for the rest of the conversation.
`required_workspace`	string[]	no
`tool_params`	object	no	Default parameters per tool.
`locked_tool_params`	object	no	Parameters the user cannot change.
`kind`	string	no	`text` or `packaged`.
`created_at`	string (date-time)	no
`updated_at`	string (date-time)	no

json

{
  "name": "weekly-report",
  "description": "Build the weekly KPI report from the finance tables.",
  "persona": "You are a meticulous financial analyst.",
  "body": "1. Query the orders table for the last 7 days.\n2. Compute revenue by region.\n3. Produce a dashboard and a one-page summary.\n",
  "allowed_tools": [
    "advance_sql_search",
    "dashboard",
    "file_writer"
  ],
  "enforce_allowed_tools": true,
  "sticky": false,
  "kind": "text"
}

Response 200 — Updated.

Example

bash

curl -X PUT "https://api.example.com/microservices/workflow/agent-message/skills/<name>/" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"weekly-report","description":"Build the weekly KPI report from the finance tables.","persona":"You are a meticulous financial analyst.","body":"1. Query the orders table for the last 7 days.\n2. Compute revenue by region.\n3. Produce a dashboard and a one-page summary.\n","allowed_tools":["advance_sql_search","dashboard","file_writer"],"enforce_allowed_tools":true,"sticky":false,"kind":"text"}'

DELETE `/microservices/workflow/agent-message/skills/{name}/`

Delete a skill

Auth: Session token

Path parameters

Field	Type	Required	Description
`name`	string	yes

Response 200 — Deleted.

Example

bash

curl -X DELETE "https://api.example.com/microservices/workflow/agent-message/skills/<name>/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST `/microservices/workflow/agent-message/skills/import/`

Import a packaged skill (zip)

Staff only. Upload a zip containing SKILL.md and any working files as the raw request body (Content-Type: application/zip). 409 when the name exists — resend with ?replace=true.

Auth: Session token · In the app: Skill picker → Import (staff)

Query parameters

Field	Type	Required	Description
`replace`	boolean	no

Request body (application/zip)

Response 200 — Imported.

Response 403 — Not staff.

Response 409 — Name exists.

Example

bash

curl -X POST "https://api.example.com/microservices/workflow/agent-message/skills/import/" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/zip" \
  --data-binary @weekly-report-skill.zip

GET `/microservices/workflow/agent-message/skills/{name}/export/`

Export a skill as a zip

Staff only. Text skills get a synthesised SKILL.md.

Auth: Session token

Path parameters

Field	Type	Required	Description
`name`	string	yes

Response 200 — The zip.

Content type: application/zip

Response 403 — Not staff.

Example

bash

curl -X GET "https://api.example.com/microservices/workflow/agent-message/skills/<name>/export/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET `/microservices/workflow/agent-message/memory/`

List my memories

What the assistant remembers about you across conversations. Written automatically after turns (at most 5 per turn, 200 per user) and explicitly with POST. enabled: false means the memory feature is off on this deployment.

Auth: Session token · In the app: Chat AI → Memory panel

Query parameters

Field	Type	Required	Description
`kind`	string (`"preference"`, `"fact"`, `"episode"`)	no
`limit`	integer	no	Default: `100`.

Response 200 — Memories.

Field	Type	Description
`success`	boolean
`count`	integer
`enabled`	boolean
`memories`	object[]
`memories[].memory_id`	string
`memories[].kind`	string (`"preference"`, `"fact"`, `"episode"`)
`memories[].text`	string
`memories[].confidence`	number
`memories[].created_at`	string (date-time)
`memories[].last_accessed_at`	string (date-time)
`memories[].source_thread_id`	string, nullable
`memories[].source_run_id`	string, nullable
`memories[].related_entities`	string[]

Example

bash

curl -X GET "https://api.example.com/microservices/workflow/agent-message/memory/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST `/microservices/workflow/agent-message/memory/`

Remember something

Saves a memory verbatim (no de-duplication) with confidence 0.95 by default.

Auth: Session token · In the app: Chat AI → "Remember this"

Request body (application/json)

Field	Type	Required	Description
`kind`	string (`"preference"`, `"fact"`, `"episode"`)	yes
`text`	string	yes
`confidence`	number	no	Default: `0.95`.
`source_thread_id`	string	no
`related_entities`	string[]	no

json

{
  "kind": "preference",
  "text": "Always reply in Arabic"
}

Response 201 — Saved.

Field	Type	Description
`success`	boolean
`memory_id`	string

Response 400 — Bad kind, empty text or bad confidence.

Response 503 — Memory feature disabled (or the account has no organisation).

Example

bash

curl -X POST "https://api.example.com/microservices/workflow/agent-message/memory/" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"kind":"preference","text":"Always reply in Arabic"}'

DELETE `/microservices/workflow/agent-message/memory/`

Forget everything

Requires ?confirm=all; without it nothing is deleted (400).

Auth: Session token · In the app: Memory panel → Forget all

Query parameters

Field	Type	Required	Description
`confirm`	string (`"all"`)	yes

Response 200 — Deleted (deleted_count is -1 by design).

Field	Type	Description
`success`	boolean
`username`	string
`organization_name`	string
`deleted_count`	integer

Example

bash

curl -X DELETE "https://api.example.com/microservices/workflow/agent-message/memory/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET `/microservices/workflow/agent-message/memory/{memory_id}/`

Get one memory

Auth: Session token

Path parameters

Field	Type	Required	Description
`memory_id`	string	yes

Response 200 — The memory.

Field	Type	Description
`success`	boolean
`memory`	object	One long-term memory the assistant keeps about the user.
`memory.memory_id`	string
`memory.kind`	string (`"preference"`, `"fact"`, `"episode"`)
`memory.text`	string
`memory.confidence`	number
`memory.created_at`	string (date-time)
`memory.last_accessed_at`	string (date-time)
`memory.source_thread_id`	string, nullable
`memory.source_run_id`	string, nullable
`memory.related_entities`	string[]

Response 403 — Belongs to another user.

Response 404 — Unknown id.

Example

bash

curl -X GET "https://api.example.com/microservices/workflow/agent-message/memory/<memory_id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

DELETE `/microservices/workflow/agent-message/memory/{memory_id}/`

Forget one memory

Auth: Session token

Path parameters

Field	Type	Required	Description
`memory_id`	string	yes

Response 200 — Deleted.

Field	Type	Description
`success`	boolean
`deleted`	string

Response 403 — Belongs to another user.

Response 404 — Unknown id.

Example

bash

curl -X DELETE "https://api.example.com/microservices/workflow/agent-message/memory/<memory_id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

Workflow assistant ​

Endpoints ​

POST /microservices/prompt-2-workflow/agent/ ​

POST /microservices/workflow/agent-message/ ​

POST /microservices/workflow/agent-message/clear/ ​

GET /microservices/workflow/agent-message/skills/ ​

POST /microservices/workflow/agent-message/skills/ ​

GET /microservices/workflow/agent-message/skills/{name}/ ​

PUT /microservices/workflow/agent-message/skills/{name}/ ​

DELETE /microservices/workflow/agent-message/skills/{name}/ ​

POST /microservices/workflow/agent-message/skills/import/ ​

GET /microservices/workflow/agent-message/skills/{name}/export/ ​

GET /microservices/workflow/agent-message/memory/ ​

POST /microservices/workflow/agent-message/memory/ ​

DELETE /microservices/workflow/agent-message/memory/ ​

GET /microservices/workflow/agent-message/memory/{memory_id}/ ​

DELETE /microservices/workflow/agent-message/memory/{memory_id}/ ​

Workflow assistant

Endpoints

POST `/microservices/prompt-2-workflow/agent/`

POST `/microservices/workflow/agent-message/`

POST `/microservices/workflow/agent-message/clear/`

GET `/microservices/workflow/agent-message/skills/`

POST `/microservices/workflow/agent-message/skills/`

GET `/microservices/workflow/agent-message/skills/{name}/`

PUT `/microservices/workflow/agent-message/skills/{name}/`

DELETE `/microservices/workflow/agent-message/skills/{name}/`

POST `/microservices/workflow/agent-message/skills/import/`

GET `/microservices/workflow/agent-message/skills/{name}/export/`

GET `/microservices/workflow/agent-message/memory/`

POST `/microservices/workflow/agent-message/memory/`

DELETE `/microservices/workflow/agent-message/memory/`

GET `/microservices/workflow/agent-message/memory/{memory_id}/`

DELETE `/microservices/workflow/agent-message/memory/{memory_id}/`