Skip to main content

Campaign Brief API

The Campaign Brief API accepts uploaded documents (PDFs, Word files, PowerPoint presentations, images, or plain text) and uses Claude to analyze the campaign brief, extracting marketing objectives, target audiences, and recommended audience topics. This endpoint powers the "Upload Brief" feature in the AudienceGPT chatbot, returning structured topic recommendations that can be classified through the standard pipeline.

POST /api/analyze-brief​

Upload and analyze a campaign brief document.

Auth: API key with classify scope, or Clerk session

POST /api/analyze-brief

Request Body​

The request body is JSON (not multipart form data). The file must be base64-encoded.

{
  "file": {
    "data": "JVBERi0xLjQKMS...",
    "mediaType": "application/pdf",
    "filename": "Q1-campaign-brief.pdf"
  }
}
FieldTypeRequiredDescription
file.datastringYesBase64-encoded file content
file.mediaTypestringYesMIME type of the file
file.filenamestringNoOriginal filename (used for display)

Supported Media Types​

MIME TypeFile TypeProcessing
application/pdfPDFDocument block
application/vnd.openxmlformats-officedocument.wordprocessingml.documentDOCXDocument block
application/vnd.openxmlformats-officedocument.presentationml.presentationPPTXDocument block
image/pngPNGImage block
image/jpegJPEGImage block
image/gifGIFImage block
image/webpWebPImage block
text/plainTXTDecoded as text inline
warning

Maximum file size is 10 MB (measured from the base64-encoded payload, which is approximately 4/3 of the original file size).

Response (200)​

The response is a structured JSON object containing the brief analysis and recommended topics:

{
  "summary": "Q1 automotive campaign targeting EV buyers in California with focus on Tesla and Rivian models",
  "objectives": [
    "Drive test drive appointments",
    "Increase brand awareness among eco-conscious consumers"
  ],
  "targetAudience": "Affluent professionals aged 30-55 interested in electric vehicles",
  "recommendedTopics": [
    {
      "topic_name": "Tesla Model 3 Buyers - California",
      "rationale": "Primary vehicle mentioned in brief with California geo-targeting"
    },
    {
      "topic_name": "Rivian R1T Truck Enthusiasts",
      "rationale": "Secondary vehicle brand with adventure lifestyle positioning"
    },
    {
      "topic_name": "EV Charging Infrastructure Interest",
      "rationale": "Brief mentions charging concerns as a consideration factor"
    }
  ]
}

curl Example​

# Base64-encode the file first
BASE64_DATA=$(base64 -i Q1-campaign-brief.pdf)

curl -X POST https://app.audiencegpt.com/api/analyze-brief \
  -H "Authorization: Bearer txadv_your_api_key" \
  -H "Content-Type: application/json" \
  -d "{
    \"file\": {
      \"data\": \"${BASE64_DATA}\",
      \"mediaType\": \"application/pdf\",
      \"filename\": \"Q1-campaign-brief.pdf\"
    }
  }"

TypeScript Example​

async function analyzeBrief(file: File): Promise<BriefAnalysis> {
  // Convert file to base64
  const buffer = await file.arrayBuffer();
  const base64 = btoa(String.fromCharCode(...new Uint8Array(buffer)));

  const response = await fetch("https://app.audiencegpt.com/api/analyze-brief", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      file: {
        data: base64,
        mediaType: file.type,
        filename: file.name,
      },
    }),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error);
  }

  return response.json();
}

SDK Route​

An identical endpoint is available for client-side applications using SDK publishable keys:

POST /api/sdk/analyze-brief

Auth: SDK key (pk_live_ or pk_test_) with classify scope

This endpoint mirrors /api/analyze-brief with the same request/response format, but adds CORS headers for cross-origin browser requests.

CORS Headers​

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization

An OPTIONS preflight handler is included for CORS compliance.

Error Responses​

StatusBodyDescription
400{"error": "file.data (base64) and file.mediaType are required"}Missing file data
400{"error": "Unsupported media type: video/mp4. Accepted: ..."}Invalid MIME type
400{"error": "File exceeds 10MB limit"}File too large
401{"error": "Unauthorized"}Invalid credentials
429{"error": "Monthly classifications quota exceeded (10000 limit)"}Quota exceeded
500{"error": "ANTHROPIC_API_KEY not configured"}Server misconfiguration
502{"error": "Failed to parse analysis response"}AI response parsing failure

Usage Tracking​

Brief analysis counts toward your organization's classification quota. Each brief analysis is tracked as a single classification event with input/output token counts.

Next Steps​