V1 CORE SERVICES

Insightarc REST API Documentation

Integrate seamless, proactive hospitality intelligence directly into your platform. Our RESTful architecture utilizes standardized JSON payloads and predictable, resource-oriented endpoints.

info AI-Native Context

Our API is designed specifically to enrich AI assistants and support chats with real-time user context and intent to mitigate hallucinations and enable next-best actions.

key

lock Authentication

All requests must be authenticated using a Bearer token provided in the Authorization header. Retrieve your API key from the developer dashboard.

terminal Bash

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

Core API Methods

GET /context/history/{customerId}

Retrieve Historical Context

Retrieve historical user behavior data and analytics for a specific customer.

Parameters

customerId

string *required Unique customer identifier.

limit

int (Default: 10) Limit on the number of intents to return.

time_range

string (e.g. "7d", "30d") Time window for analysis.

Response Example

200 OK application/json

{
  "customerId": "user_67890",
  "stats": {
    "bought": false,
    "engagement_rate": 78.5,
    "type_of_signal": "reg",
    "avg_see_page": 45.2,
    "is_bot": false
  },
  "intents": [...]
}

GET /context/realtime/{sessionId}

Retrieve Real-Time Context

Retrieve data about the user's active session and current intent.

Parameters

sessionId

string *required Active session identifier.

Response Example

200 OK application/json

{
  "sessionId": "sess_xyz789",
  "stats": {
    "engagement_rate": 92.0,
    "type_of_signal": "after_buy",
    "avg_see_page": 120.4,
    "is_bot": false
  },
  "current_intent": {...}
}

Data Structure

analytics Statistics Fields

bought bool (true/false)

engagement_rate float (0-100)

type_of_signal drop, reg, after_buy

is_bot bool (true/false)

shopping_bag Intent Structure

{
  "url": "https://example.com/p/1",
  "name": "Luxury Suite",
  "category": "hospitality",
  "price_amount": 299.99,
  "price_cur": "USD",
  "timestamp": "2024-02-20..."
}

smart_toy

Powering AI

LLM Prompt Integration

Use our intent data to dynamically generate prompts that guide LLM chatbots toward higher conversion.

Python Example

prompt = f"""
The user shows signs of 
losing interest (signal: {signal_type}). 
Recommended Actions:
- If engagement < 40: offer discount
- If signal is 'drop': ask a help question
"""

Result for LLM

"The user viewed Luxury Suite but the engagement rate is low (35%). Recommendation: Ask if they need help with booking or offer a 10% seasonal discount."

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

Integration Examples

Request Historical Context (cURL)

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)

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

Frequently Asked Questions

How often is real-time data updated?

A: Data is updated every 5 seconds. For more frequent updates, consider using WebSockets.

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.

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).

Need help with integration?

Our developer support team is available for 1-on-1 implementation calls.