Discover Competitors

POSThttps://api.boringmarketing.com/brands/{brand_id}/discover-competitors

Uses Tavily research to find business, SERP, and content competitors for your brand. Competitors are classified by type and tier.

Duration: 2-5 minutes.

Path parameters

brand_idstringrequired

The brand UUID.

Query parameters

persistbooleandefault: true

Whether to save the discovered competitors to the brand record. Set to false to preview results without mutating the brand. This is a query parameter, not a request body field — pass it as ?persist=false on the URL.

Response (202 Accepted)

{
  "run_id": "run-uuid",
  "status": "queued"
}

Discovered competitors are added to the brand's competitor list (when persist=true, the default). View them via GET /brands/{id}.

Errors

Status	Meaning
`404`	Brand not found, or not owned by the caller.
`409`	Returned when (a) another `competitor_discovery` run is already active for this brand, or (b) a `full` (`/analyze`) run is currently writing to all tables. Other partial runs do not block this endpoint. Header: `X-Running-Run-Id`. Active runs older than 15 minutes are auto-expired and do not count.
`422`	`brand_id` is not a valid UUID.

Example

# Persist to brand (default)
curl -X POST \
  -H "X-API-Key: $BM_API_KEY" \
  https://api.boringmarketing.com/brands/$BRAND_ID/discover-competitors

# Preview without mutating the brand
curl -X POST \
  -H "X-API-Key: $BM_API_KEY" \
  "https://api.boringmarketing.com/brands/$BRAND_ID/discover-competitors?persist=false"

The full pipeline (/analyze) triggers competitor discovery automatically if no competitors are set. Use this endpoint when you want to refresh competitors independently.