API Reference

Endpoint

Authentication

No auth required on the endpoint. The server reads OPENAI_API_KEY from its environment. If not set, banwords-only mode runs automatically.

Option 1 — Send plain text (JSON)

curl -X POST https://your-domain.com/api/check \
  -H "Content-Type: application/json" \
  -d '{"text": "Your marketing copy here..."}'

Option 2 — Upload a file (PDF / DOCX / TXT)

curl -X POST https://your-domain.com/api/check \
  -F "file=@/path/to/post.pdf"

Query Parameters

curl -X POST "https://your-domain.com/api/check?checklist=false" \
  -H "Content-Type: application/json" \
  -d '{"text": "..."}'

Response Schema

{
  "pass": boolean,          // true only if banwords=0 AND all 6 Q = NO
  "text_length": number,

  "banwords": {
    "pass": boolean,
    "count": number,
    "matches": [
      { "phrase": "book a demo", "category": "Vertical SaaS CTA", "count": 1 }
    ]
  },

  "checklist": {
    "enabled": boolean,     // false if OPENAI_API_KEY not set
    "pass": boolean | null,
    "results": [
      {
        "id": 1,
        "rivalVoice": "Generalist Digital-Transformation Agency",
        "answer": "YES" | "NO",
        "reason": "One sentence explanation."
      }
    ] | null
  }
}

n8n / Make — automation pattern

HTTP Request node → POST /api/check, body JSON. Branch on pass field.

// Route on result
{{ $json.pass ? "SHIP" : "REWRITE" }}

// List found banwords
{{ $json.banwords.matches.map(m => m.phrase).join(", ") }}

// Which checklist questions triggered
{{ $json.checklist.results?.filter(r => r.answer === "YES").map(r => "Q" + r.id).join(", ") }}

CI / GitHub Actions — block PR on failure

- name: Anti-positioning check
  run: |
    RESULT=$(curl -sf -X POST $QA_TOOL_URL/api/check \
      -H "Content-Type: application/json" \
      -d "{\"text\": \"$(cat copy.txt)\"}")
    echo "$RESULT" | jq .
    if [ "$(echo "$RESULT" | jq -r '.pass')" != "true" ]; then
      echo "Anti-positioning check FAILED — rewrite required"
      exit 1
    fi

Error responses