Sovereign OS — Dify Agent Tools — OpenAPI 1.0.0
<!-- GENERATED by scripts/render-platform-map-api-docs.mjs — do not hand-edit; edit apps/agent-bff/openapi/<spec>.json and re-run. --> Scope: The published reference for Sovereign OS — Dify Agent Tools. 17 paths — the measured spec-vs-implementation coverage lives in the complete API inventory. Status: rendered 2026-11-09 from the OpenAPI source for Sovereign OS — Dify Agent Tools — regenerate with node scripts/render-platform-map-api-docs.mjs. See also: the OpenAPI spec index.
Servers
| URL | Notes |
|---|---|
| http://127.0.0.1:3030 | Local dev (DEV_SKIP_AUTH=1) |
| https://api.sovereignos.org | Production |
Tags
| Tag | Summary |
|---|---|
| truth-graph | Truth Graph node/edge read and traversal operations |
| governance | Scope governance and ABAC policy operations |
| messaging | Multichannel messaging to platform users |
| commerce | Commerce quoting and subscription operations |
| search | Semantic search across the Truth Graph |
| forms | Form trigger and submission operations |
| vault | Vault document read operations |
| templates | Message template rendering for email, chat, and push notifications |
| bridge | Generalized bridge command routing to external subsystems |
Paths — 17 paths / 17 operations
| Method | Path | Operation ID | Summary |
|---|---|---|---|
| POST | /v1/dify/tools/truth/read-node | truthReadNode | Read a truth node by ID |
| POST | /v1/dify/tools/truth/traverse | truthTraverse | Traverse the truth graph from a node |
| POST | /v1/dify/tools/truth/write-node | truthWriteNode | Create, update, or delete a truth node |
| POST | /v1/dify/tools/truth/write-edge | truthWriteEdge | Create or delete a truth edge |
| POST | /v1/dify/tools/truth/reindex | truthReindex | Reindex a truth node for semantic search |
| POST | /v1/dify/tools/truth/search | truthSearch | Semantic search across truth nodes |
| POST | /v1/dify/tools/governance/evaluate | governanceEvaluate | Evaluate ABAC policy for an action |
| POST | /v1/dify/tools/messaging/send | messagingSend | Send a message to a platform user |
| POST | /v1/dify/tools/quoting/request | quotingRequest | Request a commerce quote |
| POST | /v1/dify/tools/search | semanticSearch | Semantic search across the Truth Graph |
| POST | /v1/dify/tools/forms/trigger | formsTrigger | Trigger a form for user data collection |
| POST | /v1/dify/tools/vault/read-document | vaultReadDocument | Read a document from the Sovereign Vault |
| POST | /v1/dify/tools/provisioning/create-organization | provisioningCreateOrganization | Create a new organization with provisioning |
| POST | /v1/dify/tools/governance/team-members | governanceListTeamMembers | List team members for the current scope |
| POST | /v1/dify/tools/bus/emit-event | busEmitEvent | Route a command to any bridge service |
| GET | /v1/dify/tools/openapi.json | getDifyToolOpenApi | Dify Tools OpenAPI spec (self-describing) |
| POST | /v1/dify/tools/templates/render | templatesRender | Render a message template with variables |
Operations
POST /v1/dify/tools/truth/read-node
Summary: Read a truth node by ID Description: Returns the full record for a truth node. Use this to inspect a node's traits, edges, and metadata.
Tags: truth-graph Operation ID: truthReadNode
Parameters:
| Name | In | Required | Type | Notes |
|---|---|---|---|---|
| no | ||||
| no |
Request body:
Content type: application/json
| Field | Type | Notes |
|---|---|---|
| node_id | string | Truth node ID |
| include_edges | boolean | Include connected edges |
Responses:
| Status | Meaning |
|---|---|
| 200 | Node data |
| 401 | |
| 404 | |
| 503 |
POST /v1/dify/tools/truth/traverse
Summary: Traverse the truth graph from a node Description: Traverse edges from a starting node, optionally filtering by edge type and depth. Returns the path and discovered nodes.
Tags: truth-graph Operation ID: truthTraverse
Parameters:
| Name | In | Required | Type | Notes |
|---|---|---|---|---|
| no | ||||
| no |
Request body:
Content type: application/json
| Field | Type | Notes |
|---|---|---|
| node_id | string | |
| edge_types | string[] | Filter by edge types (e.g. ['has_lease', 'is_parent']) |
| max_depth | int | |
| max_results | int |
Responses:
| Status | Meaning |
|---|---|
| 200 | Traversal result |
| 401 | |
| 503 |
POST /v1/dify/tools/truth/write-node
Summary: Create, update, or delete a truth node Description: Mutation endpoint for truth graph nodes. Supports create, update, and delete actions with PoCE audit logging.
Tags: truth-graph Operation ID: truthWriteNode
Parameters:
| Name | In | Required | Type | Notes |
|---|---|---|---|---|
| no | ||||
| no |
Request body:
Content type: application/json
| Field | Type | Notes |
|---|---|---|
| node_id | string | Truth node ID |
| action | string enum: create, update, delete | Mutation action |
| node_type | string | Node type (required for create) |
| name | string | Node display name |
| description | string | Node description |
| metadata | object | Arbitrary metadata object |
| correlation_id | string | Idempotency key |
Responses:
| Status | Meaning |
|---|---|
| 200 | Mutation result |
| 401 | |
| 503 |
POST /v1/dify/tools/truth/write-edge
Summary: Create or delete a truth edge Description: Mutation endpoint for truth graph edges. Supports create and delete actions.
Tags: truth-graph Operation ID: truthWriteEdge
Parameters:
| Name | In | Required | Type | Notes |
|---|---|---|---|---|
| no | ||||
| no |
Request body:
Content type: application/json
| Field | Type | Notes |
|---|---|---|
| action | string enum: create, delete | Mutation action |
| from_node | string | Source node ID (required for create) |
| to_node | string | Target node ID (required for create) |
| edge_type | string | Edge type (required for create) |
| strength | number | Edge strength (0-1) |
| edge_id | string | Edge ID (required for delete) |
| correlation_id | string | Idempotency key |
Responses:
| Status | Meaning |
|---|---|
| 200 | Mutation result |
| 401 | |
| 503 |
POST /v1/dify/tools/truth/reindex
Summary: Reindex a truth node for semantic search Description: Triggers reindexing of a truth node's embedding in the semantic search index.
Tags: truth-graph Operation ID: truthReindex
Parameters:
| Name | In | Required | Type | Notes |
|---|---|---|---|---|
| no | ||||
| no |
Request body:
Content type: application/json
| Field | Type | Notes |
|---|---|---|
| node_id | string | Truth node ID to reindex |
Responses:
| Status | Meaning |
|---|---|
| 200 | Reindex result |
| 401 | |
| 503 |
POST /v1/dify/tools/truth/search
Summary: Semantic search across truth nodes Description: Full-text semantic search over the truth index using vector embeddings.
Tags: truth-graph Operation ID: truthSearch
Parameters:
| Name | In | Required | Type | Notes |
|---|---|---|---|---|
| no | ||||
| no |
Request body:
Content type: application/json
| Field | Type | Notes |
|---|---|---|
| query_text | string | Search query |
| limit | int | |
| threshold | number | Minimum similarity threshold |
| scope_id | string | Scope filter |
Responses:
| Status | Meaning |
|---|---|
| 200 | Search results |
| 401 | |
| 503 |
POST /v1/dify/tools/governance/evaluate
Summary: Evaluate ABAC policy for an action Description: Check whether a user is allowed to perform a specific action on a resource within a scope. Returns the policy decision.
Tags: governance Operation ID: governanceEvaluate
Parameters:
| Name | In | Required | Type | Notes |
|---|---|---|---|---|
| no | ||||
| no |
Request body:
Content type: application/json
| Field | Type | Notes |
|---|---|---|
| action | string | Action to evaluate (e.g. 'team.member_added') |
| resource_type | string | Resource type (e.g. 'team', 'org', 'user') |
| resource_id | string |
Responses:
| Status | Meaning |
|---|---|
| 200 | Policy decision |
| 401 | |
| 503 |
POST /v1/dify/tools/messaging/send
Summary: Send a message to a platform user Description: Sends an outbound message to a user on a supported platform (WhatsApp, Telegram, Slack, Discord, SMS). The platform is auto-resolved from the user's profile.
Tags: messaging Operation ID: messagingSend
Parameters:
| Name | In | Required | Type | Notes |
|---|---|---|---|---|
| no | ||||
| no |
Request body:
Content type: application/json
| Field | Type | Notes |
|---|---|---|
| user_id | string | Target user ID |
| message | string | Message content |
| platform | string enum: whatsapp, telegram, slack, sms | Override platform detection |
Responses:
| Status | Meaning |
|---|---|
| 200 | Send result |
| 401 | |
| 503 |
POST /v1/dify/tools/quoting/request
Summary: Request a commerce quote Description: Creates a commerce quote request for a product or service. Returns the quote ID and estimated amount.
Tags: commerce Operation ID: quotingRequest
Parameters:
| Name | In | Required | Type | Notes |
|---|---|---|---|---|
| no | ||||
| no |
Request body:
Content type: application/json
| Field | Type | Notes |
|---|---|---|
| product_id | string | |
| quantity | number | |
| currency | string | |
| notes | string |
Responses:
| Status | Meaning |
|---|---|
| 200 | Quote response |
| 401 | |
| 503 |
POST /v1/dify/tools/search
Summary: Semantic search across the Truth Graph Description: Performs a vector similarity search across truth nodes. Returns ranked results with relevance scores.
Tags: search Operation ID: semanticSearch
Parameters:
| Name | In | Required | Type | Notes |
|---|---|---|---|---|
| no |
Request body:
Content type: application/json
| Field | Type | Notes |
|---|---|---|
| query | string | Natural language search query |
| filters | object | Optional field filters |
| limit | int |
Responses:
| Status | Meaning |
|---|---|
| 200 | Search results |
| 401 | |
| 503 |
POST /v1/dify/tools/forms/trigger
Summary: Trigger a form for user data collection Description: Triggers a form.io form for a user. The user will receive the form via their preferred channel and the submission will be returned to the agent.
Tags: forms Operation ID: formsTrigger
Parameters:
| Name | In | Required | Type | Notes |
|---|---|---|---|---|
| no | ||||
| no |
Request body:
Content type: application/json
| Field | Type | Notes |
|---|---|---|
| form_id | string | Form.io form ID |
| recipient_id | string | User who needs to fill the form |
| prefill | object | Pre-fill values for the form |
| expires_in_hours | int |
Responses:
| Status | Meaning |
|---|---|
| 200 | Form triggered |
| 401 | |
| 503 |
POST /v1/dify/tools/vault/read-document
Summary: Read a document from the Sovereign Vault Description: Retrieves a vault document's metadata and content reference by its UON or claim ID. Requires active vault_access_lease.
Tags: vault Operation ID: vaultReadDocument
Parameters:
| Name | In | Required | Type | Notes |
|---|---|---|---|---|
| no | ||||
| no |
Request body:
Content type: application/json
| Field | Type | Notes |
|---|---|---|
| document_uri | string | UON or vault claim ID |
| include_content | boolean |
Responses:
| Status | Meaning |
|---|---|
| 200 | Document data |
| 401 | |
| 403 | |
| 503 |
POST /v1/dify/tools/provisioning/create-organization
Summary: Create a new organization with provisioning Description: Provisions a new organization, its sovereign account, virtual app, and manifest in a single call. Returns the created entity IDs. Requires governance approval.
Tags: governance Operation ID: provisioningCreateOrganization
Parameters:
| Name | In | Required | Type | Notes |
|---|---|---|---|---|
| no | ||||
| no |
Request body:
Content type: application/json
| Field | Type | Notes |
|---|---|---|
| org_name | string | |
| admin_user_id | string | User who will be the org admin |
| description | string | |
| country_code | string |
Responses:
| Status | Meaning |
|---|---|
| 200 | Provisioning result |
| 401 | |
| 403 | |
| 503 |
POST /v1/dify/tools/governance/team-members
Summary: List team members for the current scope Description: Returns members of teams within the active scope. Used by Generative UI dropdowns to populate user selection.
Tags: governance Operation ID: governanceListTeamMembers
Parameters:
| Name | In | Required | Type | Notes |
|---|---|---|---|---|
| no | ||||
| no |
Request body:
Content type: application/json
| Field | Type | Notes |
|---|---|---|
| team_id | string | Optional team filter |
| role | string | Optional role filter |
| limit | int |
Responses:
| Status | Meaning |
|---|---|
| 200 | Member list |
| 401 | |
| 503 |
POST /v1/dify/tools/bus/emit-event
Summary: Route a command to any bridge service Description: Generalized bridge command router. Publishes commands to NATS and waits for correlated responses from bridge services (usafiri, medusa, killbill, zammad, synapse, jitsi). Falls back to L3 HTTP if NATS is unavailable.
Tags: bridge Operation ID: busEmitEvent Request body:
Content type: application/json
| Field | Type | Notes |
|---|---|---|
| service | string enum: usafiri, medusa, killbill, zammad, synapse, jitsi | Bridge service name |
| command | string | Command name (e.g. order.create, driver.ensure) |
| payload | object | Command payload |
| subject | string | Alternative: explicit NATS subject (parsed for service/command) |
| org_id | string | Organization ID for scope resolution |
| timeout_ms | int | Response timeout in milliseconds |
Responses:
| Status | Meaning |
|---|---|
| 200 | Bridge command result |
GET /v1/dify/tools/openapi.json
Summary: Dify Tools OpenAPI spec (self-describing) Description: Returns the OpenAPI 3.1 spec for Dify Agent tools. Dify consumes this URL as a Custom Tool endpoint.
Tags: truth-graph Operation ID: getDifyToolOpenApi Responses:
| Status | Meaning |
|---|---|
| 200 | OpenAPI spec JSON |
POST /v1/dify/tools/templates/render
Summary: Render a message template with variables Description: Fetches a message template by ID, replaces {{variable}} placeholders with provided values, and returns the rendered HTML/CSS. Used by Dify agents to render email, chat, or push notification templates before sending.
Tags: templates Operation ID: templatesRender Request body:
Content type: application/json
| Field | Type | Notes |
|---|---|---|
| template_id | string | Template ID (e.g., tmpl_xxxxx or message_template:xxxxx) |
| variables | object | Key-value pairs for {{variable}} replacement |
Responses:
| Status | Meaning |
|---|---|
| 200 | Rendered template |
| 404 |
Full specification — verbatim source of truth
{
"openapi": "3.1.0",
"info": {
"title": "Sovereign OS — Dify Agent Tools",
"version": "1.0.0",
"description": "OpenAPI 3.1 fragment for Dify Chat Agent tool execution. Dify Agents consume this spec as Custom Tools to interact with the Sovereign Truth Graph.\n\nEach endpoint receives X-Node-Id and X-Scope-Id headers injected by the BFF from the Dify chat context. Authentication is via a short-lived service JWT embedded in the Dify chat inputs as _sovereign_token, passed back as Authorization: Bearer <token>.\n\nAll tool responses follow a standardized envelope:\n{ ok: boolean, data?: any, error?: string, poce_session_id?: string }\n\nHuman-readable: docs/integrations/dify_interactive_agent_architecture.md",
"x-tool-config": {
"auth_header": "Authorization",
"auth_scheme": "Bearer",
"context_headers": [
"X-Node-Id",
"X-Scope-Id",
"X-User-Id"
],
"response_envelope": "{ ok, data?, error?, poce_session_id? }",
"rate_limit": "60 rpm per tool, per user"
}
},
"servers": [
{
"url": "http://127.0.0.1:3030",
"description": "Local dev (DEV_SKIP_AUTH=1)"
},
{
"url": "https://api.sovereignos.org",
"description": "Production"
}
],
"tags": [
{
"name": "truth-graph",
"description": "Truth Graph node/edge read and traversal operations"
},
{
"name": "governance",
"description": "Scope governance and ABAC policy operations"
},
{
"name": "messaging",
"description": "Multichannel messaging to platform users"
},
{
"name": "commerce",
"description": "Commerce quoting and subscription operations"
},
{
"name": "search",
"description": "Semantic search across the Truth Graph"
},
{
"name": "forms",
"description": "Form trigger and submission operations"
},
{
"name": "vault",
"description": "Vault document read operations"
},
{
"name": "templates",
"description": "Message template rendering for email, chat, and push notifications"
},
{
"name": "bridge",
"description": "Generalized bridge command routing to external subsystems"
}
],
"paths": {
"/v1/dify/tools/truth/read-node": {
"post": {
"tags": [
"truth-graph"
],
"summary": "Read a truth node by ID",
"description": "Returns the full record for a truth node. Use this to inspect a node's traits, edges, and metadata.",
"operationId": "truthReadNode",
"parameters": [
{
"$ref": "#/components/parameters/NodeId"
},
{
"$ref": "#/components/parameters/ScopeId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"node_id"
],
"properties": {
"node_id": {
"type": "string",
"description": "Truth node ID"
},
"include_edges": {
"type": "boolean",
"default": false,
"description": "Include connected edges"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Node data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ToolResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"404": {
"$ref": "#/components/responses/NotFound"
},
"503": {
"$ref": "#/components/responses/ToolUnavailable"
}
}
}
},
"/v1/dify/tools/truth/traverse": {
"post": {
"tags": [
"truth-graph"
],
"summary": "Traverse the truth graph from a node",
"description": "Traverse edges from a starting node, optionally filtering by edge type and depth. Returns the path and discovered nodes.",
"operationId": "truthTraverse",
"parameters": [
{
"$ref": "#/components/parameters/NodeId"
},
{
"$ref": "#/components/parameters/ScopeId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"node_id"
],
"properties": {
"node_id": {
"type": "string"
},
"edge_types": {
"type": "array",
"items": {
"type": "string"
},
"description": "Filter by edge types (e.g. ['has_lease', 'is_parent'])"
},
"max_depth": {
"type": "integer",
"default": 2,
"minimum": 1,
"maximum": 5
},
"max_results": {
"type": "integer",
"default": 20,
"maximum": 100
}
}
}
}
}
},
"responses": {
"200": {
"description": "Traversal result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ToolResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"503": {
"$ref": "#/components/responses/ToolUnavailable"
}
}
}
},
"/v1/dify/tools/truth/write-node": {
"post": {
"tags": [
"truth-graph"
],
"summary": "Create, update, or delete a truth node",
"description": "Mutation endpoint for truth graph nodes. Supports create, update, and delete actions with PoCE audit logging.",
"operationId": "truthWriteNode",
"parameters": [
{
"$ref": "#/components/parameters/NodeId"
},
{
"$ref": "#/components/parameters/ScopeId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"node_id",
"action"
],
"properties": {
"node_id": {
"type": "string",
"description": "Truth node ID"
},
"action": {
"type": "string",
"enum": [
"create",
"update",
"delete"
],
"description": "Mutation action"
},
"node_type": {
"type": "string",
"description": "Node type (required for create)"
},
"name": {
"type": "string",
"description": "Node display name"
},
"description": {
"type": "string",
"description": "Node description"
},
"metadata": {
"type": "object",
"description": "Arbitrary metadata object"
},
"correlation_id": {
"type": "string",
"description": "Idempotency key"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Mutation result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ToolResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"503": {
"$ref": "#/components/responses/ToolUnavailable"
}
}
}
},
"/v1/dify/tools/truth/write-edge": {
"post": {
"tags": [
"truth-graph"
],
"summary": "Create or delete a truth edge",
"description": "Mutation endpoint for truth graph edges. Supports create and delete actions.",
"operationId": "truthWriteEdge",
"parameters": [
{
"$ref": "#/components/parameters/NodeId"
},
{
"$ref": "#/components/parameters/ScopeId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"action"
],
"properties": {
"action": {
"type": "string",
"enum": [
"create",
"delete"
],
"description": "Mutation action"
},
"from_node": {
"type": "string",
"description": "Source node ID (required for create)"
},
"to_node": {
"type": "string",
"description": "Target node ID (required for create)"
},
"edge_type": {
"type": "string",
"description": "Edge type (required for create)"
},
"strength": {
"type": "number",
"default": 1,
"description": "Edge strength (0-1)"
},
"edge_id": {
"type": "string",
"description": "Edge ID (required for delete)"
},
"correlation_id": {
"type": "string",
"description": "Idempotency key"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Mutation result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ToolResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"503": {
"$ref": "#/components/responses/ToolUnavailable"
}
}
}
},
"/v1/dify/tools/truth/reindex": {
"post": {
"tags": [
"truth-graph"
],
"summary": "Reindex a truth node for semantic search",
"description": "Triggers reindexing of a truth node's embedding in the semantic search index.",
"operationId": "truthReindex",
"parameters": [
{
"$ref": "#/components/parameters/NodeId"
},
{
"$ref": "#/components/parameters/ScopeId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"node_id"
],
"properties": {
"node_id": {
"type": "string",
"description": "Truth node ID to reindex"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Reindex result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ToolResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"503": {
"$ref": "#/components/responses/ToolUnavailable"
}
}
}
},
"/v1/dify/tools/truth/search": {
"post": {
"tags": [
"truth-graph"
],
"summary": "Semantic search across truth nodes",
"description": "Full-text semantic search over the truth index using vector embeddings.",
"operationId": "truthSearch",
"parameters": [
{
"$ref": "#/components/parameters/NodeId"
},
{
"$ref": "#/components/parameters/ScopeId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"query_text"
],
"properties": {
"query_text": {
"type": "string",
"description": "Search query"
},
"limit": {
"type": "integer",
"default": 10,
"maximum": 50
},
"threshold": {
"type": "number",
"default": 0.5,
"description": "Minimum similarity threshold"
},
"scope_id": {
"type": "string",
"description": "Scope filter"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Search results",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ToolResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"503": {
"$ref": "#/components/responses/ToolUnavailable"
}
}
}
},
"/v1/dify/tools/governance/evaluate": {
"post": {
"tags": [
"governance"
],
"summary": "Evaluate ABAC policy for an action",
"description": "Check whether a user is allowed to perform a specific action on a resource within a scope. Returns the policy decision.",
"operationId": "governanceEvaluate",
"parameters": [
{
"$ref": "#/components/parameters/NodeId"
},
{
"$ref": "#/components/parameters/ScopeId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"action",
"resource_type"
],
"properties": {
"action": {
"type": "string",
"description": "Action to evaluate (e.g. 'team.member_added')"
},
"resource_type": {
"type": "string",
"description": "Resource type (e.g. 'team', 'org', 'user')"
},
"resource_id": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Policy decision",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ToolResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"503": {
"$ref": "#/components/responses/ToolUnavailable"
}
}
}
},
"/v1/dify/tools/messaging/send": {
"post": {
"tags": [
"messaging"
],
"summary": "Send a message to a platform user",
"description": "Sends an outbound message to a user on a supported platform (WhatsApp, Telegram, Slack, Discord, SMS). The platform is auto-resolved from the user's profile.",
"operationId": "messagingSend",
"parameters": [
{
"$ref": "#/components/parameters/NodeId"
},
{
"$ref": "#/components/parameters/ScopeId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"user_id",
"message"
],
"properties": {
"user_id": {
"type": "string",
"description": "Target user ID"
},
"message": {
"type": "string",
"description": "Message content"
},
"platform": {
"type": "string",
"enum": [
"whatsapp",
"telegram",
"slack",
"sms"
],
"description": "Override platform detection"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Send result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ToolResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"503": {
"$ref": "#/components/responses/ToolUnavailable"
}
}
}
},
"/v1/dify/tools/quoting/request": {
"post": {
"tags": [
"commerce"
],
"summary": "Request a commerce quote",
"description": "Creates a commerce quote request for a product or service. Returns the quote ID and estimated amount.",
"operationId": "quotingRequest",
"parameters": [
{
"$ref": "#/components/parameters/NodeId"
},
{
"$ref": "#/components/parameters/ScopeId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"product_id",
"quantity"
],
"properties": {
"product_id": {
"type": "string"
},
"quantity": {
"type": "number",
"minimum": 0.01
},
"currency": {
"type": "string",
"default": "KES"
},
"notes": {
"type": "string"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Quote response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ToolResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"503": {
"$ref": "#/components/responses/ToolUnavailable"
}
}
}
},
"/v1/dify/tools/search": {
"post": {
"tags": [
"search"
],
"summary": "Semantic search across the Truth Graph",
"description": "Performs a vector similarity search across truth nodes. Returns ranked results with relevance scores.",
"operationId": "semanticSearch",
"parameters": [
{
"$ref": "#/components/parameters/ScopeId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"description": "Natural language search query"
},
"filters": {
"type": "object",
"description": "Optional field filters"
},
"limit": {
"type": "integer",
"default": 10,
"maximum": 50
}
}
}
}
}
},
"responses": {
"200": {
"description": "Search results",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ToolResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"503": {
"$ref": "#/components/responses/ToolUnavailable"
}
}
}
},
"/v1/dify/tools/forms/trigger": {
"post": {
"tags": [
"forms"
],
"summary": "Trigger a form for user data collection",
"description": "Triggers a form.io form for a user. The user will receive the form via their preferred channel and the submission will be returned to the agent.",
"operationId": "formsTrigger",
"parameters": [
{
"$ref": "#/components/parameters/NodeId"
},
{
"$ref": "#/components/parameters/ScopeId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"form_id",
"recipient_id"
],
"properties": {
"form_id": {
"type": "string",
"description": "Form.io form ID"
},
"recipient_id": {
"type": "string",
"description": "User who needs to fill the form"
},
"prefill": {
"type": "object",
"description": "Pre-fill values for the form"
},
"expires_in_hours": {
"type": "integer",
"default": 48
}
}
}
}
}
},
"responses": {
"200": {
"description": "Form triggered",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ToolResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"503": {
"$ref": "#/components/responses/ToolUnavailable"
}
}
}
},
"/v1/dify/tools/vault/read-document": {
"post": {
"tags": [
"vault"
],
"summary": "Read a document from the Sovereign Vault",
"description": "Retrieves a vault document's metadata and content reference by its UON or claim ID. Requires active vault_access_lease.",
"operationId": "vaultReadDocument",
"parameters": [
{
"$ref": "#/components/parameters/NodeId"
},
{
"$ref": "#/components/parameters/ScopeId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"document_uri"
],
"properties": {
"document_uri": {
"type": "string",
"description": "UON or vault claim ID"
},
"include_content": {
"type": "boolean",
"default": false
}
}
}
}
}
},
"responses": {
"200": {
"description": "Document data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ToolResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/LeaseDenied"
},
"503": {
"$ref": "#/components/responses/ToolUnavailable"
}
}
}
},
"/v1/dify/tools/provisioning/create-organization": {
"post": {
"tags": [
"governance"
],
"summary": "Create a new organization with provisioning",
"description": "Provisions a new organization, its sovereign account, virtual app, and manifest in a single call. Returns the created entity IDs. Requires governance approval.",
"operationId": "provisioningCreateOrganization",
"parameters": [
{
"$ref": "#/components/parameters/NodeId"
},
{
"$ref": "#/components/parameters/ScopeId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"org_name",
"admin_user_id"
],
"properties": {
"org_name": {
"type": "string"
},
"admin_user_id": {
"type": "string",
"description": "User who will be the org admin"
},
"description": {
"type": "string"
},
"country_code": {
"type": "string",
"default": "KE"
}
}
}
}
}
},
"responses": {
"200": {
"description": "Provisioning result",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ToolResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"403": {
"$ref": "#/components/responses/GovernanceDenied"
},
"503": {
"$ref": "#/components/responses/ToolUnavailable"
}
}
}
},
"/v1/dify/tools/governance/team-members": {
"post": {
"tags": [
"governance"
],
"summary": "List team members for the current scope",
"description": "Returns members of teams within the active scope. Used by Generative UI dropdowns to populate user selection.",
"operationId": "governanceListTeamMembers",
"parameters": [
{
"$ref": "#/components/parameters/NodeId"
},
{
"$ref": "#/components/parameters/ScopeId"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"team_id": {
"type": "string",
"description": "Optional team filter"
},
"role": {
"type": "string",
"description": "Optional role filter"
},
"limit": {
"type": "integer",
"default": 50,
"maximum": 200
}
}
}
}
}
},
"responses": {
"200": {
"description": "Member list",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ToolResponse"
}
}
}
},
"401": {
"$ref": "#/components/responses/Unauthorized"
},
"503": {
"$ref": "#/components/responses/ToolUnavailable"
}
}
}
},
"/v1/dify/tools/bus/emit-event": {
"post": {
"tags": [
"bridge"
],
"summary": "Route a command to any bridge service",
"description": "Generalized bridge command router. Publishes commands to NATS and waits for correlated responses from bridge services (usafiri, medusa, killbill, zammad, synapse, jitsi). Falls back to L3 HTTP if NATS is unavailable.",
"operationId": "busEmitEvent",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"service",
"command"
],
"properties": {
"service": {
"type": "string",
"enum": [
"usafiri",
"medusa",
"killbill",
"zammad",
"synapse",
"jitsi"
],
"description": "Bridge service name"
},
"command": {
"type": "string",
"description": "Command name (e.g. order.create, driver.ensure)"
},
"payload": {
"type": "object",
"description": "Command payload"
},
"subject": {
"type": "string",
"description": "Alternative: explicit NATS subject (parsed for service/command)"
},
"org_id": {
"type": "string",
"description": "Organization ID for scope resolution"
},
"timeout_ms": {
"type": "integer",
"description": "Response timeout in milliseconds",
"default": 15000
}
}
}
}
}
},
"responses": {
"200": {
"description": "Bridge command result",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"data": {
"type": "object"
},
"event_id": {
"type": "string"
},
"transport": {
"type": "string",
"enum": [
"nats",
"http"
]
}
}
}
}
}
}
}
}
},
"/v1/dify/tools/openapi.json": {
"get": {
"tags": [
"truth-graph"
],
"summary": "Dify Tools OpenAPI spec (self-describing)",
"description": "Returns the OpenAPI 3.1 spec for Dify Agent tools. Dify consumes this URL as a Custom Tool endpoint.",
"operationId": "getDifyToolOpenApi",
"responses": {
"200": {
"description": "OpenAPI spec JSON",
"content": {
"application/json": {
"schema": {
"type": "object"
}
}
}
}
}
}
},
"/v1/dify/tools/templates/render": {
"post": {
"tags": [
"templates"
],
"summary": "Render a message template with variables",
"description": "Fetches a message template by ID, replaces {{variable}} placeholders with provided values, and returns the rendered HTML/CSS. Used by Dify agents to render email, chat, or push notification templates before sending.",
"operationId": "templatesRender",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": [
"template_id"
],
"properties": {
"template_id": {
"type": "string",
"description": "Template ID (e.g., tmpl_xxxxx or message_template:xxxxx)"
},
"variables": {
"type": "object",
"description": "Key-value pairs for {{variable}} replacement",
"additionalProperties": {
"type": "string"
}
}
}
}
}
}
},
"responses": {
"200": {
"description": "Rendered template",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"data": {
"type": "object",
"properties": {
"html": {
"type": "string",
"description": "Rendered HTML with variables replaced"
},
"css": {
"type": "string",
"description": "Rendered CSS"
},
"subject": {
"type": "string",
"description": "Rendered email subject (if email template)"
},
"plain_text": {
"type": "string",
"description": "Plain text version (HTML stripped)"
},
"template_name": {
"type": "string"
},
"template_type": {
"type": "string"
},
"channel": {
"type": "string"
}
}
}
}
}
}
}
},
"404": {
"$ref": "#/components/responses/NotFound"
}
}
}
}
},
"components": {
"parameters": {
"NodeId": {
"name": "X-Node-Id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Current truth node context injected by BFF from Dify chat"
},
"ScopeId": {
"name": "X-Scope-Id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Current vault scope injected by BFF from Dify chat"
},
"UserId": {
"name": "X-User-Id",
"in": "header",
"required": true,
"schema": {
"type": "string"
},
"description": "Original user ID extracted from service JWT"
}
},
"responses": {
"Unauthorized": {
"description": "Missing or invalid service JWT",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
},
"NotFound": {
"description": "Resource not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ToolResponse"
}
}
}
},
"LeaseDenied": {
"description": "Active vault_access_lease required for this vault scope",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ToolResponse"
}
}
}
},
"GovernanceDenied": {
"description": "Action blocked by ABAC governance policy",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ToolResponse"
}
}
}
},
"ToolUnavailable": {
"description": "Tool gateway timeout or circuit breaker open",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorEnvelope"
}
}
}
}
},
"schemas": {
"ErrorEnvelope": {
"type": "object",
"properties": {
"ok": {
"type": "boolean",
"const": false
},
"error": {
"type": "string"
},
"code": {
"type": "string"
}
}
},
"ToolResponse": {
"type": "object",
"properties": {
"ok": {
"type": "boolean"
},
"data": {
"type": "object"
},
"error": {
"type": "string"
},
"poce_session_id": {
"type": "string"
},
"latency_ms": {
"type": "integer"
}
}
}
},
"securitySchemes": {
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT (service JWT minted via @jamii/iam-client/service-jwt)"
}
}
},
"security": [
{
"BearerAuth": []
}
]
}