Market Analysis API

Start AI-powered market analysis jobs to monitor prices and availability across marketplaces.

Endpoints Overview

Method	Endpoint	Description
POST	`/product-market-analysis-jobs/create`	Create a market analysis job
POST	`/product-market-analysis-jobs/get`	List market analysis jobs
POST	`/product-market-analysis-jobs/{job_id}/items/get`	Get analysis results
POST	`/product-market-analysis-jobs/{job_id}/stop`	Stop a running job

Create Market Analysis Job

Start a new market analysis job to track marketplace data for multiple products.

Endpoint: POST /api/{organization}/product-market-analysis-jobs/create

Request Body

Field	Type	Required	Description
`productIds`	string[]	Yes	Array of product IDs to analyze (1 or more, no fixed maximum)
`modelType`	string	Yes	AI model to use (see below)

Model Types

Model	Description
`budget-v1`	Balanced speed and search depth
`pro-v1`	Extended search across more marketplaces

Example Request

curl -X POST https://catalog-ai.tdcapps.com/api/your-org/product-market-analysis-jobs/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "productIds": ["prod_abc123", "prod_def456"],
    "modelType": "pro-v1"
  }'

Response

{
  "success": true,
  "data": {
    "jobId": "job_mkl987",
    "status": "pending",
    "totalProducts": 2,
    "modelType": "pro-v1",
    "createdAt": "2024-01-15T14:00:00Z"
  }
}

List Market Analysis Jobs

Retrieve a paginated list of market analysis jobs.

Endpoint: POST /api/{organization}/product-market-analysis-jobs/get

Request Body

Field	Type	Required	Default	Description
`page`	number	No	1	Page number
`limit`	number	No	10	Items per page (max 100)

Get Job Items

Retrieve detailed marketplace results for products within an analysis job.

Endpoint: POST /api/{organization}/product-market-analysis-jobs/{job_id}/items/get

Path Parameters

Parameter	Type	Required	Description
`job_id`	string	Yes	Job ID

Request Body

Field	Type	Required	Default	Description
`limit`	number	No	50	Items per page (max 100)
`offset`	number	No	0	Offset for pagination

Response

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "item_mkl111",
        "jobId": "job_mkl987",
        "productId": "prod_abc123",
        "status": "completed",
        "results": [
          {
            "id": "res_aaa111",
            "source": "Amazon",
            "price": 99.99,
            "originalPrice": 129.99,
            "currency": "USD",
            "availability": "In Stock",
            "link": "https://amazon.com/product/..."
          },
          {
            "id": "res_bbb222",
            "source": "Walmart",
            "price": 95.5,
            "currency": "USD",
            "availability": "Out of Stock",
            "link": "https://walmart.com/product/..."
          }
        ]
      }
    ]
  }
}

Stop Market Analysis Job

Stop a running or pending market analysis job.

Endpoint: POST /api/{organization}/product-market-analysis-jobs/{job_id}/stop

Path Parameters

Parameter	Type	Required	Description
`job_id`	string	Yes	ID of the job to stop

Response

{
  "success": true,
  "message": "Market Analysis job stopped successfully",
  "data": {
    "jobId": "job_mkl987",
    "status": "stopped"
  }
}