AI Refinement API

Endpoints for AI-powered brand profile refinement including usage tracking, preflight validation, and one-shot refinement.

Authentication

All endpoints require JWT authentication via Bearer token.

Endpoints

Get Usage Summary

GET /api/usage

Returns current billing period usage for AI refinement features.

Response

{
  "websiteAnalysis": { "used": 2, "limit": 10 },
  "fieldAnalysis": { "used": 15, "limit": 100 },
  "oneShotRefinement": { "used": 45, "limit": 200 },
  "chatSessions": { "used": 8, "limit": 50 },
  "messagesPerSession": { "limit": 25 }
}

TIP

A limit of -1 indicates unlimited usage for the feature.

---

Get Usage History

GET /api/usage/history?page=1&limit=20&actionType=WEBSITE_ANALYSIS

Query Parameters

Parameter	Type	Description
page	number	Page number (default: 1)
limit	number	Items per page (1-100, default: 20)
actionType	string	Filter by action type (optional)

Action Types: WEBSITE_ANALYSIS, FIELD_ANALYSIS, ONE_SHOT_REFINEMENT, CHAT_SESSION_START, CHAT_MESSAGE

Response

{
  "items": [
    {
      "id": "uuid",
      "actionType": "ONE_SHOT_REFINEMENT",
      "task": "one_shot_refinement",
      "model": "anthropic/claude-haiku-4.5",
      "totalTokens": 1250,
      "totalCostCents": 2,
      "success": true,
      "createdAt": "2024-12-13T16:00:00.000Z"
    }
  ],
  "total": 45,
  "page": 1,
  "limit": 20,
  "totalPages": 3
}

---

Export Usage (CSV)

GET /api/usage/export?format=csv

Downloads usage data as CSV for the current billing period.

---

Company Usage Breakdown

GET /api/usage/company

Returns usage breakdown by team member (admin view).

Response

{
  "totalSpendCents": 125,
  "userBreakdown": [
    {
      "userId": "uuid",
      "userName": "John Doe",
      "userEmail": "john@example.com",
      "websiteAnalysis": 2,
      "fieldAnalysis": 10,
      "oneShotRefinement": 25,
      "chatSessions": 5,
      "totalCostCents": 75
    }
  ]
}

---

Pre-flight URL Check

POST /api/preflight-check

Validates a URL before website analysis. Does not consume credits.

Request

{
  "url": "https://example.com"
}

Response (Success)

{
  "success": true,
  "contentLength": 15420,
  "responseTime": 850
}

Response (Failure)

{
  "success": false,
  "errorCode": "LOGIN_PAGE",
  "message": "This appears to be a login page. Please provide a publicly accessible URL."
}

Error Codes: UNREACHABLE, LOGIN_PAGE, INSUFFICIENT_CONTENT, BLOCKED, INVALID_URL, TIMEOUT

---

Website Analysis

POST /api/analyze-website

Full website analysis with entitlement checks, rate limiting, and confidence scoring.

Request

{
  "url": "https://example.com",
  "maxPages": 1
}

Response (Success)

{
  "success": true,
  "data": {
    "title": "Example Company",
    "description": "Leading provider of example services",
    "colors": {
      "background": "#ffffff",
      "text": "#1a1a1a",
      "primary": "#3b82f6",
      "secondary": "#10b981",
      "accent": "#f59e0b"
    },
    "typography": {
      "headingFont": "Inter",
      "bodyFont": "Roboto"
    }
  },
  "confidence": {
    "title": "high",
    "description": "high",
    "colors": "medium",
    "typography": "high"
  }
}

Rate Limits

• 30 second cooldown between analyses
• 24 hour cooldown for the same URL

IMPORTANT

This endpoint consumes one WEBSITE_ANALYSIS credit per successful call.

---

One-Shot Refinement

POST /api/refine-field

Quick single-turn improvement for brand profile fields.

Request

{
  "fieldId": "tagline",
  "fieldValue": "We make software",
  "instruction": "improve",
  "context": {
    "brandName": "Acme Corp",
    "industry": "Technology",
    "targetAudience": "Enterprise developers"
  }
}

Instructions: improve, expand, shorten, formalize, casualize, clarify, custom

Response

{
  "refined": "Building the future of enterprise software, one innovation at a time",
  "originalLength": 16,
  "refinedLength": 66
}

IMPORTANT

This endpoint consumes one ONE_SHOT_REFINEMENT credit per successful call.