Battlecards API

The Battlecards API allows you to retrieve and manage battlecards generated for your competitors.

List Battlecards

Get all battlecards for your workspace. Optionally filter by product ID or competitor ID.

GET /api/battlecards?productId={productId}&competitorId={competitorId}

Query Parameters

• productId (string, optional) - Filter battlecards by product ID
• competitorId (string, optional) - Filter battlecards by competitor ID

Response

{
  "battlecards": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "workspaceId": "workspace-id",
      "competitorId": "competitor-id",
      "myProductId": "product-id",
      "mode": "ATTACK",
      "content": {
        "whyWeWin": [
          {
            "title": "Superior Feature",
            "description": "We have better features",
            "evidenceIds": ["evidence-id-1", "evidence-id-2"]
          }
        ],
        "whyWeLose": [
          {
            "title": "Competitor Advantage",
            "description": "They have better pricing",
            "evidenceIds": ["evidence-id-3"]
          }
        ],
        "objections": [],
        "talkingPoints": []
      },
      "evidenceIds": ["evidence-id-1", "evidence-id-2", "evidence-id-3"],
      "createdAt": "2024-01-01T00:00:00.000Z"
    }
  ]
}

Mode Values

• ATTACK - Battlecard for competitive selling situations
• DEFENSE - Battlecard for defending against competitor pitches

Get Battlecard

Get a specific battlecard by ID. Optionally include evidence details.

GET /api/battlecards/{id}?includeEvidence=true

Path Parameters

• id (string, required) - Battlecard ID

Query Parameters

• includeEvidence (boolean, optional) - Include detailed evidence information. Defaults to false

Response (without evidence)

{
  "battlecard": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspaceId": "workspace-id",
    "competitorId": "competitor-id",
    "myProductId": "product-id",
    "mode": "ATTACK",
    "content": {
      "whyWeWin": [],
      "whyWeLose": [],
      "objections": [],
      "talkingPoints": []
    },
    "evidenceIds": [],
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
}

Response (with evidence)

{
  "battlecard": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspaceId": "workspace-id",
    "competitorId": "competitor-id",
    "myProductId": "product-id",
    "mode": "ATTACK",
    "content": {
      "whyWeWin": [
        {
          "title": "Superior Feature",
          "description": "We have better features",
          "evidenceIds": ["evidence-id-1"]
        }
      ],
      "whyWeLose": [],
      "objections": [],
      "talkingPoints": []
    },
    "evidenceIds": ["evidence-id-1"],
    "createdAt": "2024-01-01T00:00:00.000Z"
  },
  "evidence": {
    "evidence-id-1": {
      "id": "evidence-id-1",
      "content": "Evidence content text",
      "sourceType": "WEB_PAGE",
      "url": "https://example.com/source",
      "title": "Source Title",
      "credibilityScore": 0.95
    }
  }
}

Generate Battlecard

Generate a new battlecard for a competitor and product combination.

POST /api/battlecards/{competitorId}/generate

Path Parameters

• competitorId (string, required) - Competitor ID

Request Body

{
  "productId": "product-id",
  "mode": "ATTACK"
}

Required Fields

• productId (string) - Product ID to generate battlecard for
• mode (string) - Battlecard mode: "ATTACK" or "DEFENSE"

Response

{
  "battlecard": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "workspaceId": "workspace-id",
    "competitorId": "competitor-id",
    "myProductId": "product-id",
    "mode": "ATTACK",
    "content": {
      "whyWeWin": [],
      "whyWeLose": [],
      "objections": [],
      "talkingPoints": []
    },
    "evidenceIds": [],
    "createdAt": "2024-01-01T00:00:00.000Z"
  },
  "jobId": "job-id-for-tracking-generation"
}

Battlecard generation runs asynchronously. Use the returned jobId to track progress via the Jobs API.

Error Responses

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