Making Requests

1. The /v1/analyze Endpoint

bashCopy codePOST https://api.damasco.ai/v1/analyze

1.1 Purpose

This endpoint allows you to analyze a single user message (or chunk of text) to determine factors such as:

• Sentiment (positive, negative, or neutral)

• Objective (e.g., "Improve customer satisfaction" or "Gather sales information")

• Potential Risk Indicators like hacking attempts, security breaches, or inappropriate content.

1.2 Request Structure

Headers

• Authorization: Bearer <YOUR_API_KEY>

  • Replace <YOUR_API_KEY> with the key you generated from https://damasco.ai/dashboard/.

• Content-Type: application/json

Body (JSON)

jsoncCopy code{
  "message": "I have a question about pricing and discounts for your product."
}

Field	Type	Required	Description
message	String	Yes	The text content to be analyzed. The AI will parse this text and return classification fields.

Additional or Custom Fields While message is the primary required field, future versions or enterprise features may support optional metadata or user context. For now, keep your requests minimal: just pass the message string.

---

2. Understanding the Response

A successful response typically contains 9 fields, each helping you understand the message’s classification and risk level. Here is a sample response body:

jsoncCopy code{
  "success": true,
  "objective": "Gather sales information",
  "sentiment": "positive",
  "ai_score": 0.85,
  "inappropriate_score": 0.02,
  "hack_score": 0.00,
  "security_breach": false,
  "support_request": false,
  "sales_request": true
}

2.1 Response Fields

Field	Type	Description
success	Boolean	Indicates whether the request was processed successfully. true if everything went fine.
objective	String	Summarizes the primary goal of the message (e.g., “Gather sales information”).
sentiment	String	The emotional tone of the text. Can be "positive", "negative", or "neutral".
ai_score	Float	Confidence (0–1) that the AI’s classification is accurate. Higher = more confident.
inappropriate_score	Float	Likelihood (0–1) that the content is inappropriate/offensive. 0 = none, 1 = extremely offensive.
hack_score	Float	Likelihood (0–1) of hacking or code-injection content. 0 = none, 1 = definite hacking attempt.
security_breach	Boolean	true if a potential security issue is detected (e.g., leaking confidential data).
support_request	Boolean	true if the message is recognized as a support or customer service inquiry.
sales_request	Boolean	true if the message is related to sales (pricing, product details, etc.).

---

3. Example Request & Response

Below is a Python code snippet demonstrating how to POST a user message to the /v1/analyze endpoint and interpret the result.

3.1 Python Example

pythonCopy codeimport os
import requests

# Retrieve your API key (best stored as an environment variable for security)
API_KEY = os.getenv("MY_API_KEY")  
url = "https://api.damasco.ai/v1/analyze"

# The message we want the AI to analyze
payload = {
    "message": "Can you tell me if there's a discount available for your subscription plan?"
}

# Construct the request
response = requests.post(
    url,
    headers={
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
    },
    json=payload
)

# Parse the JSON response
result = response.json()

# Check 'success' and handle accordingly
if result.get("success"):
    print("Request processed successfully!")
    print("Objective:", result.get("objective"))
    print("Sentiment:", result.get("sentiment"))
    print("AI Score:", result.get("ai_score"))
    print("Sales Request:", result.get("sales_request"))
else:
    print("Request failed or encountered an error.")
    print(result)

3.2 Possible Response

jsonCopy code{
  "success": true,
  "objective": "Gather sales information",
  "sentiment": "positive",
  "ai_score": 0.92,
  "inappropriate_score": 0.00,
  "hack_score": 0.00,
  "security_breach": false,
  "support_request": false,
  "sales_request": true
}

Interpretation:

• success = true: The request was valid and processed.

• objective = "Gather sales information"`: The user is asking about discounts, so the system classifies it as a sales inquiry.

• sentiment = "positive"`: The user’s tone is friendly or enthusiastic.

• sales_request = true: Confirms that the message is sales-related.

---

4. Additional Implementation Tips

1. Error Handling

   • Watch for non-200 HTTP status codes.

   • Error responses may include "success": false and an "error" field describing the issue (e.g., “Invalid API Key” or “Malformed Request”).

2. Performance

   • The complexity of AI analysis may impact response time.

   • For low-latency needs, ensure your messages are concise. Handling extremely long text might slow processing.

3. Security

   • Do not expose your API key in client-side code.

   • If your environment demands extra protection, consider rotating keys periodically.

4. Metrics & Logging

   • You can store results (objective, sentiment, etc.) in your logs or analytics dashboards to monitor user inquiries over time.

   • For advanced analytics (e.g., aggregated stats, date-range queries), see if the optional GET /v1/stats endpoint is available on your plan.

5. Possible Customization

   • Enterprise editions may include deeper classification (e.g., sub-categories under “support_request”) or advanced detection.

   • If you have specialized needs (like detecting competitor mentions or code samples), contact us at [e-mail].

---

5. Example Use Cases

1. Live Chat Routing

   • If sales_request = true, forward the conversation to a sales rep.

   • If support_request = true, route to a customer service queue.

2. Negative Sentiment Alerts

   • If sentiment = "negative", flag for immediate review to prevent churn or escalate to a manager.

3. Security Monitoring

   • If security_breach = true or hack_score is high, block or quarantine the request and notify your security team.

---

6. Summary

• Endpoint: POST /v1/analyze

• Required Request Field: message

• Response: A comprehensive JSON object detailing success, sentiment, AI confidence, risk indicators, and more.

By following the steps above, you can seamlessly integrate the analysis endpoint into your workflow, ensuring you capture real-time insights into user intent, emotional tone, and potential security issues.

---

Need More Help?

• Support: [e-mail]

• Dashboard: https://damasco.ai/dashboard/ for key management and usage stats

With this guide, you should feel confident in making requests to our new API. Experiment with real user messages, build workflows around the returned fields, and leverage the insights to optimize user engagement and safeguard your platform.