Skip to main content

​
Send a query

POST /api/workspaces/:id/query
Runs the agent loop for the specified workspace. Connects to MCP servers, discovers tools, invokes the language model, executes tool calls, and returns the answer. Request body:
FieldTypeRequiredDescription
querystringYesThe user’s question
session_idstringNoSession identifier for multi-turn conversations
historyarrayNoPrior message history ([{role, content}])
Example: 
curl -X POST https://your-instance/api/workspaces/ws-example/query \
  -H "Content-Type: application/json" \
  -H "Cookie: supaproxy_session=YOUR_JWT" \
  -d '{
    "query": "What is the status of order ORD-2026-001?",
    "session_id": "session-123"
  }'
Response: 
{
  "answer": "Order ORD-2026-001 is currently DELIVERED. It was shipped on April 15 and delivered on April 17.",
  "tools_called": ["get_order_status"],
  "connections_hit": ["order-service"],
  "tokens": {"input": 860, "output": 310},
  "cost_usd": 0.008,
  "duration_ms": 2340,
  "error": null,
  "conversation_id": "conv-abc123",
  "session_id": "session-123"
}

​
What happens during a query

  1. Load workspace config: model, system prompt, max tool rounds
  2. Find or create conversation: uses session_id or creates a new conversation
  3. Load conversation history: prior messages for context
  4. Connect to MCP servers: establish connections to all workspace MCP servers
  5. Discover tools: call tools/list on each connection
  6. Agent loop: send query + tools to the language model; execute tool calls; repeat until text response
  7. Record: save messages to conversation, create audit log entry
  8. Return: answer, tools called, cost, duration

​
Errors

If a query fails, the error field contains the error message. The answer field may still contain a partial response. 
{
  "answer": "",
  "tools_called": [],
  "connections_hit": [],
  "tokens": {"input": 0, "output": 0},
  "cost_usd": 0,
  "duration_ms": 150,
  "error": "MCP connection failed: order-service is unreachable",
  "conversation_id": "conv-abc123",
  "session_id": "session-123"
}