Competitors API

Competitors are tracked within an AIBeam project so you can compare how other brands appear in the same monitored AI responses.

List Competitors

GET /api/v1/projects/:projectId/competitors

Response

The list endpoint returns the competitor table fields plus selected-analysis aggregate metrics when available.

{
  "data": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "project_id": "789a1234-b56c-78d9-e012-f34567890123",
      "name": "TechRival",
      "website_url": "https://techrival.example",
      "description": "Direct competitor in B2B SaaS",
      "discovery_method": "manual",
      "is_active": true,
      "created_at": "2026-02-15T10:30:00Z",
      "updated_at": "2026-03-10T12:00:00Z",
      "total_mentions_count": 42,
      "visibility_score": 68,
      "market_share": 34.4,
      "first_seen_at": "2026-03-01T10:30:00Z",
      "last_seen_at": "2026-03-09T14:22:33Z"
    }
  ]
}

Create Competitor

POST /api/v1/projects/:projectId/competitors

Request Body

Example Request

curl -X POST "https://aibeam.io/api/v1/projects/789a1234-b56c-78d9-e012-f34567890123/competitors" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CloudCompete",
    "website_url": "https://cloudcompete.example",
    "description": "Emerging competitor platform"
  }'

Response

{
  "data": {
    "id": "334e6789-e01d-34f5-c678-648836396222",
    "project_id": "789a1234-b56c-78d9-e012-f34567890123",
    "name": "CloudCompete",
    "website_url": "https://cloudcompete.example",
    "description": "Emerging competitor platform",
    "discovery_method": "manual",
    "is_active": true,
    "created_at": "2026-03-10T09:15:42Z",
    "updated_at": "2026-03-10T09:15:42Z"
  }
}

Delete Competitor

DELETE /api/v1/competitors/:competitorId

Response

{
  "data": {
    "deleted": true
  }
}

Error Responses

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "name is required"
  }
}

Common error codes are VALIDATION_ERROR, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, RATE_LIMIT_EXCEEDED, AIBEAM_KILL_SWITCH_ACTIVE, and INTERNAL_ERROR.

Rate Limiting

Rate limit status is included in response headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 42
X-RateLimit-Reset: 1678512300