Workflow AI

The Workflow AI canvas: create and edit workflows, run them, follow a run's progress, read node outputs and history, schedule runs, manage versions, tags, collaborators and the trash, and browse the tool catalogue the canvas is built from.

Anatomy of a workflow

A workflow is a graph of nodes. Each node is an instance of a catalogue API (a tool: an LLM prompt, a document extractor, a web search, a chart builder…) with its parameters filled in, connected by edges that pass one node's output to the next. The graph is stored as nodes and edges JSON in the workflow document and rendered by the canvas.

Runs

POST /microservices/workflow/start/ launches a run. Progress is pushed over the ws/workflow/{id}/nodes/ WebSocket (see Streaming & WebSockets); the same information is available by polling the node list and the outputs endpoint. Every completed run is archived as a history version.

Endpoints

Method	Path	Purpose
GET	/microservices/workflow/	List workflows
GET	/microservices/workflow/search/	Search workflows
POST	/microservices/workflow/start/	Create a workflow
GET	/microservices/workflow/{id}/	Get a workflow
PUT	/microservices/workflow/{id}/	Save a workflow
DELETE	/microservices/workflow/{id}/	Move a workflow to the trash
GET	/microservices/workflow/{id}/delete-impact/	What deleting a workflow removes
GET	/microservices/workflow/trash/	List trashed workflows
POST	/microservices/workflow/{id}/restore/	Restore a workflow from the trash
DELETE	/microservices/workflow/{id}/permanent-delete/	Delete a workflow permanently
POST	/microservices/workflow/rerun/	Run a workflow
POST	/microservices/workflow/branch-rerun/	Run from a node
POST	/microservices/workflow/stop/	Stop a run
GET	/microservices/workflow/{id}/nodes/	Node execution status
GET	/microservices/workflow/{id}/nodes/{node_execution_id}/	One node's execution record
GET	/microservices/workflow/{id}/outputs/	Persistent outputs
GET	/microservices/workflow/stats/	Run statistics
GET	/microservices/workflow/{id}/history/	Run history (versions)
GET	/microservices/workflow/{id}/history/{version}/	One archived run
GET	/microservices/workflow/{id}/history/latest/	The most recent archived run
GET	/microservices/workflow/{id}/versions/	Definition snapshots
POST	/microservices/workflow/{id}/versions/{revision}/restore/	Restore a definition snapshot
POST	/microservices/workflow/schedule/	Schedule a workflow
PATCH	/microservices/workflow/schedule/	Enable or disable a schedule
DELETE	/microservices/workflow/schedule/	Delete a schedule
GET	/microservices/workflow/scheduled-tasks/	My schedules
GET	/microservices/workflow-tags/	My tags
POST	/microservices/workflow-tags/	Create a tag
PUT	/microservices/workflow-tags/{tag_id}/	Rename or recolour a tag
DELETE	/microservices/workflow-tags/{tag_id}/	Delete a tag
GET	/microservices/workflows/{id}/tags/	Tags on a workflow
POST	/microservices/workflows/{id}/tags/attach/	Attach tags to a workflow
DELETE	/microservices/workflows/{id}/tags/{tag_id}/	Detach a tag from a workflow
GET	/microservices/workflow/{id}/collaborators/	Collaborators on a workflow
POST	/microservices/workflow/{id}/collaborators/	Add or update collaborators
PATCH	/microservices/workflow/{id}/collaborators/{user_id}/	Change a collaborator's role
DELETE	/microservices/workflow/{id}/collaborators/{user_id}/	Remove a collaborator
POST	/microservices/workflows/copy-to-user/	Share a copy with users
POST	/microservices/workflows/remove-users/	Withdraw shared copies
POST	/microservices/workflows/sync/	Push my changes to everyone I shared with
POST	/microservices/workflows/duplicate/	Duplicate a workflow
GET	/microservices/workflow-share-updates/	Share updates waiting for me
GET	/microservices/workflow-share-updates/{update_id}/	A pushed definition (for review)
POST	/microservices/workflow-share-updates/{update_id}/apply/	Accept a share update
POST	/microservices/workflow-share-updates/{update_id}/decline/	Decline a share update
GET	/microservices/documents/	Files uploaded for workflows
POST	/microservices/documents/	Upload a file for a workflow node
DELETE	/microservices/documents/	Delete a workflow file
GET	/microservices/apis/	Tool catalogue
GET	/microservices/apis/light/	Tool catalogue (names only)
POST	/microservices/apis/create/	Register a custom tool
GET	/microservices/apis/{id}/	Get a tool
PUT	/microservices/apis/{id}/	Update a tool (owner)
DELETE	/microservices/apis/{id}/	Delete a tool (owner)
POST	/microservices/apis/{id}/test/	Call a tool directly
GET	/microservices/categories/	Tool categories
POST	/microservices/categories/	Create a category
GET	/microservices/categories/{id}/	Get a category
PUT	/microservices/categories/{id}/	Update a category
DELETE	/microservices/categories/{id}/	Deactivate a category

GET /microservices/workflow/

List workflows

Paginated (10 per page by default, page_size up to 100). Includes workflows you own, copies shared with you and workflows you collaborate on; my_role says which. Filter by published-app flags and by your tags.

With with_outputs=1 the list is reduced to {id, name} rows for workflows that have at least one node saving persistent outputs (the picker in Apps).

Auth: Session token · In the app: Workflow AI → list

Query parameters

Field	Type	Required	Description
page	integer	no	Default: 1.
page_size	integer	no	Default: 10.
ordering	string	no	Model field, prefix - for descending (e.g. -updated_at, name). Default: "-created_at".
available_as_app	boolean	no
csv_dashbord	boolean	no
chatbot_app	boolean	no
tag_ids	string	no	Comma-separated tag uuids (your tags).
with_outputs	boolean	no

Response 200 — A page.

Field	Type	Description
count	integer
next	string (uri), nullable
previous	string (uri), nullable
results	object[]
results[].id	string (uuid)
results[].user	string	Owner username.
results[].name	string
results[].subtitle	string, nullable
results[].description	string, nullable
results[].summary	string, nullable
results[].json_spec	object	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.
results[].json_spec.name	string
results[].json_spec.version	string
results[].json_spec.entry	string[]	Node ids that start the run.
results[].json_spec.nodes	object[]
results[].json_spec.nodes[].id	string	Unique within the workflow (the app uses step1, step2, …).
results[].json_spec.nodes[].kind	string	Tool name from the catalogue.
results[].json_spec.nodes[].name	string	Display label (max 100 chars).
results[].json_spec.nodes[].params	object	Tool parameters, per the tool's parameters schema.
results[].json_spec.nodes[].next	string[]	Node ids to run after this one.
results[].json_spec.nodes[].requires	object
results[].json_spec.nodes[].requires.wait_for	string[]
results[].json_spec.nodes[].save_output	boolean	Keep this node's output as a persistent Output (Apps → outputs).
results[].json_spec.nodes[].export_output	boolean	Include the output in exports.
results[].json_spec.edges	object[]	Canvas edges (kept for the editor; execution follows next).
results[].instructions	any[]	App instructions shown to users of the published app.
results[].status	string ("IDLE", "PENDING", "RUNNING", "COMPLETED", "FAILED", "STOPPED")
results[].available_as_app	boolean	Published in Apps.
results[].csv_dashbord	boolean	Published as a CSV dashboard app.
results[].run_only	boolean
results[].chatbot_app	boolean	Published as a chatbot app.
results[].webhook_id	string	Workflow-level webhook id (pair with webhook_secret from the detail view).
results[].successful_run_count	integer
results[].created_at	string (date-time)
results[].updated_at	string (date-time)
results[].content_revision	integer	Optimistic-concurrency token for saves.
results[].my_role	string ("owner", "editor", "viewer", null), nullable
results[].owner	object, nullable
results[].owner.id	integer
results[].owner.username	string
results[].owner.email	string
results[].last_edited_by	object, nullable
results[].last_edited_by.id	integer
results[].last_edited_by.username	string
results[].last_edited_at	string (date-time), nullable

Response 400 — Bad tag_ids.

{
  "error": "path is required"
}

Example

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

GET /microservices/workflow/search/

Search workflows

Same result shape as the list, filtered by search (name/description), status, app flags and tags. include_tags=true adds each workflow's tags.

Auth: Session token · In the app: Workflow AI → search box

Query parameters

Field	Type	Required	Description
search	string	no
status	string ("IDLE", "PENDING", "RUNNING", "COMPLETED", "FAILED", "STOPPED")	no
ordering	string	no	Default: "-updated_at".
available_as_app	boolean	no
csv_dashbord	boolean	no
chatbot_app	boolean	no
tag_ids	string	no
include_tags	boolean	no
page	integer	no
page_size	integer	no

Response 200 — A page.

Field	Type	Description
count	integer
next	string, nullable
previous	string, nullable
results	object[]
results[].id	string (uuid)
results[].user	string	Owner username.
results[].name	string
results[].subtitle	string, nullable
results[].description	string, nullable
results[].summary	string, nullable
results[].json_spec	object	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.
results[].json_spec.name	string
results[].json_spec.version	string
results[].json_spec.entry	string[]	Node ids that start the run.
results[].json_spec.nodes	object[]
results[].json_spec.nodes[].id	string	Unique within the workflow (the app uses step1, step2, …).
results[].json_spec.nodes[].kind	string	Tool name from the catalogue.
results[].json_spec.nodes[].name	string	Display label (max 100 chars).
results[].json_spec.nodes[].params	object	Tool parameters, per the tool's parameters schema.
results[].json_spec.nodes[].next	string[]	Node ids to run after this one.
results[].json_spec.nodes[].requires	object
results[].json_spec.nodes[].requires.wait_for	string[]
results[].json_spec.nodes[].save_output	boolean	Keep this node's output as a persistent Output (Apps → outputs).
results[].json_spec.nodes[].export_output	boolean	Include the output in exports.
results[].json_spec.edges	object[]	Canvas edges (kept for the editor; execution follows next).
results[].instructions	any[]	App instructions shown to users of the published app.
results[].status	string ("IDLE", "PENDING", "RUNNING", "COMPLETED", "FAILED", "STOPPED")
results[].available_as_app	boolean	Published in Apps.
results[].csv_dashbord	boolean	Published as a CSV dashboard app.
results[].run_only	boolean
results[].chatbot_app	boolean	Published as a chatbot app.
results[].webhook_id	string	Workflow-level webhook id (pair with webhook_secret from the detail view).
results[].successful_run_count	integer
results[].created_at	string (date-time)
results[].updated_at	string (date-time)
results[].content_revision	integer	Optimistic-concurrency token for saves.
results[].my_role	string ("owner", "editor", "viewer", null), nullable
results[].owner	object, nullable
results[].owner.id	integer
results[].owner.username	string
results[].owner.email	string
results[].last_edited_by	object, nullable
results[].last_edited_by.id	integer
results[].last_edited_by.username	string
results[].last_edited_at	string (date-time), nullable

Example

curl -X GET "https://api.example.com/microservices/workflow/search/?search=digest" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /microservices/workflow/start/

Create a workflow

Saves a new workflow from a spec (status IDLE) and creates one execution row per node. Despite its name this does not run anything — call POST /microservices/workflow/rerun/ to run it.

If json.name is empty or "Untitled workflow" a name is generated.

Auth: Session token · In the app: Workflow AI → Save (new canvas)

Request body (application/json)

Field	Type	Required	Description
json	object	yes	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.
json.name	string	no
json.version	string	no
json.entry	string[]	no	Node ids that start the run.
json.nodes	object[]	yes
json.nodes[].id	string	yes	Unique within the workflow (the app uses step1, step2, …).
json.nodes[].kind	string	yes	Tool name from the catalogue.
json.nodes[].name	string	no	Display label (max 100 chars).
json.nodes[].params	object	no	Tool parameters, per the tool's parameters schema.
json.nodes[].next	string[]	no	Node ids to run after this one.
json.nodes[].requires	object	no
json.nodes[].requires.wait_for	string[]	no
json.nodes[].save_output	boolean	no	Keep this node's output as a persistent Output (Apps → outputs).
json.nodes[].export_output	boolean	no	Include the output in exports.
json.edges	object[]	no	Canvas edges (kept for the editor; execution follows next).
vueflow_json	object	no	Canvas layout (optional for API clients).
description	string	no
subtitle	string	no
summary	string	no
instructions	any[]	no
available_as_app	boolean	no	Default: false.
csv_dashbord	boolean	no	Default: false.
chatbot_app	boolean	no	Default: false.

{
  "json": {
    "name": "Weekly competitor digest",
    "version": "1.0",
    "entry": [
      "step1"
    ],
    "nodes": [
      {
        "id": "step1",
        "kind": "web_search",
        "params": {
          "query": "competitor announcements this week"
        },
        "next": [
          "step2"
        ]
      },
      {
        "id": "step2",
        "kind": "llm_prompt",
        "params": {
          "prompt": "Summarise in 5 bullets: {{_output.step1.results}}"
        },
        "next": []
      }
    ]
  },
  "description": "Searches the web and summarises"
}

Response 201 — Created.

Field	Type	Description
workflow_id	string (uuid)

{
  "workflow_id": "7d4c2b1a-0e9f-4a3b-8c7d-6e5f4a3b2c1d"
}

Response 400 — json is not an object or json.nodes is not a list.

{
  "username": [
    "A user with that username already exists."
  ]
}

Example

curl -X POST "https://api.example.com/microservices/workflow/start/" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"json":{"name":"Weekly competitor digest","version":"1.0","entry":["step1"],"nodes":[{"id":"step1","kind":"web_search","params":{"query":"competitor announcements this week"},"next":["step2"]},{"id":"step2","kind":"llm_prompt","params":{"prompt":"Summarise in 5 bullets: {{_output.step1.results}}"},"next":[]}]},"description":"Searches the web and summarises"}'

GET /microservices/workflow/{id}/

Get a workflow

Full definition with node execution rows and access info. Pass ?webhook=true to look the workflow up by its webhook_id instead of its uuid.

Auth: Session token · In the app: Opening a canvas

Path parameters

Field	Type	Required	Description
id	string	yes

Query parameters

Field	Type	Required	Description
webhook	boolean	no	true = id is a webhook_id.

Response 200 — The workflow.

Field	Type	Description
id	string (uuid)
user	string	Owner username.
name	string
subtitle	string, nullable
description	string, nullable
summary	string, nullable
json_spec	object	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.
json_spec.name	string
json_spec.version	string
json_spec.entry	string[]	Node ids that start the run.
json_spec.nodes	object[]
json_spec.nodes[].id	string	Unique within the workflow (the app uses step1, step2, …).
json_spec.nodes[].kind	string	Tool name from the catalogue.
json_spec.nodes[].name	string	Display label (max 100 chars).
json_spec.nodes[].params	object	Tool parameters, per the tool's parameters schema.
json_spec.nodes[].next	string[]	Node ids to run after this one.
json_spec.nodes[].requires	object
json_spec.nodes[].requires.wait_for	string[]
json_spec.nodes[].save_output	boolean	Keep this node's output as a persistent Output (Apps → outputs).
json_spec.nodes[].export_output	boolean	Include the output in exports.
json_spec.edges	object[]	Canvas edges (kept for the editor; execution follows next).
instructions	any[]	App instructions shown to users of the published app.
status	string ("IDLE", "PENDING", "RUNNING", "COMPLETED", "FAILED", "STOPPED")
available_as_app	boolean	Published in Apps.
csv_dashbord	boolean	Published as a CSV dashboard app.
run_only	boolean
chatbot_app	boolean	Published as a chatbot app.
webhook_id	string	Workflow-level webhook id (pair with webhook_secret from the detail view).
successful_run_count	integer
created_at	string (date-time)
updated_at	string (date-time)
content_revision	integer	Optimistic-concurrency token for saves.
my_role	string ("owner", "editor", "viewer", null), nullable
owner	object, nullable
owner.id	integer
owner.username	string
owner.email	string
last_edited_by	object, nullable
last_edited_by.id	integer
last_edited_by.username	string
last_edited_at	string (date-time), nullable
vueflow_json	object	Canvas layout (positions, edges) for the editor.
webhook_secret	string	Secret for the workflow-level webhook.
nodes	object[]
nodes[].id	string (uuid)	Node execution id (distinct from the spec's node_id).
nodes[].workflow	string (uuid)
nodes[].name	string, nullable
nodes[].node_id	string	The node's id in the spec.
nodes[].kind	string
nodes[].params	object
nodes[].status	string ("PENDING", "RUNNING", "COMPLETED", "FAILED", "SKIPPED", "STOPPED", "WAITING")
nodes[].input	object
nodes[].output	object, nullable	The tool's result once the node completes.
nodes[].next	object|array, nullable
nodes[].attempt_count	integer
nodes[].save_output	boolean
nodes[].export_output	boolean
nodes[].started_at	string (date-time), nullable
nodes[].finished_at	string (date-time), nullable
nodes[].batch_id	string, nullable
nodes[].batch_total	integer, nullable
nodes[].batch_completed	integer
nodes[].is_batch_processor	boolean
nodes[].progress_percentage	integer, nullable	For batch nodes only.
is_owner	boolean
can_edit	boolean
collaborators	object[]	Present for the owner only.
collaborators[].user	object
collaborators[].user.id	integer
collaborators[].user.username	string
collaborators[].user.email	string
collaborators[].role	string ("editor", "viewer")
collaborators[].role_label	string
collaborators[].created_at	string (date-time)
sharer	object	Present on a copy you received — who shared it.
only_view_in_apps	boolean	On a received copy — you may only run it from Apps.
sharees	object[]	Present on your own workflow — who received copies.
sharees[].id	integer
sharees[].username	string
sharees[].email	string
sharees[].only_view_in_apps	boolean

Response 404 — Not found or no access.

{
  "detail": "Authentication credentials were not provided."
}

Example

curl -X GET "https://api.example.com/microservices/workflow/7d4c2b1a-0e9f-4a3b-8c7d-6e5f4a3b2c1d/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

PUT /microservices/workflow/{id}/

Save a workflow

Replaces the definition and metadata (editors and owners). Send expected_content_revision (the value you last read) to detect concurrent edits: on mismatch the response is 409 with the current revision, who saved it, and the current workflow. Saving while a run is in flight is allowed and flagged with warning: "running". Collaborators on the canvas receive the new definition over the nodes WebSocket.

Auth: Session token · In the app: Workflow AI → Save

Path parameters

Field	Type	Required	Description
id	string (uuid)	yes

Request body (application/json)

Field	Type	Required	Description
name	string	yes
subtitle	string	no
description	string	no
summary	string	no
json_spec	object	yes	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.
json_spec.name	string	no
json_spec.version	string	no
json_spec.entry	string[]	no	Node ids that start the run.
json_spec.nodes	object[]	yes
json_spec.nodes[].id	string	yes	Unique within the workflow (the app uses step1, step2, …).
json_spec.nodes[].kind	string	yes	Tool name from the catalogue.
json_spec.nodes[].name	string	no	Display label (max 100 chars).
json_spec.nodes[].params	object	no	Tool parameters, per the tool's parameters schema.
json_spec.nodes[].next	string[]	no	Node ids to run after this one.
json_spec.nodes[].requires	object	no
json_spec.nodes[].requires.wait_for	string[]	no
json_spec.nodes[].save_output	boolean	no	Keep this node's output as a persistent Output (Apps → outputs).
json_spec.nodes[].export_output	boolean	no	Include the output in exports.
json_spec.edges	object[]	no	Canvas edges (kept for the editor; execution follows next).
vueflow_json	object	no
instructions	any[]	no
available_as_app	boolean	no
csv_dashbord	boolean	no
run_only	boolean	no
chatbot_app	boolean	no
expected_content_revision	integer	no	Revision you are editing on top of.

{
  "name": "Weekly competitor digest",
  "json_spec": {
    "name": "Weekly competitor digest",
    "version": "1.0",
    "entry": [
      "step1"
    ],
    "nodes": []
  },
  "available_as_app": true,
  "expected_content_revision": 14
}

Response 200 — Saved.

Field	Type	Description
message	string
content_revision	integer
warning	string	running when a run was in flight.

{
  "message": "Workflow updated",
  "content_revision": 15
}

Response 400 — Validation errors.

{
  "username": [
    "A user with that username already exists."
  ]
}

Response 409 — Someone saved a newer revision.

{
  "detail": "Workflow save conflict.",
  "content_revision": 16,
  "last_edited_by": {
    "id": 57,
    "username": "omar"
  },
  "last_edited_at": "2026-09-22T07:55:00Z",
  "workflow": {
    "id": "7d4c2b1a-…",
    "name": "Weekly competitor digest"
  }
}

Example

curl -X PUT "https://api.example.com/microservices/workflow/<id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Weekly competitor digest","json_spec":{"name":"Weekly competitor digest","version":"1.0","entry":["step1"],"nodes":[]},"available_as_app":true,"expected_content_revision":14}'

DELETE /microservices/workflow/{id}/

Move a workflow to the trash

Owner only. Soft delete with 30-day retention (WORKFLOW_TRASH_RETENTION_DAYS); schedules and webhooks stop firing. Apps shared off this workflow go with it; independent copies given to others are untouched.

Auth: Session token · In the app: Workflow AI → Delete

Path parameters

Field	Type	Required	Description
id	string (uuid)	yes

Response 200 — Trashed.

Field	Type	Description
message	string
status	string ("trashed")
id	string
deleted_at	string (date-time)
purge_at	string (date-time)
side_effects	object

Response 404 — Not found or not the owner.

{
  "detail": "Authentication credentials were not provided."
}

Example

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

GET /microservices/workflow/{id}/delete-impact/

What deleting a workflow removes

Auth: Session token · In the app: Delete confirmation dialog

Path parameters

Field	Type	Required	Description
id	string (uuid)	yes

Response 200 — Impact report (counts are null when the run store is unreachable).

Field	Type	Description
workflow	object
workflow.id	string
workflow.name	string
workflow.is_trashed	boolean
artifacts	object
artifacts.count	integer
artifacts.bytes	integer
artifacts.sample	string[]
charts	object
charts.count	integer
charts.sample	string[]
dashboards	object
dashboards.emptied	object[]
chat_sessions	object
chat_sessions.count	integer
chat_sessions.sample	string[]
run_history	object
run_history.versions	integer, nullable
dashboard_documents	object
dashboard_documents.count	integer, nullable
spec_revisions	integer
schedules	string[]
queued_webhook_runs	integer
node_runs	integer
extractor_tables_deleted	object[]

Example

curl -X GET "https://api.example.com/microservices/workflow/<id>/delete-impact/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /microservices/workflow/trash/

List trashed workflows

Auth: Session token

Response 200 — Trashed workflows with deleted_at and purge_at.

Example

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

POST /microservices/workflow/{id}/restore/

Restore a workflow from the trash

Auth: Session token

Path parameters

Field	Type	Required	Description
id	string (uuid)	yes

Response 200 — Restored.

Field	Type	Description
status	string ("restored")
id	string

Response 404 — No such trashed workflow.

{
  "detail": "Authentication credentials were not provided."
}

Example

curl -X POST "https://api.example.com/microservices/workflow/<id>/restore/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

DELETE /microservices/workflow/{id}/permanent-delete/

Delete a workflow permanently

Destroys the workflow and everything it produced (run history, outputs, artifacts, charts, extracted tables it created). Cannot be undone.

Auth: Session token

Path parameters

Field	Type	Required	Description
id	string (uuid)	yes

Response 200 — Purged.

Field	Type	Description
status	string ("permanently_deleted")
id	string
deleted	object	Per-resource counts.

Response 404 — Not your workflow.

{
  "detail": "Authentication credentials were not provided."
}

Example

curl -X DELETE "https://api.example.com/microservices/workflow/<id>/permanent-delete/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /microservices/workflow/rerun/

Run a workflow

Starts a full run: every node is reset and the entry nodes are dispatched. Returns immediately with the run's history version; follow progress on the ws/workflow/{id}/nodes/ WebSocket or by polling GET /microservices/workflow/{id}/nodes/.

Editors and owners may run. Starting a run while one is in flight resets it — use the webhook trigger if calls may overlap; it queues them.

Auth: Session token · In the app: Workflow AI → Run

Request body (application/json)

Field	Type	Required	Description
workflow_id	string (uuid)	yes
webhook_payload	object	no	Optional input merged into the entry nodes' params as _webhook_payload.

{
  "workflow_id": "7d4c2b1a-0e9f-4a3b-8c7d-6e5f4a3b2c1d"
}

Response 200 — Started.

Field	Type	Description
message	string
version	integer	History version reserved for this run.

{
  "message": "Workflow has been re-run.",
  "version": 13
}

Response 404 — Not found or no edit access.

{
  "detail": "Authentication credentials were not provided."
}

Example

curl -X POST "https://api.example.com/microservices/workflow/rerun/" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workflow_id":"7d4c2b1a-0e9f-4a3b-8c7d-6e5f4a3b2c1d"}'

POST /microservices/workflow/branch-rerun/

Run from a node

Re-runs one node (run_to_the_end: false) or the branch from that node to the end, reusing upstream outputs. Parameter references to earlier nodes are resolved from the last run.

Auth: Session token · In the app: Node menu → Run from here / Run this node

Request body (application/json)

Field	Type	Required	Description
workflow_id	string (uuid)	yes
start_node_id	string	yes	Spec node id.
run_to_the_end	boolean	no	Default: false.
save_outputs	boolean	no	Honour save_output on newly created node rows. Default: false.
webhook_payload	object	no

{
  "workflow_id": "7d4c2b1a-0e9f-4a3b-8c7d-6e5f4a3b2c1d",
  "start_node_id": "step2",
  "run_to_the_end": true
}

Response 200 — Started.

Field	Type	Description
workflow_id	string
start_node_id	string
run_to_the_end	boolean
nodes_in_branch	integer
save_outputs	boolean
message	string

Response 400 — Missing ids, unknown node, or the branch is invalid.

{
  "error": "path is required"
}

Example

curl -X POST "https://api.example.com/microservices/workflow/branch-rerun/" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workflow_id":"7d4c2b1a-0e9f-4a3b-8c7d-6e5f4a3b2c1d","start_node_id":"step2","run_to_the_end":true}'

POST /microservices/workflow/stop/

Stop a run

Auth: Session token · In the app: Workflow AI → Stop

Request body (application/json)

Field	Type	Required	Description
workflow_id	string (uuid)	yes

Response 200 — Stopped.

Field	Type	Description
workflow_id	string
status	string ("STOPPED")
nodes_stopped	integer
message	string

Response 400 — Not running.

{
  "error": "Workflow cannot be stopped. Current status: COMPLETED"
}

Example

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

GET /microservices/workflow/{id}/nodes/

Node execution status

One row per node with status, timing and output from the current or last run. The same payload the nodes WebSocket pushes.

Auth: Session token · In the app: Canvas node badges (fallback polling)

Path parameters

Field	Type	Required	Description
id	string (uuid)	yes

Response 200 — Nodes.

Array of:

Field	Type	Description
id	string (uuid)	Node execution id (distinct from the spec's node_id).
workflow	string (uuid)
name	string, nullable
node_id	string	The node's id in the spec.
kind	string
params	object
status	string ("PENDING", "RUNNING", "COMPLETED", "FAILED", "SKIPPED", "STOPPED", "WAITING")
input	object
output	object, nullable	The tool's result once the node completes.
next	object|array, nullable
attempt_count	integer
save_output	boolean
export_output	boolean
started_at	string (date-time), nullable
finished_at	string (date-time), nullable
batch_id	string, nullable
batch_total	integer, nullable
batch_completed	integer
is_batch_processor	boolean
progress_percentage	integer, nullable	For batch nodes only.

Example

curl -X GET "https://api.example.com/microservices/workflow/<id>/nodes/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /microservices/workflow/{id}/nodes/{node_execution_id}/

One node's execution record

Auth: Session token

Path parameters

Field	Type	Required	Description
id	string (uuid)	yes
node_execution_id	string (uuid)	yes	The execution row id (not the spec node_id).

Response 200 — Node.

Field	Type	Description
id	string (uuid)	Node execution id (distinct from the spec's node_id).
workflow	string (uuid)
name	string, nullable
node_id	string	The node's id in the spec.
kind	string
params	object
status	string ("PENDING", "RUNNING", "COMPLETED", "FAILED", "SKIPPED", "STOPPED", "WAITING")
input	object
output	object, nullable	The tool's result once the node completes.
next	object|array, nullable
attempt_count	integer
save_output	boolean
export_output	boolean
started_at	string (date-time), nullable
finished_at	string (date-time), nullable
batch_id	string, nullable
batch_total	integer, nullable
batch_completed	integer
is_batch_processor	boolean
progress_percentage	integer, nullable	For batch nodes only.

{
  "id": "0c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "workflow": "7d4c2b1a-0e9f-4a3b-8c7d-6e5f4a3b2c1d",
  "name": "Summarise",
  "node_id": "step2",
  "kind": "llm_prompt",
  "params": {
    "prompt": "Summarise these results in 5 bullets: {{_output.step1.results}}"
  },
  "status": "COMPLETED",
  "input": {},
  "output": {
    "response": "- Acme launched …"
  },
  "next": [
    "step3"
  ],
  "attempt_count": 1,
  "save_output": false,
  "export_output": false,
  "started_at": "2026-09-21T08:00:03Z",
  "finished_at": "2026-09-21T08:00:09Z",
  "batch_id": null,
  "batch_total": null,
  "batch_completed": 0,
  "is_batch_processor": false,
  "progress_percentage": null
}

Example

curl -X GET "https://api.example.com/microservices/workflow/<id>/nodes/<node_execution_id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /microservices/workflow/{id}/outputs/

Persistent outputs

Outputs of nodes flagged save_output, kept across runs. Filter by date and order by kind, status, started_at, finished_at.

Auth: Session token · In the app: Apps → outputs panel

Path parameters

Field	Type	Required	Description
id	string (uuid)	yes

Query parameters

Field	Type	Required	Description
start	string (date)	no
end	string (date)	no
ordering	string	no	Default: "-started_at".

Response 200 — Outputs.

Array of:

Field	Type	Description
id	integer
workflow	string
kind	string
params	object
output	object, nullable
status	string
started_at	string (date-time), nullable
finished_at	string (date-time), nullable

Response 400 — Bad date.

{
  "detail": "Authentication credentials were not provided."
}

Example

curl -X GET "https://api.example.com/microservices/workflow/<id>/outputs/?start=2026-09-01" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /microservices/workflow/stats/

Run statistics

Auth: Session token · In the app: Workflow AI header counters

Query parameters

Field	Type	Required	Description
breakdown	boolean	no	Add a per-workflow list.

Response 200 — Totals.

Field	Type	Description
total_successful_runs	integer
workflow_count	integer
workflows	object[]
workflows[].id	string
workflows[].name	string
workflows[].successful_run_count	integer

{
  "total_successful_runs": 128,
  "workflow_count": 9
}

Example

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

GET /microservices/workflow/{id}/history/

Run history (versions)

Every archived run, newest first. Each run is a snapshot of the spec plus node results.

Auth: Session token · In the app: Workflow AI → History

Path parameters

Field	Type	Required	Description
id	string (uuid)	yes

Response 200 — Versions.

Field	Type	Description
workflow_id	string
workflow_name	string
total_versions	integer
versions	object[]
versions[].version	integer
versions[].version_label	string
versions[].created_at	string (date-time)
versions[].status	string

Response 503 — The run store is unavailable.

{
  "error": "path is required"
}

Example

curl -X GET "https://api.example.com/microservices/workflow/<id>/history/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /microservices/workflow/{id}/history/{version}/

One archived run

Auth: Session token · In the app: Workflow AI → History → open

Path parameters

Field	Type	Required	Description
id	string (uuid)	yes
version	integer	yes

Response 200 — The run document.

Field	Type	Description
_id	string
workflow_id	string
version	integer
version_label	string
workflow_name	string
workflow_description	string
workflow_status	string
user_id	string
username	string
json_spec	object	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.
json_spec.name	string
json_spec.version	string
json_spec.entry	string[]	Node ids that start the run.
json_spec.nodes	object[]
json_spec.nodes[].id	string	Unique within the workflow (the app uses step1, step2, …).
json_spec.nodes[].kind	string	Tool name from the catalogue.
json_spec.nodes[].name	string	Display label (max 100 chars).
json_spec.nodes[].params	object	Tool parameters, per the tool's parameters schema.
json_spec.nodes[].next	string[]	Node ids to run after this one.
json_spec.nodes[].requires	object
json_spec.nodes[].requires.wait_for	string[]
json_spec.nodes[].save_output	boolean	Keep this node's output as a persistent Output (Apps → outputs).
json_spec.nodes[].export_output	boolean	Include the output in exports.
json_spec.edges	object[]	Canvas edges (kept for the editor; execution follows next).
nodes	object[]
nodes[].id	string (uuid)	Node execution id (distinct from the spec's node_id).
nodes[].workflow	string (uuid)
nodes[].name	string, nullable
nodes[].node_id	string	The node's id in the spec.
nodes[].kind	string
nodes[].params	object
nodes[].status	string ("PENDING", "RUNNING", "COMPLETED", "FAILED", "SKIPPED", "STOPPED", "WAITING")
nodes[].input	object
nodes[].output	object, nullable	The tool's result once the node completes.
nodes[].next	object|array, nullable
nodes[].attempt_count	integer
nodes[].save_output	boolean
nodes[].export_output	boolean
nodes[].started_at	string (date-time), nullable
nodes[].finished_at	string (date-time), nullable
nodes[].batch_id	string, nullable
nodes[].batch_total	integer, nullable
nodes[].batch_completed	integer
nodes[].is_batch_processor	boolean
nodes[].progress_percentage	integer, nullable	For batch nodes only.
created_at	string (date-time)
workflow_created_at	string, nullable
workflow_summary	string
workflow_vueflow_json	object

Response 400 — version is not an integer.

Response 404 — No such version.

{
  "error": "path is required"
}

Example

curl -X GET "https://api.example.com/microservices/workflow/<id>/history/13/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /microservices/workflow/{id}/history/latest/

The most recent archived run

Auth: Session token

Path parameters

Field	Type	Required	Description
id	string (uuid)	yes

Response 200 — The run document (same shape as a version).

Response 404 — No runs yet.

{
  "error": "path is required"
}

Example

curl -X GET "https://api.example.com/microservices/workflow/<id>/history/latest/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /microservices/workflow/{id}/versions/

Definition snapshots

Snapshots taken before anything overwrote the definition (an assistant edit, an applied share update, a restore). Distinct from run history.

Auth: Session token · In the app: Workflow AI → Versions

Path parameters

Field	Type	Required	Description
id	string (uuid)	yes

Response 200 — Snapshots, newest first.

Array of:

Field	Type	Description
revision	integer
source	string
source_label	string
note	string
created_at	string (date-time)
node_count	integer

[
  {
    "revision": 6,
    "source": "agent",
    "source_label": "Assistant edit",
    "note": "Before applying assistant changes",
    "created_at": "2026-09-20T10:00:00Z",
    "node_count": 3
  }
]

Example

curl -X GET "https://api.example.com/microservices/workflow/<id>/versions/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /microservices/workflow/{id}/versions/{revision}/restore/

Restore a definition snapshot

Snapshots the current definition first, so a restore is itself undoable.

Auth: Session token

Path parameters

Field	Type	Required	Description
id	string (uuid)	yes
revision	integer	yes

Response 200 — Restored.

Field	Type	Description
status	string ("restored")
workflow_id	string
restored_revision	integer
content_revision	integer

Example

curl -X POST "https://api.example.com/microservices/workflow/<id>/versions/<revision>/restore/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /microservices/workflow/schedule/

Schedule a workflow

Owner only. Creates a periodic task that runs the workflow:

type	Extra fields
minutes / hours / days	every (integer)
clocked	clock_time — YYYY-MM-DD HH:MM:SS in the server's timezone; runs once
cron	minute, hour, day_of_week, day_of_month, month_of_year (crontab fields, default *)

Auth: Session token · In the app: Workflow AI → Schedule

Request body (application/json)

Field	Type	Required	Description
workflow_id	string (uuid)	yes
type	string ("minutes", "hours", "days", "clocked", "cron")	yes
every	integer	no
clock_time	string	no
minute	string	no	Default: "*".
hour	string	no	Default: "*".
day_of_week	string	no	Default: "*".
day_of_month	string	no	Default: "*".
month_of_year	string	no	Default: "*".

{
  "workflow_id": "7d4c2b1a-0e9f-4a3b-8c7d-6e5f4a3b2c1d",
  "type": "cron",
  "minute": "0",
  "hour": "8",
  "day_of_week": "1"
}

Response 201 — Scheduled.

Field	Type	Description
message	string

{
  "message": "Workflow scheduled successfully"
}

Response 400 — Missing fields or invalid type.

{
  "error": "path is required"
}

Example

curl -X POST "https://api.example.com/microservices/workflow/schedule/" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workflow_id":"7d4c2b1a-0e9f-4a3b-8c7d-6e5f4a3b2c1d","type":"cron","minute":"0","hour":"8","day_of_week":"1"}'

PATCH /microservices/workflow/schedule/

Enable or disable a schedule

Auth: Session token

Request body (application/json)

Field	Type	Required	Description
task_id	integer	yes
enabled	boolean	yes

Response 200 — Updated.

Field	Type	Description
message	string

{
  "message": "OK"
}

Response 403 — Not your schedule.

{
  "error": "path is required"
}

Response 404 — Unknown task.

{
  "error": "path is required"
}

Example

curl -X PATCH "https://api.example.com/microservices/workflow/schedule/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

DELETE /microservices/workflow/schedule/

Delete a schedule

Auth: Session token

Request body (application/json)

Field	Type	Required	Description
task_id	integer	yes

Response 200 — Deleted.

Field	Type	Description
message	string

{
  "message": "OK"
}

Response 403 — Not your schedule.

Response 404 — Unknown task.

Example

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

GET /microservices/workflow/scheduled-tasks/

My schedules

Auth: Session token · In the app: Workflow AI → Schedules

Response 200 — Periodic tasks for workflows you own.

Array of:

Field	Type	Description
id	integer
name	string
enabled	boolean
last_run_at	string (date-time), nullable
total_run_count	integer
args	any[]	[workflow_id, user_context].
interval	integer, nullable
crontab	integer, nullable
clocked	integer, nullable
one_off	boolean
start_time	string (date-time), nullable
expires	string (date-time), nullable

Example

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

GET /microservices/workflow-tags/

My tags

Auth: Session token · In the app: Workflow AI → tag filter

Response 200 — Tags.

Array of:

Field	Type	Description
id	string (uuid)
name	string
color	string, nullable
created_at	string (date-time)
updated_at	string (date-time)

Example

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

POST /microservices/workflow-tags/

Create a tag

Auth: Session token

Request body (application/json)

Field	Type	Required	Description
name	string	yes
color	string	no	Hex colour.

{
  "name": "finance",
  "color": "#12bcc2"
}

Response 201 — Created.

Field	Type	Description
id	string (uuid)
name	string
color	string, nullable
created_at	string (date-time)
updated_at	string (date-time)

{
  "id": "3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
  "name": "finance",
  "color": "#12bcc2",
  "created_at": "2026-05-01T08:00:00Z",
  "updated_at": "2026-05-01T08:00:00Z"
}

Response 400 — Duplicate name or validation error.

{
  "name": [
    "A tag with this name already exists."
  ]
}

Example

curl -X POST "https://api.example.com/microservices/workflow-tags/" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"finance","color":"#12bcc2"}'

PUT /microservices/workflow-tags/{tag_id}/

Rename or recolour a tag

Auth: Session token

Path parameters

Field	Type	Required	Description
tag_id	string (uuid)	yes

Request body (application/json)

Field	Type	Required	Description
name	string	yes
color	string	no

Response 200 — Updated.

Field	Type	Description
id	string (uuid)
name	string
color	string, nullable
created_at	string (date-time)
updated_at	string (date-time)

{
  "id": "3a2b1c0d-9e8f-4a7b-8c6d-5e4f3a2b1c0d",
  "name": "finance",
  "color": "#12bcc2",
  "created_at": "2026-05-01T08:00:00Z",
  "updated_at": "2026-05-01T08:00:00Z"
}

Response 404 — Not your tag.

{
  "error": "path is required"
}

Example

curl -X PUT "https://api.example.com/microservices/workflow-tags/<tag_id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

DELETE /microservices/workflow-tags/{tag_id}/

Delete a tag

Auth: Session token

Path parameters

Field	Type	Required	Description
tag_id	string (uuid)	yes

Response 204 — Deleted (detached from every workflow).

Response 404 — Not your tag.

Example

curl -X DELETE "https://api.example.com/microservices/workflow-tags/<tag_id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /microservices/workflows/{id}/tags/

Tags on a workflow

Tags are personal — you only see your own tags on a workflow, even a shared one.

Auth: Session token

Path parameters

Field	Type	Required	Description
id	string (uuid)	yes

Response 200 — Tags.

Array of:

Field	Type	Description
id	string (uuid)
name	string
color	string, nullable
created_at	string (date-time)
updated_at	string (date-time)

Example

curl -X GET "https://api.example.com/microservices/workflows/<id>/tags/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /microservices/workflows/{id}/tags/attach/

Attach tags to a workflow

Auth: Session token

Path parameters

Field	Type	Required	Description
id	string (uuid)	yes

Request body (application/json)

Field	Type	Required	Description
tag_ids	string (uuid)[]	yes

Response 200 — Newly attached tags (already-attached ones are omitted).

Field	Type	Description
attached	object[]
attached[].id	string (uuid)
attached[].name	string
attached[].color	string, nullable
attached[].created_at	string (date-time)
attached[].updated_at	string (date-time)
errors	string[]

Example

curl -X POST "https://api.example.com/microservices/workflows/<id>/tags/attach/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

DELETE /microservices/workflows/{id}/tags/{tag_id}/

Detach a tag from a workflow

Auth: Session token

Path parameters

Field	Type	Required	Description
id	string (uuid)	yes
tag_id	string (uuid)	yes

Response 204 — Detached.

Response 404 — Tag not attached / not yours.

{
  "error": "path is required"
}

Example

curl -X DELETE "https://api.example.com/microservices/workflows/<id>/tags/<tag_id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /microservices/workflow/{id}/collaborators/

Collaborators on a workflow

People who edit or view the same workflow (as opposed to receiving a copy). Anyone with view access may read the list.

Auth: Session token · In the app: Workflow AI → Share → Collaborators

Path parameters

Field	Type	Required	Description
id	string (uuid)	yes

Response 200 — Collaborators.

Array of:

Field	Type	Description
user	object
user.id	integer
user.username	string
user.email	string
role	string ("editor", "viewer")
role_label	string
created_at	string (date-time)

Example

curl -X GET "https://api.example.com/microservices/workflow/<id>/collaborators/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /microservices/workflow/{id}/collaborators/

Add or update collaborators

Owner only. Editors get write access to the workflow's extracted tables and the files it references are shared with them where possible; files_not_shared lists what could not be shared.

Auth: Session token

Path parameters

Field	Type	Required	Description
id	string (uuid)	yes

Request body (application/json)

Field	Type	Required	Description
users	object[]	yes
users[].user_id	integer	no
users[].email	string	no
users[].username	string	no
users[].role	string ("editor", "viewer")	no	Default: "editor".

{
  "users": [
    {
      "email": "omar@acme.com",
      "role": "editor"
    },
    {
      "username": "sara",
      "role": "viewer"
    }
  ]
}

Response 200 — Result per user.

Field	Type	Description
workflow_id	string
collaborators	any[]

Response 400 — Bad users, unknown user, owner in the list, or bad role.

{
  "error": "path is required"
}

Example

curl -X POST "https://api.example.com/microservices/workflow/<id>/collaborators/" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"users":[{"email":"omar@acme.com","role":"editor"},{"username":"sara","role":"viewer"}]}'

PATCH /microservices/workflow/{id}/collaborators/{user_id}/

Change a collaborator's role

Auth: Session token

Path parameters

Field	Type	Required	Description
id	string (uuid)	yes
user_id	integer	yes

Request body (application/json)

Field	Type	Required	Description
role	string ("editor", "viewer")	yes

Response 200 — Updated seat.

Field	Type	Description
user	object
user.id	integer
user.username	string
user.email	string
role	string ("editor", "viewer")
role_label	string
created_at	string (date-time)

{
  "user": {
    "id": 57,
    "username": "omar",
    "email": "omar@acme.com"
  },
  "role": "editor",
  "role_label": "Editor",
  "created_at": "2026-09-10T10:00:00Z"
}

Example

curl -X PATCH "https://api.example.com/microservices/workflow/<id>/collaborators/<user_id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

DELETE /microservices/workflow/{id}/collaborators/{user_id}/

Remove a collaborator

Owner only — except that a collaborator may remove themselves.

Auth: Session token

Path parameters

Field	Type	Required	Description
id	string (uuid)	yes
user_id	integer	yes

Response 200 — Removed.

Field	Type	Description
status	string ("removed")
user_id	integer

Example

curl -X DELETE "https://api.example.com/microservices/workflow/<id>/collaborators/<user_id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /microservices/workflows/copy-to-user/

Share a copy with users

Owner only. Gives each user their own copy of the workflow (optionally restricted to running it from Apps). mode decides how the workflow's extracted tables travel: share grants access to the same tables, clone duplicates them. Later changes can be pushed with workflows/sync/.

Auth: Session token · In the app: Workflow AI → Share → Send a copy

Request body (application/json)

Field	Type	Required	Description
workflow_id	string (uuid)	yes
users	object[]	yes
users[].user_id	integer	no
users[].email	string	no
users[].username	string	no
users[].only_view_in_apps	boolean	no	Default: false.
mode	string ("share", "clone")	yes
include_outputs	boolean	no	Default: false.

{
  "workflow_id": "7d4c2b1a-0e9f-4a3b-8c7d-6e5f4a3b2c1d",
  "users": [
    {
      "email": "omar@acme.com",
      "only_view_in_apps": true
    }
  ],
  "mode": "share"
}

Response 201 — Copies created.

Field	Type	Description
source_workflow_id	string
results	object[]
results[].target_user	object
results[].only_view_in_apps	boolean
results[].copied_workflow_id	string
results[].nodes_copied	integer
results[].outputs_copied	integer
results[].status	string
results[].files_not_shared	string[]
results[].files_not_shared_reason	string

Response 400 — Missing fields or invalid mode.

{
  "error": "path is required"
}

Example

curl -X POST "https://api.example.com/microservices/workflows/copy-to-user/" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workflow_id":"7d4c2b1a-0e9f-4a3b-8c7d-6e5f4a3b2c1d","users":[{"email":"omar@acme.com","only_view_in_apps":true}],"mode":"share"}'

POST /microservices/workflows/remove-users/

Withdraw shared copies

Auth: Session token · In the app: Workflow AI → Share → Remove

Request body (application/json)

Field	Type	Required	Description
workflow_id	string (uuid)	yes
users	object[]	yes
users[].user_id	integer	no
users[].email	string	no
users[].username	string	no

Response 200 — Result per user.

Field	Type	Description
source_workflow_id	string
results	object[]
results[].target_user	object
results[].removed	boolean
results[].message	string

Example

curl -X POST "https://api.example.com/microservices/workflows/remove-users/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /microservices/workflows/sync/

Push my changes to everyone I shared with

App-only recipients get the new definition immediately; recipients with editable copies get a pending share update they can apply or decline.

Auth: Session token · In the app: Workflow AI → Share → Sync

Request body (application/json)

Field	Type	Required	Description
workflow_id	string (uuid)	yes

Response 200 — Delivery summary.

Field	Type	Description
source_workflow_id	string
synced_count	integer
copy_workflow_ids	string[]
pending_count	integer
pending	object[]

Example

curl -X POST "https://api.example.com/microservices/workflows/sync/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /microservices/workflows/duplicate/

Duplicate a workflow

Auth: Session token · In the app: Workflow AI → Duplicate

Request body (application/json)

Field	Type	Required	Description
workflow_id	string (uuid)	yes

Response 201 — Copy created.

Field	Type	Description
source_workflow_id	string
copied_workflow_id	string
nodes_copied	integer
status	string ("duplicated")

Example

curl -X POST "https://api.example.com/microservices/workflows/duplicate/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /microservices/workflow-share-updates/

Share updates waiting for me

Definitions pushed by the people who shared workflows with you, not yet applied or declined.

Auth: Session token · In the app: Banner on a shared workflow

Query parameters

Field	Type	Required	Description
workflow_id	string (uuid)	no	Only updates for this copy.

Response 200 — Updates.

Array of:

Field	Type	Description
id	string
status	string
created_at	string (date-time)
workflow	object
workflow.id	string
workflow.name	string
sharer	object
sharer.id	integer
sharer.username	string
node_count	integer

Example

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

GET /microservices/workflow-share-updates/{update_id}/

A pushed definition (for review)

Auth: Session token

Path parameters

Field	Type	Required	Description
update_id	string (uuid)	yes

Response 200 — The pushed definition next to your current one.

Field	Type	Description
id	string
status	string
created_at	string (date-time)
workflow	object
sharer	object
node_count	integer
json_spec	object
vueflow_json	object
current_json_spec	object

Example

curl -X GET "https://api.example.com/microservices/workflow-share-updates/<update_id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /microservices/workflow-share-updates/{update_id}/apply/

Accept a share update

Snapshots your current definition first (recoverable from versions/).

Auth: Session token

Path parameters

Field	Type	Required	Description
update_id	string (uuid)	yes

Response 200 — Applied.

Field	Type	Description
status	string ("applied")
workflow_id	string
content_revision	integer

Response 400 — Already resolved.

{
  "error": "path is required"
}

Example

curl -X POST "https://api.example.com/microservices/workflow-share-updates/<update_id>/apply/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /microservices/workflow-share-updates/{update_id}/decline/

Decline a share update

Auth: Session token

Path parameters

Field	Type	Required	Description
update_id	string (uuid)	yes

Response 200 — Declined.

Field	Type	Description
status	string ("declined")
id	string

Example

curl -X POST "https://api.example.com/microservices/workflow-share-updates/<update_id>/decline/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /microservices/documents/

Files uploaded for workflows

Files attached to nodes through the canvas file picker (separate from My Data).

Auth: Session token · In the app: Canvas → file upload field

Response 200 — Files.

Array of:

Field	Type	Description
uid	string (uuid)
file	string	Media URL.
file_path	string	Media path.
uploaded_at	string (date-time)

Example

curl -X GET "https://api.example.com/microservices/documents/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /microservices/documents/

Upload a file for a workflow node

Auth: Session token

Request body (multipart/form-data)

Field	Type	Required	Description
file	string (binary)	yes

Response 201 — Stored.

Field	Type	Description
uid	string
file	string
file_path	string
uploaded_at	string (date-time)

Example

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

DELETE /microservices/documents/

Delete a workflow file

Auth: Session token

Request body (application/json)

Field	Type	Required	Description
uid	string (uuid)	yes

Response 200 — Deleted.

Field	Type	Description
message	string

{
  "message": "OK"
}

Response 404 — Not your file.

{
  "error": "path is required"
}

Example

curl -X DELETE "https://api.example.com/microservices/documents/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /microservices/apis/

Tool catalogue

Every tool you can put on a canvas: platform tools, your own, and tools shared with you. Filter with search, ids and is_tool.

Auth: Session token · In the app: Canvas → node palette

Query parameters

Field	Type	Required	Description
search	string	no
ids	string	no	Comma-separated ids.
is_tool	boolean	no
ordering	string	no	Default: "-created_at".

Response 200 — Tools.

Array of:

Field	Type	Description
id	integer
name	string	Stable key; used as kind in workflow specs.
name_ar	string, nullable
method	string ("GET", "POST", "PUT", "DELETE")
endpoint	string	Path on the service, e.g. /search.
url	string	Base URL of the service (user tools).
port	integer, nullable
description	string
description_ar	string, nullable
parameters	object	Parameter schema shown in the node panel (field name → type/label/default/validation).
test_parameters	object
headers	object
query_params	object
response_example	object
agent_spec	object, nullable	Description of the tool for the assistant.
developed_by	string ("Developer", "User")	Developer tools are visible to everyone; User tools to their owner and shares.
owner	integer, nullable
owner_username	string	Omitted entirely when the tool has no owner.
service_type	string	Deployment fields, for tools the operator runs in-cluster; empty on hosted tools.
network_name	string
requires_gpu	boolean
running	boolean	Last known state of the tool container.
dir	string	Working directory of the service.
start_command	string
env_example	string	Sample environment file for running the service.
is_tool	boolean	Usable by the assistant as a tool.
is_long_running	boolean
media_access	boolean
model_capability	string ("none", "chat", "vision", "image_gen", "embed")
category	integer, nullable
category_details	object
category_details.id	integer
category_details.name	string
category_details.title	string
category_details.title_ar	string, nullable
category_details.color	string
category_details.icon	string	SVG markup.
category_details.description	string
category_details.description_ar	string, nullable
category_details.is_active	boolean
category_details.apis_count	integer
category_details.created_at	string (date-time)
category_details.updated_at	string (date-time)
compatible_apis_details	object[]
compatible_apis_count	integer
shared	object	{"users": [{"id": 12, "username": "omar"}]}
timeout_seconds	integer
max_retries	integer
retry_delay_seconds	integer
created_at	string (date-time)
updated_at	string (date-time)

Example

curl -X GET "https://api.example.com/microservices/apis/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /microservices/apis/light/

Tool catalogue (names only)

Auth: Session token

Query parameters

Field	Type	Required	Description
ids	string	no
is_tool	boolean	no
ordering	string	no

Response 200 — Tools.

Array of:

Field	Type	Description
id	integer
name	string
name_ar	string, nullable
description	string
description_ar	string, nullable
category	object, nullable

Example

curl -X GET "https://api.example.com/microservices/apis/light/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /microservices/apis/create/

Register a custom tool

Adds your own HTTP service to the catalogue (developed_by: User). Share it with colleagues through shared.users.

Auth: Session token

Request body (application/json)

Field	Type	Required	Description
id	integer	no
name	string	no	Stable key; used as kind in workflow specs.
name_ar	string, nullable	no
method	string ("GET", "POST", "PUT", "DELETE")	no
endpoint	string	no	Path on the service, e.g. /search.
url	string	no	Base URL of the service (user tools).
port	integer, nullable	no
description	string	no
description_ar	string, nullable	no
parameters	object	no	Parameter schema shown in the node panel (field name → type/label/default/validation).
test_parameters	object	no
headers	object	no
query_params	object	no
response_example	object	no
agent_spec	object, nullable	no	Description of the tool for the assistant.
developed_by	string ("Developer", "User")	no	Developer tools are visible to everyone; User tools to their owner and shares.
owner	integer, nullable	no
owner_username	string	no	Omitted entirely when the tool has no owner.
service_type	string	no	Deployment fields, for tools the operator runs in-cluster; empty on hosted tools.
network_name	string	no
requires_gpu	boolean	no
running	boolean	no	Last known state of the tool container.
dir	string	no	Working directory of the service.
start_command	string	no
env_example	string	no	Sample environment file for running the service.
is_tool	boolean	no	Usable by the assistant as a tool.
is_long_running	boolean	no
media_access	boolean	no
model_capability	string ("none", "chat", "vision", "image_gen", "embed")	no
category	integer, nullable	no
category_details	object	no
category_details.id	integer	no
category_details.name	string	no
category_details.title	string	no
category_details.title_ar	string, nullable	no
category_details.color	string	no
category_details.icon	string	no	SVG markup.
category_details.description	string	no
category_details.description_ar	string, nullable	no
category_details.is_active	boolean	no
category_details.apis_count	integer	no
category_details.created_at	string (date-time)	no
category_details.updated_at	string (date-time)	no
compatible_apis_details	object[]	no
compatible_apis_count	integer	no
shared	object	no	{"users": [{"id": 12, "username": "omar"}]}
timeout_seconds	integer	no
max_retries	integer	no
retry_delay_seconds	integer	no
created_at	string (date-time)	no
updated_at	string (date-time)	no

{
  "name": "crm_lookup",
  "method": "POST",
  "endpoint": "/lookup",
  "url": "https://tools.acme.internal",
  "port": 8080,
  "description": "Look up a customer in the CRM.",
  "parameters": {
    "customer_id": {
      "type": "text",
      "label": "Customer id",
      "required": true
    }
  },
  "developed_by": "User",
  "timeout_seconds": 30
}

Response 201 — Registered.

Field	Type	Description
id	integer
name	string	Stable key; used as kind in workflow specs.
name_ar	string, nullable
method	string ("GET", "POST", "PUT", "DELETE")
endpoint	string	Path on the service, e.g. /search.
url	string	Base URL of the service (user tools).
port	integer, nullable
description	string
description_ar	string, nullable
parameters	object	Parameter schema shown in the node panel (field name → type/label/default/validation).
test_parameters	object
headers	object
query_params	object
response_example	object
agent_spec	object, nullable	Description of the tool for the assistant.
developed_by	string ("Developer", "User")	Developer tools are visible to everyone; User tools to their owner and shares.
owner	integer, nullable
owner_username	string	Omitted entirely when the tool has no owner.
service_type	string	Deployment fields, for tools the operator runs in-cluster; empty on hosted tools.
network_name	string
requires_gpu	boolean
running	boolean	Last known state of the tool container.
dir	string	Working directory of the service.
start_command	string
env_example	string	Sample environment file for running the service.
is_tool	boolean	Usable by the assistant as a tool.
is_long_running	boolean
media_access	boolean
model_capability	string ("none", "chat", "vision", "image_gen", "embed")
category	integer, nullable
category_details	object
category_details.id	integer
category_details.name	string
category_details.title	string
category_details.title_ar	string, nullable
category_details.color	string
category_details.icon	string	SVG markup.
category_details.description	string
category_details.description_ar	string, nullable
category_details.is_active	boolean
category_details.apis_count	integer
category_details.created_at	string (date-time)
category_details.updated_at	string (date-time)
compatible_apis_details	object[]
compatible_apis_count	integer
shared	object	{"users": [{"id": 12, "username": "omar"}]}
timeout_seconds	integer
max_retries	integer
retry_delay_seconds	integer
created_at	string (date-time)
updated_at	string (date-time)

{
  "id": 18,
  "name": "web_search",
  "name_ar": "بحث الويب",
  "method": "POST",
  "endpoint": "/search",
  "description": "Search the web and return the top results.",
  "parameters": {
    "query": {
      "type": "text",
      "label": "Query",
      "required": true
    },
    "max_results": {
      "type": "number",
      "default": 10
    }
  },
  "developed_by": "Developer",
  "owner": null,
  "owner_username": "",
  "is_tool": true,
  "is_long_running": false,
  "media_access": false,
  "model_capability": "none",
  "category": 3,
  "category_details": {
    "id": 3,
    "name": "research",
    "title": "Research",
    "color": "#0e6d92"
  },
  "compatible_apis_count": 4,
  "timeout_seconds": 60,
  "max_retries": 3,
  "retry_delay_seconds": 10,
  "created_at": "2026-01-10T08:00:00Z",
  "updated_at": "2026-08-01T08:00:00Z"
}

Response 400 — Validation errors.

{
  "username": [
    "A user with that username already exists."
  ]
}

Example

curl -X POST "https://api.example.com/microservices/apis/create/" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"crm_lookup","method":"POST","endpoint":"/lookup","url":"https://tools.acme.internal","port":8080,"description":"Look up a customer in the CRM.","parameters":{"customer_id":{"type":"text","label":"Customer id","required":true}},"developed_by":"User","timeout_seconds":30}'

GET /microservices/apis/{id}/

Get a tool

Auth: Session token

Path parameters

Field	Type	Required	Description
id	integer	yes

Response 200 — The tool.

Field	Type	Description
id	integer
name	string	Stable key; used as kind in workflow specs.
name_ar	string, nullable
method	string ("GET", "POST", "PUT", "DELETE")
endpoint	string	Path on the service, e.g. /search.
url	string	Base URL of the service (user tools).
port	integer, nullable
description	string
description_ar	string, nullable
parameters	object	Parameter schema shown in the node panel (field name → type/label/default/validation).
test_parameters	object
headers	object
query_params	object
response_example	object
agent_spec	object, nullable	Description of the tool for the assistant.
developed_by	string ("Developer", "User")	Developer tools are visible to everyone; User tools to their owner and shares.
owner	integer, nullable
owner_username	string	Omitted entirely when the tool has no owner.
service_type	string	Deployment fields, for tools the operator runs in-cluster; empty on hosted tools.
network_name	string
requires_gpu	boolean
running	boolean	Last known state of the tool container.
dir	string	Working directory of the service.
start_command	string
env_example	string	Sample environment file for running the service.
is_tool	boolean	Usable by the assistant as a tool.
is_long_running	boolean
media_access	boolean
model_capability	string ("none", "chat", "vision", "image_gen", "embed")
category	integer, nullable
category_details	object
category_details.id	integer
category_details.name	string
category_details.title	string
category_details.title_ar	string, nullable
category_details.color	string
category_details.icon	string	SVG markup.
category_details.description	string
category_details.description_ar	string, nullable
category_details.is_active	boolean
category_details.apis_count	integer
category_details.created_at	string (date-time)
category_details.updated_at	string (date-time)
compatible_apis_details	object[]
compatible_apis_count	integer
shared	object	{"users": [{"id": 12, "username": "omar"}]}
timeout_seconds	integer
max_retries	integer
retry_delay_seconds	integer
created_at	string (date-time)
updated_at	string (date-time)

{
  "id": 18,
  "name": "web_search",
  "name_ar": "بحث الويب",
  "method": "POST",
  "endpoint": "/search",
  "description": "Search the web and return the top results.",
  "parameters": {
    "query": {
      "type": "text",
      "label": "Query",
      "required": true
    },
    "max_results": {
      "type": "number",
      "default": 10
    }
  },
  "developed_by": "Developer",
  "owner": null,
  "owner_username": "",
  "is_tool": true,
  "is_long_running": false,
  "media_access": false,
  "model_capability": "none",
  "category": 3,
  "category_details": {
    "id": 3,
    "name": "research",
    "title": "Research",
    "color": "#0e6d92"
  },
  "compatible_apis_count": 4,
  "timeout_seconds": 60,
  "max_retries": 3,
  "retry_delay_seconds": 10,
  "created_at": "2026-01-10T08:00:00Z",
  "updated_at": "2026-08-01T08:00:00Z"
}

Response 404 — Not accessible.

{
  "error": "path is required"
}

Example

curl -X GET "https://api.example.com/microservices/apis/<id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

PUT /microservices/apis/{id}/

Update a tool (owner)

Auth: Session token

Path parameters

Field	Type	Required	Description
id	integer	yes

Request body (application/json)

Field	Type	Required	Description
id	integer	no
name	string	no	Stable key; used as kind in workflow specs.
name_ar	string, nullable	no
method	string ("GET", "POST", "PUT", "DELETE")	no
endpoint	string	no	Path on the service, e.g. /search.
url	string	no	Base URL of the service (user tools).
port	integer, nullable	no
description	string	no
description_ar	string, nullable	no
parameters	object	no	Parameter schema shown in the node panel (field name → type/label/default/validation).
test_parameters	object	no
headers	object	no
query_params	object	no
response_example	object	no
agent_spec	object, nullable	no	Description of the tool for the assistant.
developed_by	string ("Developer", "User")	no	Developer tools are visible to everyone; User tools to their owner and shares.
owner	integer, nullable	no
owner_username	string	no	Omitted entirely when the tool has no owner.
service_type	string	no	Deployment fields, for tools the operator runs in-cluster; empty on hosted tools.
network_name	string	no
requires_gpu	boolean	no
running	boolean	no	Last known state of the tool container.
dir	string	no	Working directory of the service.
start_command	string	no
env_example	string	no	Sample environment file for running the service.
is_tool	boolean	no	Usable by the assistant as a tool.
is_long_running	boolean	no
media_access	boolean	no
model_capability	string ("none", "chat", "vision", "image_gen", "embed")	no
category	integer, nullable	no
category_details	object	no
category_details.id	integer	no
category_details.name	string	no
category_details.title	string	no
category_details.title_ar	string, nullable	no
category_details.color	string	no
category_details.icon	string	no	SVG markup.
category_details.description	string	no
category_details.description_ar	string, nullable	no
category_details.is_active	boolean	no
category_details.apis_count	integer	no
category_details.created_at	string (date-time)	no
category_details.updated_at	string (date-time)	no
compatible_apis_details	object[]	no
compatible_apis_count	integer	no
shared	object	no	{"users": [{"id": 12, "username": "omar"}]}
timeout_seconds	integer	no
max_retries	integer	no
retry_delay_seconds	integer	no
created_at	string (date-time)	no
updated_at	string (date-time)	no

{
  "id": 18,
  "name": "web_search",
  "name_ar": "بحث الويب",
  "method": "POST",
  "endpoint": "/search",
  "description": "Search the web and return the top results.",
  "parameters": {
    "query": {
      "type": "text",
      "label": "Query",
      "required": true
    },
    "max_results": {
      "type": "number",
      "default": 10
    }
  },
  "developed_by": "Developer",
  "owner": null,
  "owner_username": "",
  "is_tool": true,
  "is_long_running": false,
  "media_access": false,
  "model_capability": "none",
  "category": 3,
  "category_details": {
    "id": 3,
    "name": "research",
    "title": "Research",
    "color": "#0e6d92"
  },
  "compatible_apis_count": 4,
  "timeout_seconds": 60,
  "max_retries": 3,
  "retry_delay_seconds": 10,
  "created_at": "2026-01-10T08:00:00Z",
  "updated_at": "2026-08-01T08:00:00Z"
}

Response 200 — Updated.

Field	Type	Description
id	integer
name	string	Stable key; used as kind in workflow specs.
name_ar	string, nullable
method	string ("GET", "POST", "PUT", "DELETE")
endpoint	string	Path on the service, e.g. /search.
url	string	Base URL of the service (user tools).
port	integer, nullable
description	string
description_ar	string, nullable
parameters	object	Parameter schema shown in the node panel (field name → type/label/default/validation).
test_parameters	object
headers	object
query_params	object
response_example	object
agent_spec	object, nullable	Description of the tool for the assistant.
developed_by	string ("Developer", "User")	Developer tools are visible to everyone; User tools to their owner and shares.
owner	integer, nullable
owner_username	string	Omitted entirely when the tool has no owner.
service_type	string	Deployment fields, for tools the operator runs in-cluster; empty on hosted tools.
network_name	string
requires_gpu	boolean
running	boolean	Last known state of the tool container.
dir	string	Working directory of the service.
start_command	string
env_example	string	Sample environment file for running the service.
is_tool	boolean	Usable by the assistant as a tool.
is_long_running	boolean
media_access	boolean
model_capability	string ("none", "chat", "vision", "image_gen", "embed")
category	integer, nullable
category_details	object
category_details.id	integer
category_details.name	string
category_details.title	string
category_details.title_ar	string, nullable
category_details.color	string
category_details.icon	string	SVG markup.
category_details.description	string
category_details.description_ar	string, nullable
category_details.is_active	boolean
category_details.apis_count	integer
category_details.created_at	string (date-time)
category_details.updated_at	string (date-time)
compatible_apis_details	object[]
compatible_apis_count	integer
shared	object	{"users": [{"id": 12, "username": "omar"}]}
timeout_seconds	integer
max_retries	integer
retry_delay_seconds	integer
created_at	string (date-time)
updated_at	string (date-time)

{
  "id": 18,
  "name": "web_search",
  "name_ar": "بحث الويب",
  "method": "POST",
  "endpoint": "/search",
  "description": "Search the web and return the top results.",
  "parameters": {
    "query": {
      "type": "text",
      "label": "Query",
      "required": true
    },
    "max_results": {
      "type": "number",
      "default": 10
    }
  },
  "developed_by": "Developer",
  "owner": null,
  "owner_username": "",
  "is_tool": true,
  "is_long_running": false,
  "media_access": false,
  "model_capability": "none",
  "category": 3,
  "category_details": {
    "id": 3,
    "name": "research",
    "title": "Research",
    "color": "#0e6d92"
  },
  "compatible_apis_count": 4,
  "timeout_seconds": 60,
  "max_retries": 3,
  "retry_delay_seconds": 10,
  "created_at": "2026-01-10T08:00:00Z",
  "updated_at": "2026-08-01T08:00:00Z"
}

Response 403 — Not the owner.

{
  "error": "path is required"
}

Example

curl -X PUT "https://api.example.com/microservices/apis/<id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"id":18,"name":"web_search","name_ar":"بحث الويب","method":"POST","endpoint":"/search","description":"Search the web and return the top results.","parameters":{"query":{"type":"text","label":"Query","required":true},"max_results":{"type":"number","default":10}},"developed_by":"Developer","owner":null,"owner_username":"","is_tool":true,"is_long_running":false,"media_access":false,"model_capability":"none","category":3,"category_details":{"id":3,"name":"research","title":"Research","color":"#0e6d92"},"compatible_apis_count":4,"timeout_seconds":60,"max_retries":3,"retry_delay_seconds":10,"created_at":"2026-01-10T08:00:00Z","updated_at":"2026-08-01T08:00:00Z"}'

DELETE /microservices/apis/{id}/

Delete a tool (owner)

Auth: Session token

Path parameters

Field	Type	Required	Description
id	integer	yes

Response 200 — Deleted.

Field	Type	Description
message	string

{
  "message": "OK"
}

Response 403 — Not the owner.

Example

curl -X DELETE "https://api.example.com/microservices/apis/<id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /microservices/apis/{id}/test/

Call a tool directly

Sends the tool's test_parameters (or the body you provide) to the service and returns its raw response — the "Test" button in the tool editor.

Auth: Session token

Path parameters

Field	Type	Required	Description
id	integer	yes

Request body (application/json, optional)

Response 200 — The service's response body (JSON or text), always returned with status 200.

Response 500 — The service could not be reached.

Example

curl -X POST "https://api.example.com/microservices/apis/<id>/test/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

GET /microservices/categories/

Tool categories

Auth: Session token · In the app: Canvas → node palette groups

Response 200 — Active categories with the number of tools you can access in each.

Array of:

Field	Type	Description
id	integer
name	string
title	string
title_ar	string, nullable
color	string
icon	string	SVG markup.
description	string
description_ar	string, nullable
is_active	boolean
apis_count	integer
created_at	string (date-time)
updated_at	string (date-time)

Example

curl -X GET "https://api.example.com/microservices/categories/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

POST /microservices/categories/

Create a category

Auth: Session token

Request body (application/json)

Field	Type	Required	Description
id	integer	no
name	string	no
title	string	no
title_ar	string, nullable	no
color	string	no
icon	string	no	SVG markup.
description	string	no
description_ar	string, nullable	no
is_active	boolean	no
apis_count	integer	no
created_at	string (date-time)	no
updated_at	string (date-time)	no

Response 201 — Created.

Field	Type	Description
id	integer
name	string
title	string
title_ar	string, nullable
color	string
icon	string	SVG markup.
description	string
description_ar	string, nullable
is_active	boolean
apis_count	integer
created_at	string (date-time)
updated_at	string (date-time)

Example

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

GET /microservices/categories/{id}/

Get a category

Auth: Session token

Path parameters

Field	Type	Required	Description
id	integer	yes

Response 200 — The category.

Field	Type	Description
id	integer
name	string
title	string
title_ar	string, nullable
color	string
icon	string	SVG markup.
description	string
description_ar	string, nullable
is_active	boolean
apis_count	integer
created_at	string (date-time)
updated_at	string (date-time)

Example

curl -X GET "https://api.example.com/microservices/categories/<id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

PUT /microservices/categories/{id}/

Update a category

Auth: Session token

Path parameters

Field	Type	Required	Description
id	integer	yes

Request body (application/json)

Field	Type	Required	Description
id	integer	no
name	string	no
title	string	no
title_ar	string, nullable	no
color	string	no
icon	string	no	SVG markup.
description	string	no
description_ar	string, nullable	no
is_active	boolean	no
apis_count	integer	no
created_at	string (date-time)	no
updated_at	string (date-time)	no

Response 200 — Updated.

Field	Type	Description
id	integer
name	string
title	string
title_ar	string, nullable
color	string
icon	string	SVG markup.
description	string
description_ar	string, nullable
is_active	boolean
apis_count	integer
created_at	string (date-time)
updated_at	string (date-time)

Example

curl -X PUT "https://api.example.com/microservices/categories/<id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN"

DELETE /microservices/categories/{id}/

Deactivate a category

Auth: Session token

Path parameters

Field	Type	Required	Description
id	integer	yes

Response 200 — Marked inactive.

Field	Type	Description
message	string

{
  "message": "OK"
}

Example

curl -X DELETE "https://api.example.com/microservices/categories/<id>/" \
  -H "Authorization: Token $FINBLADE_TOKEN"