Conversation API

Build interactive AI chat experiences with memory, context, and document-grounded responses.

Conversation Overview

The Conversation API allows you to create stateful chat interfaces where the AI remembers previous messages and can leverage your document collections to provide accurate, knowledge-grounded responses. It also supports advanced features like function calling through tools.

Typical Conversation Flow with Tools

Understanding the conversation flow is crucial when implementing tool/function calling. Here's a typical interaction sequence:

🔄 Conversation Flow Example

User sends initial message - Creates a new conversation
→ POST /messages with user message and tools array
Bot responds - Either with a direct answer or tool request
← Returns response or tool_calls with conversation_id
User asks follow-up question - Continues conversation
→ POST /messages with conversation_id and new message
Bot triggers tool call - Requests external data/action
← Returns type: "tool_calls" with tool details
Client executes tool - Runs the requested function locally
⚡ Your application handles the tool execution
Submit tool results - Send results back (no user message)
→ POST /messages with tool_results array (no message field)
Bot uses results - Generates final response using tool data
← Returns response incorporating the tool results

⚠️ Important: When submitting tool results (step 6), do NOT include a "message" field - only "tool_results".

Create or Continue a Conversation

Send a message to create a new conversation or continue an existing one.

POST /messages

Request Parameters

Parameter	Type	Required	Description
user	string	Yes	A unique identifier for the end user
message	string	Yes*	The user's message (required unless tool_results is provided)
conversation	string	No	Conversation ID from a previous response (omit to create a new conversation)
system_context	string	No	System instructions for the AI
user_context	string	No	User-specific context to guide the conversation
collections	array	No	Array of collection IDs to use for knowledge retrieval
role	string	No	Message role: "user" (default), "assistant", "system", or "tool"
tools	array	No	Array of tools the AI can use (for function calling)
tool_results	array	No	Results from tool execution (for function calling responses)
no_tools	boolean	No	If true, disables tool usage for this request

Starting a New Conversation

cURL

curl -X POST https://api.vectorforgeai.com/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Team-Token: YOUR_TEAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "user_12345",
    "message": "What are the key features of VectorForgeAI?",
    "system_context": "You are a helpful AI assistant for VectorForgeAI. Provide accurate information about our product.",
    "collections": ["abc123xyz456", "def456uvw789"]
  }'

Response

JSON

{
  "id": "resp_assi_xyz123abc456",
  "type": "response",
  "conversation_id": "jkl789mno012",
  "response": "VectorForgeAI offers several key features:\n\n1. Document Collections: Organize and manage your knowledge base efficiently\n2. Vector Embedding: Convert text into semantic vectors for advanced search\n3. Semantic Search: Find information based on meaning, not just keywords\n4. LLM Integration: Generate AI responses grounded in your data\n5. Conversation API: Build interactive chat experiences with context and memory\n\nThese features enable you to create powerful AI applications that can understand and retrieve information from your documents with high accuracy.",
  "documents": [
    {
      "identifier": "features-overview",
      "title": "VectorForgeAI Features",
      "body_intro": "VectorForgeAI offers a comprehensive set of features designed for knowledge management and retrieval...",
      "metadata": {
        "category": "Product"
      }
    }
  ],
  "messages": [
    {
      "id": "mess_user_abc123def456",
      "role": "user",
      "content": "What are the key features of VectorForgeAI?",
      "timestamp": "2025-05-10T08:42:15.123Z"
    },
    {
      "id": "resp_assi_xyz123abc456",
      "role": "assistant",
      "content": "VectorForgeAI offers several key features:\n\n1. Document Collections: Organize and manage your knowledge base efficiently\n2. Vector Embedding: Convert text into semantic vectors for advanced search\n3. Semantic Search: Find information based on meaning, not just keywords\n4. LLM Integration: Generate AI responses grounded in your data\n5. Conversation API: Build interactive chat experiences with context and memory\n\nThese features enable you to create powerful AI applications that can understand and retrieve information from your documents with high accuracy.",
      "timestamp": "2025-05-10T08:42:17.456Z"
    }
  ]
}

Continuing a Conversation

cURL

curl -X POST https://api.vectorforgeai.com/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Team-Token: YOUR_TEAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "user_12345",
    "conversation": "jkl789mno012",
    "message": "How does the vector search feature work?"
  }'

Retrieve Conversation History

Get the message history for a specific conversation.

GET /messages/{conversation_id}

Path Parameters

Parameter	Type	Description
conversation_id	string	ID of the conversation to retrieve

Request

cURL

curl -X GET https://api.vectorforgeai.com/v1/messages/jkl789mno012 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Team-Token: YOUR_TEAM_TOKEN"

Response

JSON

{
  "messages": [
    {
      "id": "mess_user_abc123def456",
      "role": "user",
      "content": "What are the key features of VectorForgeAI?",
      "timestamp": "2025-05-10T08:42:15.123Z"
    },
    {
      "id": "resp_assi_xyz123abc456",
      "role": "assistant",
      "content": "VectorForgeAI offers several key features:...",
      "timestamp": "2025-05-10T08:42:17.456Z"
    },
    {
      "id": "mess_user_ghi789jkl012",
      "role": "user",
      "content": "How does the vector search feature work?",
      "timestamp": "2025-05-10T08:44:35.789Z"
    },
    {
      "id": "resp_assi_pqr456stu789",
      "role": "assistant",
      "content": "Vector search works by converting your query into a numerical vector representation...",
      "timestamp": "2025-05-10T08:44:38.123Z"
    }
  ]
}

Delete a Conversation

Permanently delete a conversation and all its associated messages.

DELETE /messages/{conversation_id}

Path Parameters

Parameter	Type	Description
conversation_id	string	ID of the conversation to delete

Request

cURL

curl -X DELETE https://api.vectorforgeai.com/v1/messages/jkl789mno012 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Team-Token: YOUR_TEAM_TOKEN"

Response

JSON

{
  "message": "Conversation deleted successfully."
}

Advanced Features

Tool/Function Calling

The Conversation API supports function calling through tools, allowing the AI to request specific actions when needed.

Tools Example

curl -X POST https://api.vectorforgeai.com/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Team-Token: YOUR_TEAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "user_12345",
    "message": "What\'s the weather in New York?",
    "system_context": "You are a helpful assistant that can access external services when needed.",
    "tools": [
      {
        "name": "get_weather",
        "description": "Get current weather information for a location",
        "parameters": [
          {
            "name": "location",
            "type": "string",
            "description": "The city and state or country",
            "required": true
          },
          {
            "name": "units",
            "type": "string",
            "description": "Temperature units (celsius or fahrenheit)",
            "required": false
          }
        ]
      }
    ]
  }'

Tool Response Example

JSON

{
  "type": "tool_calls",
  "conversation_id": "vwx345yz678",
  "tool_calls": [
    {
      "id": "call_123456789",
      "name": "get_weather",
      "arguments": {
        "location": "New York, NY",
        "units": "fahrenheit"
      }
    }
  ]
}

Submitting Tool Results

cURL

curl -X POST https://api.vectorforgeai.com/v1/messages \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Team-Token: YOUR_TEAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "user": "user_12345",
    "conversation": "vwx345yz678",
    "tool_results": [
      {
        "tool_id": "call_123456789",
        "tool_name": "get_weather",
        "arguments": {
          "location": "New York, NY",
          "units": "fahrenheit"
        },
        "result": {
          "temperature": 72,
          "condition": "Sunny",
          "humidity": 45,
          "wind": "5 mph"
        }
      }
    ]
  }'

Document Grounding

When you specify collections in your request, the conversation API automatically retrieves relevant documents to ground the AI's responses in your data. The system:

Analyzes the conversation context and recent messages
Performs vector search across the specified collections
Retrieves the most relevant documents
Uses these documents as context for generating the response
Returns both the AI response and the relevant documents in the response

💡 Knowledge-Grounded AI

For the most accurate, up-to-date responses, be sure to keep your document collections updated with current information. The AI will prioritize information from your documents over its general knowledge when answering queries.

Best Practices

User Identification: Use consistent user IDs to maintain separate conversation contexts for different users.
System Context: Provide clear instructions in system_context to guide the AI's behavior and response style.
Document Collections: Include relevant document collections to ensure responses are grounded in your data.
Tool Design: When using tools, design them with clear names, descriptions, and parameter requirements.
Error Handling: Implement robust error handling for cases where the API might return non-standard responses.

Next Steps

To build more interactive AI experiences, explore:

Conversation Feedback - Collect and manage user feedback on AI responses

API Documentation

Conversation API

Conversation Overview

Typical Conversation Flow with Tools

Create or Continue a Conversation

Request Parameters

Starting a New Conversation

Response

Continuing a Conversation

Retrieve Conversation History

Path Parameters

Request

Response

Delete a Conversation

Path Parameters

Request

Response

Advanced Features

Tool/Function Calling

Tool Response Example

Submitting Tool Results

Document Grounding

Best Practices

Next Steps

Need Help?