Skip to main content

Competitors API

The Competitors API allows you to track and manage competitor information in your workspace.

List Competitors​

Get all competitors for your workspace. Optionally filter by product ID.

GET /api/competitors?productId={productId}

Query Parameters​

  • productId (string, optional) - Filter competitors by product ID

Response​

{
  "competitors": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "workspaceId": "workspace-id",
      "name": "Competitor Inc",
      "websiteUrl": "https://competitor.com",
      "status": "COMPLETE",
      "tags": ["enterprise", "saas"],
      "priority": 1,
      "tier": "TIER_1",
      "refreshRate": 30,
      "products": [],
      "categories": [],
      "relevantProductIds": ["product-id-1"],
      "lastRefreshAt": "2024-01-01T00:00:00.000Z",
      "lastBattlecardAt": "2024-01-01T00:00:00.000Z",
      "createdAt": "2024-01-01T00:00:00.000Z"
    }
  ]
}

Status Values​

  • PENDING - Competitor is being set up
  • PROCESSING - Competitor analysis is in progress
  • COMPLETE - Competitor analysis is complete
  • ERROR - An error occurred during analysis

Get Competitor​

Get a specific competitor by ID, including active jobs.

GET /api/competitors/{id}

Path Parameters​

  • id (string, required) - Competitor ID

Response​

{
  "competitor": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspaceId": "workspace-id",
    "name": "Competitor Inc",
    "websiteUrl": "https://competitor.com",
    "status": "COMPLETE",
    "tags": [],
    "priority": 1,
    "tier": "TIER_1",
    "refreshRate": 30,
    "products": [],
    "categories": [],
    "relevantProductIds": ["product-id-1"],
    "lastRefreshAt": "2024-01-01T00:00:00.000Z",
    "lastBattlecardAt": "2024-01-01T00:00:00.000Z",
    "createdAt": "2024-01-01T00:00:00.000Z"
  },
  "currentJob": {
    "id": "job-id",
    "status": "running",
    "progress": 50,
    "currentStep": "Processing Intel"
  }
}

Create Competitor​

Create a new competitor. Requires EDITOR role or higher. Enforces plan limits on competitor count.

POST /api/competitors

Request Body​

{
  "name": "Competitor Inc",
  "websiteUrl": "https://competitor.com",
  "isFirstRun": true,
  "relevantProductIds": ["product-id-1", "product-id-2"]
}

Required Fields​

  • name (string) - Competitor company name
  • websiteUrl (string) - Competitor website URL (must be valid URL)

Optional Fields​

  • isFirstRun (boolean) - Whether this is the first run (triggers full pipeline). Defaults to false
  • relevantProductIds (array of strings) - Product IDs this competitor competes against

Response​

{
  "competitor": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspaceId": "workspace-id",
    "name": "Competitor Inc",
    "websiteUrl": "https://competitor.com",
    "status": "PENDING",
    "tags": [],
    "priority": 1,
    "tier": "TIER_3",
    "refreshRate": 90,
    "products": [],
    "categories": [],
    "relevantProductIds": ["product-id-1"],
    "createdAt": "2024-01-01T00:00:00.000Z"
  },
  "jobId": "job-id-for-tracking-analysis"
}

The competitor will automatically start analysis. Use the returned jobId to track progress via the Jobs API.

Update Competitor​

Update a competitor. Requires EDITOR role or higher.

PATCH /api/competitors/{id}

Path Parameters​

  • id (string, required) - Competitor ID

Request Body​

All fields are optional. Only include fields you want to update:

{
  "name": "Updated Competitor Name",
  "websiteUrl": "https://updated-competitor.com",
  "tags": ["enterprise", "saas"],
  "priority": 2,
  "products": [],
  "categories": [],
  "relevantProductIds": ["product-id-1"],
  "companyProfile": {},
  "companyStrengths": [],
  "companyWeaknesses": [],
  "referenceLinks": [],
  "keyMessaging": []
}

Response​

{
  "competitor": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspaceId": "workspace-id",
    "name": "Updated Competitor Name",
    "websiteUrl": "https://updated-competitor.com",
    "status": "COMPLETE",
    "tags": ["enterprise", "saas"],
    "priority": 2,
    "tier": "TIER_1",
    "refreshRate": 30,
    "products": [],
    "categories": [],
    "relevantProductIds": ["product-id-1"],
    "lastRefreshAt": "2024-01-01T00:00:00.000Z",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

Delete Competitor​

Delete a competitor. Requires EDITOR role or higher.

DELETE /api/competitors/{id}

Path Parameters​

  • id (string, required) - Competitor ID

Response​

{
  "success": true
}

Error Responses​

  • 400 - Bad Request (missing required fields, invalid URL)
  • 401 - Unauthorized (invalid or missing API key)
  • 403 - Forbidden (insufficient permissions or plan limit exceeded)
  • 404 - Not Found (competitor doesn't exist)

Plan Limit Error​

If you've reached your plan's competitor limit, you'll receive a 403 error:

{
  "error": {
    "code": "UPGRADE_REQUIRED",
    "message": "You've reached your STARTER plan limit of 5 competitors. Upgrade to add more competitors.",
    "currentPlan": "STARTER",
    "requiredPlan": "PRO",
    "limit": 5,
    "currentCount": 5
  }
}