Diana API Documentation

Amazon Seller Intelligence Assistant API

Version: 1.0.0
Last Updated: February 18, 2025

Overview

Diana is an AI-powered assistant designed specifically for Amazon sellers. The API provides natural language interactions with your Amazon seller data, enabling you to analyze performance, identify trends, and receive actionable insights through simple conversational queries.

Authentication

API Keys

All requests to the Diana API require an API key. You can generate and manage your API keys in the Diana Developer Dashboard.

curl -X POST https://api.diana.ai/v1/query \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "query": "Show me my top 5 products by revenue this month"
  }'

Amazon Seller Account Connection

Before using Diana, you must connect your Amazon Seller Central account. This can be done through the Diana dashboard or programmatically using the OAuth flow described below.

API Endpoints

Query Endpoint

POST /v1/query

The primary endpoint for interacting with Diana. Send natural language queries about your Amazon seller data and receive structured responses.

Request Parameters

Example Request

{
  "query": "What are my top 3 best-selling products in the last quarter?",
  "marketplace": "US",
  "timeframe": "last_quarter",
  "format": "json"
}

Example Response

{
  "request_id": "req_8f7223a1c5",
  "result": {
    "top_products": [
      {
        "asin": "B08KT7XHZY",
        "title": "Premium Bamboo Cutting Board Set",
        "units_sold": 2347,
        "revenue": 42246.00,
        "profit_margin": 27.4,
        "growth_rate": 14.2
      },
      {
        "asin": "B09D3WBQRL",
        "title": "Organic Cotton Bath Towels - 4 Pack",
        "units_sold": 1982,
        "revenue": 39640.00,
        "profit_margin": 32.1,
        "growth_rate": 8.7
      },
      {
        "asin": "B07VDTN42L",
        "title": "Smart Kitchen Timer - Voice Activated",
        "units_sold": 1855,
        "revenue": 37100.00,
        "profit_margin": 24.8,
        "growth_rate": -2.3
      }
    ],
    "analysis": {
      "summary": "Your top-selling products had strong performance in Q4, with two showing positive growth compared to previous quarter. The Smart Kitchen Timer has seen a slight decline, potentially due to increased competition in the category.",
      "recommendation": "Consider bundling the Smart Kitchen Timer with complementary products to increase its appeal and reverse the negative trend."
    }
  },
  "metadata": {
    "processing_time": "0.743s",
    "data_freshness": "2025-02-17T23:00:00Z",
    "query_understanding": {
      "intent": "product_performance_analysis",
      "filters": {
        "timeframe": "2024-Q4",
        "marketplace": "US",
        "metrics": ["units_sold", "revenue"],
        "limit": 3
      }
    }
  }
}

Data Insights Endpoint

POST /v1/insights

Generate automated insights about your seller account without requiring a specific query.

Request Parameters

Example Request

{
  "insight_type": "opportunities",
  "marketplace": "US",
  "detail_level": "detailed"
}

Account Connection Endpoint

POST /v1/connect

Initiate the OAuth flow to connect an Amazon Seller Central account.

Request Parameters

Data Models

Product Performance

{
  "asin": "string",
  "title": "string",
  "category": "string",
  "subcategory": "string",
  "metrics": {
    "units_sold": "number",
    "revenue": "number",
    "profit": "number",
    "profit_margin": "number",
    "refund_rate": "number",
    "review_rating": "number",
    "review_count": "number",
    "conversion_rate": "number",
    "page_views": "number",
    "organic_rank": "number"
  },
  "trends": {
    "growth_rate": "number",
    "price_history": "array",
    "seasonality_index": "number"
  }
}

Inventory Status

{
  "asin": "string",
  "sku": "string",
  "fnsku": "string",
  "condition": "string",
  "inventory_level": "number",
  "available_quantity": "number",
  "reserved_quantity": "number",
  "fulfillment_type": "string",
  "inbound_quantity": "number",
  "days_of_supply": "number",
  "restock_recommendation": {
    "recommended_quantity": "number",
    "urgency": "string",
    "optimal_po_date": "string"
  }
}

Common Use Cases

Performance Analysis

"How did my sales this month compare to last month?"
"Show me products with declining reviews in the last 60 days"
"Calculate my profit margins by category"

Inventory Management

"Which products are at risk of stockout in the next 30 days?"
"What's my current inventory value across all warehouses?"
"Calculate optimal restock quantities for my top sellers"

Competitive Intelligence

"How are my main competitors pricing the bamboo cutting board category?"
"Show me gaps in my product catalog compared to top sellers"
"Analyze Buy Box win rate trends over the last quarter"

Advertising Optimization

"What's my ACOS by campaign this month?"
"Show me keywords with high conversion but low impression share"
"Recommend bid adjustments to improve ROAS"

Rate Limits and Quotas

Rate limits reset at midnight UTC.

Best Practices

1. Be specific with timeframes - Include specific date ranges in your queries for more accurate results
2. Leverage context - Diana maintains conversation context, so follow-up questions work naturally
3. Use comparison queries - Ask for comparative analysis (e.g., "this month vs. last month")
4. Request actionable insights - Ask "what should I do about..." for recommendations
5. Export data - Use the format parameter to export results for further analysis

Error Handling

Diana API uses standard HTTP response codes:

• 200: Success
• 400: Bad request (query formatting issue)
• 401: Unauthorized (invalid API key)
• 403: Forbidden (permissions issue)
• 404: Not found
• 429: Too many requests (rate limit exceeded)
• 500: Server error

Detailed error responses include:

{
  "error": {
    "code": "invalid_query",
    "message": "Unable to understand the query. Please rephrase or provide more context.",
    "request_id": "req_7d6e240af1",
    "suggestions": [
      "Try specifying a timeframe",
      "Clarify which marketplace you're interested in",
      "Specify product categories if applicable"
    ]
  }
}

Webhooks

Diana supports webhooks for asynchronous notification of important events and completed analysis tasks.

POST /v1/webhooks

Configure endpoints to receive notifications about:

• Data refresh completions
• Long-running analysis completions
• Anomaly detections
• Inventory alerts
• Price change detections

For additional support, contact api-support@diana.ai or visit our Developer Community.