API documentation

Insightarc REST API Documentation for AI assistants and support chats Integration.

Table of Contents

1. Core API Methods
2. Data Structure
3. Request and Response Examples
4. Use Case: Generating Prompts for LLM Chatbot
5. Error Codes
6. Integration Examples
7. FAQs
8. Support

---

Core API Methods

1. GET /context/history/{customerId}

Purpose:
Retrieve historical user behavior data and analytics.

Parameters:

Parameter	Type	Required	Description
customerId	string	Yes	Unique customer identifier
limit	int	No	Limit on the number of intents (default: 10)
time_range	string	No	Time filter (format: "7d", "30d")
sessions_limit	int	No	Maximum number of sessions to analyze

---

2. GET /context/realtime/{sessionId}

Purpose:
Retrieve data about the user's current session.

Parameters:

Parameter	Type	Required	Description
sessionId	string	Yes	Active session identifier

---

Data Structure

Statistics Fields

Field	Type	Description	Possible Values
bought	bool	Flag indicating a completed purchase	true/false
engagement_rate	float	Percentage of user journey completion	0-100
type_of_signal	string	Session status	drop, reg, after_buy, null
avg_see_page	float	Average time spent on pages (in seconds)
is_bot	bool	Flag indicating bot-like behavior	true/false

Intent Structure

{
  "url": "https://example.com/product/123",
  "name": "Product Name",
  "category": "electronics",
  "price_amount": 299.99,
  "price_cur": "USD",
  "timestamp": "2024-02-20T14:30:00Z"
}

---

Request and Response Examples

1. Historical Context (with Filters)

Request:

GET /context/history/user_67890?limit=3&time_range=7d

Response:

{
  "customerId": "user_67890",
  "stats": {
    "bought": false,
    "engagement_rate": 78.5,
    "type_of_signal": "reg",
    "avg_see_page": 45.2,
    "is_bot": false
  },
  "intents": [
    {
      "url": "https://store.com/doctors/smith",
      "name": "Dr. Smith Consultation",
      "category": "medical",
      "price_amount": 0.0,
      "price_cur": "USD",
      "timestamp": "2024-03-01T09:15:00Z"
    }
  ]
}

2. Real-Time Context (After Purchase)

Request:

GET /context/realtime/sess_xyz789

Response:

{
  "sessionId": "sess_xyz789",
  "stats": {
    "engagement_rate": 92.0,
    "type_of_signal": "after_buy",
    "avg_see_page": 120.4,
    "is_bot": false
  },
  "current_intent": {
    "url": "https://store.com/thank-you",
    "name": "Order Confirmation",
    "category": "system",
    "price_amount": 0.0,
    "price_cur": "USD"
  }
}

---

Use Case: Generating Prompts for LLM Chatbot

Example API Data:

{
  "stats": {
    "type_of_signal": "drop",
    "engagement_rate": 35.0
  },
  "intents": [
    {
      "name": "Nike Air Max 90",
      "category": "sneakers",
      "price_amount": 150.0
    }
  ]
}

Prompt Template:

prompt = f"""
The user shows signs of losing interest (signal: {signal_type}). 
Browsing history: {products}. 
Recommend Next-Best Actions based on the data:

- If engagement_rate < 40: offer a discount
- If category is 'sneakers': show similar models
- If signal is 'drop': ask a clarifying question
"""

Result for LLM:

"The user viewed Nike Air Max 90, but the engagement rate is low (35%). 
Recommendations: 
1. Offer a 10% discount on this item. 
2. Show alternative sneakers: Adidas Ultraboost, New Balance 574. 
3. Ask a question: 'Do you need help with sizing?'"

---

Error Codes

Code	Status	Description
200	OK	Successful request
400	Bad Request	Invalid parameters
404	Not Found	User/session not found
429	Too Many Requests	Rate limit exceeded
500	Server Error	Internal server error

---

Integration Examples

cURL Example

Request Historical Context:

curl -X GET "https://api.insightarc.com/context/history/user_67890?limit=3&time_range=7d" \
-H "Authorization: Bearer YOUR_API_KEY"

Request Real-Time Context:

curl -X GET "https://api.insightarc.com/context/realtime/sess_xyz789" \
-H "Authorization: Bearer YOUR_API_KEY"

---

FAQs

Q: How often is real-time data updated?
A: Data is updated every 5 seconds. For more frequent updates, consider using WebSockets.

Q: What does type_of_signal = null mean?
A: It indicates that the user is in an active session but has not shown clear signs of completion or disengagement.

Q: How is the is_bot flag determined?
A: The is_bot flag is set to true if the system detects suspicious activity (e.g., unusually high action speed).