Endpoints Overview

1. POST /v1/analyze

Purpose Analyzes a single user message or piece of text, applying AI-driven classification and returning structured results such as sentiment, objective, or sales_request.

Endpoint

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

Request

Headers

• Authorization: Bearer <YOUR_API_KEY>

  • Replace <YOUR_API_KEY> with the key obtained from your dashboard.

• Content-Type: application/json

Body (JSON)

jsoncCopy code{
  "message": "How much does your product cost? I'd love to know more!"
}

Field	Type	Required	Description
message	String	Yes	The text to analyze. The API will parse and classify this text, returning a standardized response object.

Response

Body (JSON)

A typical successful response includes fields like success, objective, and various confidence scores. Below is the full structure:

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

Field	Type	Description
success	Boolean	Indicates request success. true if the message was processed successfully; false if an error occurred.
objective	String	Summarizes the primary goal or topic of the message.
sentiment	String	Emotional tone detected: can be "positive", "negative", or "neutral".
ai_score	Float	Confidence (0 to 1) in the AI’s overall classification (higher = more confident).
inappropriate_score	Float	Measures how likely the message contains offensive or inappropriate content (0 = clean, 1 = extremely offensive).
hack_score	Float	Indicates potential hacking attempts or suspicious code (0 = none, 1 = definite hacking attempt).
security_breach	Boolean	True if the message suggests a possible security breach (e.g., leaking confidential info).
support_request	Boolean	True if the AI classifies the text as a support or technical help inquiry.
sales_request	Boolean	True if the AI identifies the text as a sales or commercial inquiry (e.g., pricing, product details).

Example Usage

• Sentiment Monitoring: Spot negative feedback quickly.

• Routing: If support_request is true, automatically assign to your support team. If sales_request is true, route to Sales.

• Analytics: Keep track of how many messages have a high inappropriate_score or how often security_breach is flagged.

---

2. GET /v1/health

Purpose A lightweight health-check endpoint to confirm the service is running. Typically used for monitoring or load balancer readiness checks.

Endpoint

bashCopy codeGET https://api.damasco.ai/v1/health

Request

Headers

• (Optional) Authorization: Bearer <YOUR_API_KEY>

  • Some deployments may not require authorization for health checks.

Query Parameters

• None

Response

jsonCopy code{
  "status": "ok"
}

Field	Type	Description
status	String	Often returns "ok" if the service is operational.

Notes

• Responses may differ slightly (e.g., "running" or an HTTP 200 status alone).

• No classification or advanced analysis is performed here—just a simple check to confirm the API is reachable.

---

3. (Optional) GET /v1/logs

Note: This endpoint may be reserved for enterprise plans or advanced usage.

Purpose Retrieves a recent history of analyzed messages or their summaries, enabling you to audit how the system classified your requests. Useful for QA, debugging, or usage analytics.

Endpoint

bashCopy codeGET https://api.damasco.ai/v1/logs

Request

Headers

• Authorization: Bearer <YOUR_API_KEY>

Query Parameters

• limit (integer, optional)

  • Max number of logs to return. Defaults to a system value if not provided.

• offset (integer, optional)

  • For pagination; skip the first offset logs.

Response

jsoncCopy code{
  "logs": [
    {
      "timestamp": "2025-01-06T15:35:00Z",
      "message": "How can I access your private API docs?",
      "sentiment": "neutral",
      "ai_score": 0.78,
      "security_breach": true
    },
    {
      "timestamp": "2025-01-06T15:36:22Z",
      "message": "I'd like more info on your pricing tiers.",
      "sentiment": "positive",
      "ai_score": 0.95,
      "sales_request": true
    }
  ],
  "total": 2
}

Field	Type	Description
logs	Array	List of recent analysis results. Each array element may include partial fields (e.g., security_breach, sales_request).
total	Integer	The total number of log entries in the system or relevant to the current query.

Notes

• For privacy/security, the stored message text might be truncated or masked according to your organizational settings.

• Larger queries might be paginated; watch for limit and offset usage.

---

4. (Optional) GET /v1/stats

Note: This endpoint may or may not be available depending on your subscription or plan.

Purpose Provides aggregate statistics about message classifications, sentiment distributions, or other usage metrics. Great for dashboards or KPI reporting.

Endpoint

bashCopy codeGET https://api.damasco.ai/v1/stats

Request

Headers

• Authorization: Bearer <YOUR_API_KEY>

Query Parameters

• start_date, end_date (string, optional)

  • Filter stats by date range in ISO 8601 format (e.g., 2025-01-01T00:00:00Z).

Response

jsoncCopy code{
  "total_requests": 150,
  "sentiment_breakdown": {
    "positive": 100,
    "neutral": 40,
    "negative": 10
  },
  "top_objectives": [
    {"objective": "gather sales information", "count": 60},
    {"objective": "technical support", "count": 30},
    {"objective": "general info", "count": 20}
  ]
}

Field	Type	Description
total_requests	Number	The number of POST /v1/analyze calls made during the specified timeframe.
sentiment_breakdown	Object	A summary of how many times each sentiment category was detected (positive, neutral, negative).
top_objectives	Array of Obj	The most common objectives, each with a count representing frequency.

Notes

• This data can be used in performance dashboards, monthly reports, or decision-making tools.

---

Authentication & Errors

• Authentication: Pass Bearer <YOUR_API_KEY> in the Authorization header for all requests (except possibly GET /v1/health).

• Error Handling: The API uses standard HTTP status codes (4xx, 5xx) and may return a JSON body describing the error. For example:

  jsonCopy code{
    "success": false,
    "error": "Invalid API Key or permission denied"
  }

---

Summary

• POST /v1/analyze: Main endpoint for classifying user messages.

• GET /v1/health: Quick way to check if the service is online.

• GET /v1/logs (Optional/Enterprise): Retrieve or audit past requests.

• GET /v1/stats (Optional): Aggregate metrics for deeper insights.