Update API docs for 2.4 (#960)

- Update API specs for 2.4 (#960)
- Update API docs
- Regenerate Python docs

specs/api/paths/flow/agent.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     AI agent that can understand questions, reason about them, and take actions.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Agent Overview
 
     The agent service provides a conversational AI that:

specs/api/paths/flow/document-embeddings.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Query document embeddings to find similar text chunks by vector similarity.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Document Embeddings Query Overview
 
     Find document chunks semantically similar to a query vector:

specs/api/paths/flow/document-load.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Load binary documents (PDF, Word, etc.) into processing pipeline.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Document Load Overview
 
     Fire-and-forget binary document loading:

specs/api/paths/flow/document-rag.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Retrieval-Augmented Generation over document embeddings.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Document RAG Overview
 
     Document RAG combines:

specs/api/paths/flow/embeddings.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Convert text to embedding vectors for semantic similarity search.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Embeddings Overview
 
     Embeddings transform text into dense vector representations that:

specs/api/paths/flow/graph-embeddings.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Query graph embeddings to find similar entities by vector similarity.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Graph Embeddings Query Overview
 
     Find entities semantically similar to a query vector:

specs/api/paths/flow/graph-rag.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Retrieval-Augmented Generation over knowledge graph.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Graph RAG Overview
 
     Graph RAG combines:

specs/api/paths/flow/mcp-tool.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Execute MCP (Model Context Protocol) tools for agent capabilities.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## MCP Tool Overview
 
     MCP tools provide agent capabilities through standardized protocol:

specs/api/paths/flow/nlp-query.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Convert natural language questions to structured GraphQL queries.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## NLP Query Overview
 
     Transforms user questions into executable GraphQL:

specs/api/paths/flow/prompt.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Execute stored prompt templates with variable substitution.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Prompt Service Overview
 
     The prompt service enables:

specs/api/paths/flow/row-embeddings.yaml

@@ -4,6 +4,11 @@ post:
   summary: Row Embeddings Query - semantic search on structured data
   description: |
     Query row embeddings to find similar rows by vector similarity on indexed fields.
+
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     Enables fuzzy/semantic matching on structured data.
 
     ## Row Embeddings Query Overview

specs/api/paths/flow/rows.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Query structured data using GraphQL for row-oriented data access.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Rows Query Overview
 
     GraphQL interface to structured data:

specs/api/paths/flow/sparql-query.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Execute a SPARQL 1.1 query against the knowledge graph.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Supported Query Types
 
     - **SELECT**: Returns variable bindings as a table of results

specs/api/paths/flow/structured-diag.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Analyze and understand structured data (CSV, JSON, XML).
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Structured Diag Overview
 
     Helps process unknown structured data:

specs/api/paths/flow/structured-query.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Ask natural language questions and get results directly.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Structured Query Overview
 
     Combines two operations in one call:

specs/api/paths/flow/text-completion.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Direct text completion using LLM without retrieval augmentation.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Text Completion Overview
 
     Pure LLM generation for:

specs/api/paths/flow/text-load.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Load text documents into processing pipeline for indexing and embedding.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Text Load Overview
 
     Fire-and-forget document loading:

specs/api/paths/flow/triples.yaml

@@ -5,6 +5,10 @@ post:
   description: |
     Query knowledge graph using subject-predicate-object patterns.
 
+    This is a **flow-scoped** service. It requires a flow instance
+    and operates within the workspace associated with the
+    authenticated bearer token.
+
     ## Triples Query Overview
 
     Query RDF triples with flexible pattern matching: