logo

Bidventor Powered API

Amazon Ads Optimization API

Upload your Amazon Ads Excel reports and get AI-powered optimization recommendations

Authentication

Set your API key to test authenticated endpoints

Getting Started

1. Get API Key

Generate from your dashboard

2. Upload Excel File

Use the upload endpoint with your API key

3. Check Status

Monitor processing with the status endpoint

Rate Limits

Basic Tier
100/day
File Size Limit
500MB
Processing Time
~30 seconds

Quick Links

POST
/api/upload-secured
API Key

Upload Amazon Ads Excel reports for AI-powered optimization analysis

Parameters

file
File
Required
Amazon Ads Excel report (.xlsx only, max 500MB) - Campaign, Keyword, or Product Targeting reports
uploadId
string
Required
Unique identifier for tracking this upload (auto-generated if not provided)
totalChunks
string
Required
Total number of chunks (use "1" for single file upload)
fileName
string
Required
Original filename of the uploaded file
complete
string
Set to "true" for complete file upload (default: "false")

Test This Endpoint

API Key Required

Only upload ID is required - other fields are auto-generated

Response

200
File uploaded and processed successfully
{
  "success": true,
  "message": "File processed successfully",
  "uploadId": "test_1234567890_abc123",
  "results": {
    "campaigns": 15,
    "keywords": 245,
    "productTargets": 23,
    "optimizations": 67,
    "data": {
      "campaign_optimizations": [
        {
          "campaign_id": "123456789",
          "campaign_name": "Summer Sale Campaign",
          "current_bid": 1.25,
          "suggested_bid": 1.45,
          "reason": "High ROAS (4.2), low CPC ($0.85)",
          "confidence": 0.92
        }
      ],
      "keyword_optimizations": [
        {
          "keyword_id": "kw_987654321",
          "keyword_text": "wireless headphones",
          "current_bid": 0.75,
          "suggested_bid": 0.95,
          "reason": "High conversion rate (8.5%), good search volume",
          "confidence": 0.88
        }
      ],
      "product_targeting_optimizations": [
        {
          "target_id": "pt_123456789",
          "targeting_expression": "Electronics > Audio > Headphones",
          "current_bid": 0.6,
          "suggested_bid": 0.8,
          "reason": "Strong performance, expanding reach",
          "confidence": 0.85
        }
      ]
    }
  },
  "metadata": {
    "apiKeyId": "key_123",
    "userId": "user_456",
    "requestId": "req_789",
    "processedAt": "2024-01-01T00:00:00Z",
    "tier": "BASIC",
    "processingTime": 12.5,
    "computeUnits": 2600,
    "fileSize": "2.3MB",
    "recordsProcessed": 1247
  }
}

Error Responses

400
Invalid File Type
{
  "error": "Invalid file type. Please upload .xlsx",
  "message": "Only Excel (.xlsx) files are supported",
  "code": "INVALID_FILE_TYPE"
}
403
Insufficient Permissions
{
  "error": "Insufficient permissions",
  "message": "This API key does not have upload permissions",
  "code": "UPLOAD_PERMISSION_DENIED"
}
413
File Too Large
{
  "error": "File too large",
  "message": "File size exceeds 500MB limit",
  "code": "FILE_TOO_LARGE"
}
GET
/api/upload-secured
API Key

Check API key status and upload permissions

Test This Endpoint

API Key Required

Response

200
API key validation successful
{
  "success": true,
  "message": "API key is valid and has upload permissions",
  "apiKey": {
    "id": "key_123",
    "name": "Production Key",
    "tier": "BASIC",
    "permissions": {
      "canUpload": true,
      "canDownload": true,
      "canViewAnalytics": true
    }
  },
  "user": {
    "id": "user_456",
    "email": "user@example.com",
    "name": "John Doe",
    "role": "user"
  },
  "limits": {
    "maxRequestSize": "500MB",
    "rateLimit": "10 requests per minute"
  },
  "backend": {
    "url": "http://localhost:8000",
    "status": "configured"
  }
}

Error Responses

400
Invalid File Type
{
  "error": "Invalid file type. Please upload .xlsx",
  "message": "Only Excel (.xlsx) files are supported",
  "code": "INVALID_FILE_TYPE"
}
403
Insufficient Permissions
{
  "error": "Insufficient permissions",
  "message": "This API key does not have upload permissions",
  "code": "UPLOAD_PERMISSION_DENIED"
}
413
File Too Large
{
  "error": "File too large",
  "message": "File size exceeds 500MB limit",
  "code": "FILE_TOO_LARGE"
}
GET
/api/status
Public

Check processing status of an upload

Parameters

uploadId
string
Required
Upload ID to check status for

Test This Endpoint

💡 Tip: Use this endpoint to check the status of your upload after processing. You'll get the upload ID from the upload response.

Response

200
Upload status retrieved
{
  "uploadId": "test_1234567890_abc123",
  "status": "Completed",
  "progress": 100,
  "completed": true,
  "results": {
    "campaigns": 15,
    "keywords": 245,
    "productTargets": 23,
    "optimizations": 67
  },
  "processingTime": 12.5
}