TheBuildShieldAPI Documentation

Developer

API Reference

TheBuildShield API lets you analyze AI usage programmatically. Submit chat conversations or API CSV rows as JSON and get spend scores, cost breakdowns, and optimization playbooks in return.

Authentication

Pass your API key in the X-Api-Key header. API keys are available to Pro and Founder plan users.

X-Api-Key: bsk_your_key_here

Generate keys in Settings → API Keys

Rate Limits

Free / StarterNo API access
Pro1,000 calls / month
FounderUnlimited

Limits reset on the 1st of each month.

Zero-Trust Architecture: submitted payloads are processed in-memory and immediately discarded. No conversation content or prompt text is stored at any point.

POST/api/v1/analyze-api

Analyze AI usage data. Supports two modes: chat and csv.

Request Body

FieldTypeRequiredDescription
modestringRequired"chat" or "csv"
platformstringOptionalHint for platform (e.g. "ChatGPT")
conversationsarraychat modeArray of conversation objects with messages
conversations[].idstringOptionalOptional conversation identifier
conversations[].titlestringOptionalOptional conversation title
conversations[].messagesarrayYes (chat)Array of {role, content} message objects
csv_rowsarraycsv modeArray of CSV row objects with model/token/cost fields

Response

Returns the full analysis object:

spend_scoreScore 0–100, grade A–F, verdict string
action_planHeadline + prioritized list of optimization actions
estimated_cost_usd(chat mode) Equivalent API cost in USD
total_tokens(chat mode) Total tokens processed
wasted_tokens(chat mode) Tokens in inefficient interactions
summary(csv mode) Cost totals, model breakdown, tier breakdown
model_swap_recommendations(csv mode) Cheaper model alternatives with savings estimates
playbooks(csv mode) Strategy-level optimization playbooks

Error Codes

401UnauthorizedMissing or invalid API key
403ForbiddenPlan does not have API access (requires Pro/Founder)
429Too Many RequestsMonthly API call limit reached (Pro plan)
400Bad RequestInvalid mode, missing required fields, or unparseable data
500Server ErrorInternal processing error

Code Examples

Chat Mode — cURL
curl -X POST https://api.buildshield.app/api/v1/analyze-api \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: bsk_your_api_key_here" \
  -d '{
    "mode": "chat",
    "conversations": [
      {
        "id": "conv_001",
        "title": "Project planning",
        "messages": [
          { "role": "user", "content": "Help me plan a microservices migration" },
          { "role": "assistant", "content": "Here is a step-by-step plan..." }
        ]
      }
    ]
  }'
CSV Mode — cURL
curl -X POST https://api.buildshield.app/api/v1/analyze-api \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: bsk_your_api_key_here" \
  -d '{
    "mode": "csv",
    "csv_rows": [
      {
        "date": "2026-03-15",
        "model": "gpt-5.4",
        "input_tokens": "12500",
        "output_tokens": "3200",
        "total_cost": "0.19"
      }
    ]
  }'
Python
import requests

response = requests.post(
    "https://api.buildshield.app/api/v1/analyze-api",
    headers={
        "X-Api-Key": "bsk_your_api_key_here",
        "Content-Type": "application/json",
    },
    json={
        "mode": "chat",
        "conversations": [{"messages": [
            {"role": "user", "content": "Your message here"},
            {"role": "assistant", "content": "Assistant response"},
        ]}],
    },
)

data = response.json()
print("Spend score:", data["spend_score"]["score"])
print("Estimated cost:", data["estimated_cost_usd"])
JavaScript / Node
const response = await fetch(
  'https://api.buildshield.app/api/v1/analyze-api',
  {
    method: 'POST',
    headers: {
      'X-Api-Key': 'bsk_your_api_key_here',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      mode: 'chat',
      conversations: [
        {
          messages: [
            { role: 'user', content: 'Your message' },
            { role: 'assistant', content: 'Response' },
          ],
        },
      ],
    }),
  }
);

const data = await response.json();

Ready to integrate?

Generate your API key in Settings. Pro gets 1,000 calls/month, Founder gets unlimited.

Generate API KeyView Plans