Technical Appendix

Under the hood. API endpoints, authentication, data models, and technical reference for CTOs and developers.

API Overview

All Campaign Brain services expose RESTful APIs with consistent patterns:

Base URL: https://[service].nominate.ai/api/v1
Authentication: Bearer token (JWT)
Content-Type: application/json

Common Endpoints

Authentication

Campaign Brain uses JWT-based authentication with refresh tokens.

Token Flow

1. Login: POST /auth/login with credentials
2. Receive: Access token (15 min) + Refresh token (7 days)
3. Use: Include Authorization: Bearer [access_token] in requests
4. Refresh: POST /auth/refresh with refresh token when expired

Scopes

Data Models

Voter Record

{
  "id": "uuid",
  "voter_file_id": "state-assigned-id",
  "first_name": "string",
  "last_name": "string",
  "address": {
    "street": "string",
    "city": "string",
    "state": "string",
    "zip": "string"
  },
  "demographics": {
    "age": "number",
    "gender": "string",
    "party": "string"
  },
  "scores": {
    "turnout": "number (0-100)",
    "support": "number (0-100)",
    "persuadable": "number (0-100)"
  },
  "contact_history": ["ContactEvent"],
  "tags": ["string"],
  "created_at": "timestamp",
  "updated_at": "timestamp"
}

Contact Event

{
  "id": "uuid",
  "voter_id": "uuid",
  "type": "door|phone|sms|email|mail",
  "outcome": "contact|not_home|refused|wrong_number|moved",
  "notes": "string",
  "survey_responses": {},
  "created_by": "uuid",
  "created_at": "timestamp"
}

Workflow Definition

{
  "id": "uuid",
  "name": "string",
  "status": "draft|active|paused|archived",
  "trigger": {
    "type": "segment|event|schedule",
    "config": {}
  },
  "nodes": ["WorkflowNode"],
  "created_at": "timestamp",
  "updated_at": "timestamp"
}

Service Ports

Development and internal routing reference:

GitHub Repositories

Nominate-AI/cbpublic     — Public website
Nominate-AI/cbtenant     — Tenant manager
Nominate-AI/cbapp        — Campaign app
Nominate-AI/cbworkflow   — Workflow engine
Nominate-AI/cbsurveys    — Survey platform
Nominate-AI/cbdistricts  — District service
Nominate-AI/cbmodels     — Analytics
Nominate-AI/cbradio      — Radio advertising
Nominate-AI/cbfiles      — File storage
Nominate-AI/cbinfra      — Infrastructure
Nominate-AI/cbai         — AI service
Nominate-AI/cbetl        — ETL pipeline

Rate Limits

Rate limit headers included in all responses:

• X-RateLimit-Limit: Max requests per window
• X-RateLimit-Remaining: Requests left in window
• X-RateLimit-Reset: Unix timestamp when window resets

Error Codes

Error response format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Human-readable description",
    "details": {}
  }
}