Conversation API

The Conversation API enables intelligent, context-aware interactions with your data through natural language queries and AI-powered responses. It provides a complete conversational interface for data analysis and insights generation.

Overview

The API consists of four main components:

• Thread Management: Create and manage conversation contexts
• Message Operations: Send queries and receive AI responses
• AI Insights: Generate automated insights from data and interactions
• Utility Functions: Additional tools for data presentation and analysis

Thread Management

Threads provide conversational context for AI interactions, maintaining state across multiple queries and responses. Each thread is associated with a specific data index and includes visualization context.

List All Threads

Retrieve all conversation threads for your account.

Endpoint: GET /fino/threads

Request

curl -X GET "https://app.infino.ws/fino/threads" \
  -H "Authorization: AWS4-HMAC-SHA256 Credential=IAK_ExampleKey123456/20240120/us-east-1/es/aws4_request, SignedHeaders=host;x-amz-date, Signature=abc123..." \
  -H "Host: app.infino.ws" \
  -H "X-Amz-Date: 20240120T123000Z"

Response

[
  {
    "id": "thread-uuid-123",
    "name": "Sales Analysis Thread",
    "index_name": "sales-data",
    "status": "ongoing",
    "created_at": "2024-01-20T10:30:00Z",
    "updated_at": "2024-01-20T12:15:00Z",
    "viz_context": {
      "dashboard_type": "analytics",
      "filters": {"region": "north_america"}
    },
    "workflow_name": "alpha_v1"
  },
  {
    "id": "thread-uuid-456", 
    "name": "Customer Insights",
    "index_name": "customer-logs",
    "status": "completed",
    "created_at": "2024-01-19T14:20:00Z", 
    "updated_at": "2024-01-19T16:45:00Z",
    "viz_context": {
      "filters": {"date_range": "last_7_days"}
    },
    "workflow_name": "alpha_v1"
  }
]

Create New Thread

Start a new conversation thread with specified context and settings.

Endpoint: POST /fino/threads

Request

{
  "name": "Q1 Revenue Analysis",
  "index_name": "revenue-data",
  "status": "ongoing",
  "viz_context": {
    "dashboard_type": "financial",
    "time_range": "Q1_2024",
    "chart_preferences": ["time_series", "pie_chart"]
  },
  "workflow_name": "alpha_v1"
}

Request Parameters

Parameter	Type	Required	Description
name	string	Yes	Human-readable thread name
index_name	string	Yes	Target data index for queries
status	string	No	Thread status (ongoing, completed, paused)
viz_context	object	No	Visualization and UI context
workflow_name	string	No	AI workflow version (default: alpha_v1)

Response

{
  "id": "thread-uuid-789",
  "name": "Q1 Revenue Analysis", 
  "index_name": "revenue-data",
  "status": "ongoing",
  "created_at": "2024-01-20T12:30:00Z",
  "updated_at": "2024-01-20T12:30:00Z",
  "viz_context": {
    "dashboard_type": "financial",
    "time_range": "Q1_2024", 
    "chart_preferences": ["time_series", "pie_chart"]
  },
  "workflow_name": "alpha_v1"
}

Example

curl -X POST "https://app.infino.ws/fino/threads" \
  -H "Authorization: AWS4-HMAC-SHA256 Credential=IAK_ExampleKey123456/20240120/us-east-1/es/aws4_request, SignedHeaders=host;x-amz-date, Signature=def456..." \
  -H "Host: app.infino.ws" \
  -H "X-Amz-Date: 20240120T123000Z" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Behavior Analysis",
    "index_name": "user-events", 
    "status": "ongoing",
    "viz_context": {
      "dashboard_type": "behavioral",
      "time_range": "last_30_days",
      "segments": ["new_users", "returning_users"]
    },
    "workflow_name": "alpha_v1"
  }'

Get Specific Thread

Retrieve details for a specific thread, including full context and schema information.

Endpoint: GET /fino/threads/{thread_id}

Request

curl -X GET "https://app.infino.ws/fino/threads/thread-uuid-123" \
  -H "Authorization: AWS4-HMAC-SHA256 Credential=IAK_ExampleKey123456/20240120/us-east-1/es/aws4_request, SignedHeaders=host;x-amz-date, Signature=ghi789..." \
  -H "Host: app.infino.ws" \
  -H "X-Amz-Date: 20240120T123000Z"

Response

{
  "id": "thread-uuid-123",
  "name": "Sales Analysis Thread",
  "index_name": "sales-data", 
  "status": "ongoing",
  "created_at": "2024-01-20T10:30:00Z",
  "updated_at": "2024-01-20T12:15:00Z",
  "viz_context": {
    "dashboard_type": "analytics",
    "filters": {"region": "north_america"}
  },
  "workflow_name": "alpha_v1",
  "user_context": "Analyzing sales performance trends across regions",
  "system_context": "Sales data with transaction details and customer information",
  "schema": "{\"fields\": [{\"name\": \"sales_amount\", \"type\": \"float\"}, {\"name\": \"date\", \"type\": \"date\"}, {\"name\": \"region\", \"type\": \"keyword\"}]}"
}

Update Thread

Modify thread properties including name, status, and visualization context.

Endpoint: PUT /fino/threads/{thread_id}

Request

{
  "name": "Updated Sales Analysis",
  "status": "completed", 
  "viz_context": {
    "dashboard_type": "analytics",
    "filters": {"region": "global"},
    "chart_type": "time_series",
    "insights_enabled": true
  }
}

Response

{
  "id": "thread-uuid-123",
  "name": "Updated Sales Analysis",
  "index_name": "sales-data",
  "status": "completed",
  "created_at": "2024-01-20T10:30:00Z", 
  "updated_at": "2024-01-20T13:15:00Z",
  "viz_context": {
    "dashboard_type": "analytics", 
    "filters": {"region": "global"},
    "chart_type": "time_series",
    "insights_enabled": true
  },
  "workflow_name": "alpha_v1"
}

Delete Thread

Permanently remove a thread and all associated messages.

Endpoint: DELETE /fino/threads/{thread_id}

Request

curl -X DELETE "https://app.infino.ws/fino/threads/thread-uuid-123" \
  -H "Authorization: AWS4-HMAC-SHA256 Credential=IAK_ExampleKey123456/20240120/us-east-1/es/aws4_request, SignedHeaders=host;x-amz-date, Signature=jkl012..." \
  -H "Host: app.infino.ws" \
  -H "X-Amz-Date: 20240120T123000Z"

Response

true

Irreversible Action

Deleting a thread permanently removes all messages and context. This action cannot be undone.

Message Operations

Create Message

Add a message to a conversation thread and receive an AI-generated response.

Endpoint: POST /fino/message

Request

{
  "thread_id": "thread-uuid-123",
  "content": {
    "user_query": "What are the top selling products this month?",
    "context": "monthly_sales_analysis",
    "filters": {
      "date_range": "2024-01-01_to_2024-01-31",
      "category": "all"
    }
  },
  "role": "user"
}

Request Parameters

Parameter	Type	Required	Description
thread_id	string	Yes	UUID of the conversation thread
content	object	Yes	Message content and context
content.user_query	string	Yes	Natural language query
content.context	string	No	Context identifier for the query
content.filters	object	No	Additional filters or parameters
role	string	Yes	Message role (user or assistant)

Response

true

The API returns true on successful message creation. The AI response is delivered through the WebSocket connection or can be retrieved via thread message history.

Example: Sales Analysis Query

curl -X POST "https://app.infino.ws/fino/message" \
  -H "Authorization: AWS4-HMAC-SHA256 Credential=IAK_ExampleKey123456/20240120/us-east-1/es/aws4_request, SignedHeaders=host;x-amz-date, Signature=abc123..." \
  -H "Host: app.infino.ws" \
  -H "X-Amz-Date: 20240120T123000Z" \
  -H "Content-Type: application/json" \
  -d '{
    "thread_id": "thread-uuid-sales-001",
    "content": {
      "user_query": "Show me revenue trends for the electronics category",
      "context": "revenue_analysis", 
      "filters": {
        "category": "electronics",
        "time_period": "last_quarter"
      }
    },
    "role": "user"
  }'

Example: Customer Analysis Query

curl -X POST "https://app.infino.ws/fino/message" \
  -H "Authorization: AWS4-HMAC-SHA256 Credential=IAK_ExampleKey123456/20240120/us-east-1/es/aws4_request, SignedHeaders=host;x-amz-date, Signature=def456..." \
  -H "Host: app.infino.ws" \
  -H "X-Amz-Date: 20240120T123000Z" \
  -H "Content-Type: application/json" \
  -d '{
    "thread_id": "thread-uuid-customer-002", 
    "content": {
      "user_query": "Which customers have the highest lifetime value?",
      "context": "customer_analysis",
      "filters": {
        "metric": "lifetime_value", 
        "limit": 20
      }
    },
    "role": "user"
  }'

Add Message to Thread

Add a message directly to a specific thread using the thread-specific endpoint.

Endpoint: POST /fino/threads/{thread_id}/messages

Request

{
  "content": {
    "user_query": "Show me sales trends for Q4",
    "context": "quarterly_analysis",
    "parameters": {
      "quarter": "Q4_2023",
      "metrics": ["revenue", "units_sold"]
    }
  },
  "role": "user"
}

Response

true

Clear Thread Messages

Remove all messages from a thread while preserving the thread context.

Endpoint: DELETE /fino/threads/{thread_id}/messages

Response

{
  "status": "success",
  "message": "All messages cleared from thread",
  "thread_id": "thread-uuid-123", 
  "deleted_count": 15
}

Reference

Thread Status Values

Status	Description
ongoing	Active thread accepting new messages
completed	Finished analysis, read-only mode
paused	Temporarily suspended, can be resumed
archived	Long-term storage, limited access

Context Persistence

Messages within the same thread maintain conversational context, enabling follow-up questions and iterative analysis without repeating context.