​
AI Copilot API

The AI Copilot API provides a conversational interface for trading strategy creation. Users engage in a multi-turn conversation with an AI agent that guides them through strategy definition, signal selection, strategy assembly, and backtesting.

​
Base URL

http://localhost:5001/api/v1/ai-copilot

​
Workflow States

The AI Copilot follows a 5-state workflow: 
collect_user_input -> plan_signals -> assemble_strategy -> backtest -> done
  1. collect_user_input — Conversationally collect strategy requirements
  2. plan_signals — Map user intent to signals from the registry
  3. assemble_strategy — Build a complete strategy configuration
  4. backtest — Execute historical testing and evaluate metrics
  5. done — Terminal state for follow-up questions

​
Endpoints

​
Create Conversation

POST /start_new_conversation 
curl -X POST http://localhost:5001/api/v1/ai-copilot/start_new_conversation \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "org_id": "00000000-0000-0000-0000-000000000001",
    "user_id": "00000000-0000-0000-0000-000000000002"
  }'
Response: 
{
  "success": true,
  "conversation": {
    "session_id": "d09aa986-56e5-498f-88c0-51967b6a452b",
    "current_mode": "collect_user_input",
    "created_at": "2025-11-15T09:35:08.672065+00:00"
  }
}

​
Send Message

POST /chat/{session_id}
This is an asynchronous endpoint. It returns 202 Accepted immediately. Poll GET /conversations/{session_id} to retrieve the agent’s response.
curl -X POST http://localhost:5001/api/v1/ai-copilot/chat/$SESSION_ID \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "message": "I want to buy ETH when RSI drops below 30 and we are above the 50-day SMA"
  }'
Async Processing Model:
  1. Send message — returns 202 immediately
  2. Poll GET /conversations/{session_id} every 1-2 seconds
  3. Check if conversation_history length increased
  4. Read the newest message for the agent’s response

​
Get Conversation Context

GET /conversations/{session_id} Returns the complete working context including conversation history and current state. 
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:5001/api/v1/ai-copilot/conversations/$SESSION_ID"

​
List Conversations

GET /list_conversations 
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:5001/api/v1/ai-copilot/list_conversations"

​
Get Latest Conversation

GET /get_latest_conversation

​
Rename Conversation

PUT /conversations/{session_id}/rename 
curl -X PUT "http://localhost:5001/api/v1/ai-copilot/conversations/$SESSION_ID/rename" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title": "BTC Momentum Strategy Discussion"}'

​
Delete Conversation

DELETE /conversations/{session_id} 
curl -X DELETE "http://localhost:5001/api/v1/ai-copilot/conversations/$SESSION_ID" \
  -H "Authorization: Bearer $TOKEN"

​
Save Strategy

POST /save_strategy Persists a generated strategy to the database.

​
Get Configuration

GET /configuration Returns available configuration files for the AI agent.

​
Refresh Vector Database (Admin)

POST /admin/refresh-vector-db Refresh the RAG vector database. Requires management key. 
curl -X POST "http://localhost:5001/api/v1/ai-copilot/admin/refresh-vector-db" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Management-Key: YOUR_MGMT_KEY"

​
Conversation Example

# Step 1: Create session
SESSION_ID=$(curl -s -X POST http://localhost:5001/api/v1/ai-copilot/start_new_conversation \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"org_id": "org-uuid", "user_id": "user-uuid"}' | jq -r '.conversation.session_id')

# Step 2: Describe strategy
curl -X POST http://localhost:5001/api/v1/ai-copilot/chat/$SESSION_ID \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"message": "Buy BTC when 20-day RSI drops below 30, sell when it rises above 70"}'

# Step 3: Poll for response
sleep 5
curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:5001/api/v1/ai-copilot/conversations/$SESSION_ID"

# Step 4: Provide additional details when asked
curl -X POST http://localhost:5001/api/v1/ai-copilot/chat/$SESSION_ID \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"message": "Use 4-hour timeframe, 2% stop loss"}'

​
Best Practices

  1. Be specific — Include asset, timeframes, entry/exit conditions, and risk parameters
  2. Answer questions completely — The agent asks up to 5 clarification questions per state
  3. Review proposed rules — Verify the signal mapping matches your intent
  4. Monitor context size — Larger contexts take longer to process
  5. Save session ID — Sessions persist indefinitely unless deleted