API Reference

This section contains the complete reference for the NUDG3 Public API v1 endpoints.

Base URL

All API requests should be made to:

https://api.nudg3.ai/api/v1

For local development:

http://localhost:8000/api/v1

Authentication

All endpoints require authentication via API key (except health check):

Authorization: Bearer nudg3_live_ak_your_key

Or use the X-API-Key header:

X-API-Key: nudg3_live_ak_your_key

See Authentication for details on obtaining and managing API keys.

API Tiers

The Public API is organized into three tiers:

Endpoint Categories

System

Basic API information and health checks.

Analytics (Tier 1 - Basic)

Core analytics endpoints for brand visibility tracking.

Exports (Tier 2 - Premium)

Data export endpoints for BI tool integration.

Insights & Actions (Tier 2+ / Tier 3)

Visibility report insights, actions, and AI content generation.

Request Format

Headers

All requests should include:

Authorization: Bearer nudg3_live_ak_your_key
Content-Type: application/json

Query Parameters

Common query parameters across analytics endpoints:

Export-Specific Parameters

Export endpoints use different date parameters and have additional options:

Example Request

curl https://api.nudg3.ai/api/v1/dashboard \
  -H "Authorization: Bearer nudg3_live_ak_your_key"

Response Format

Success Response

Successful responses return JSON with a standard envelope:

{
  "success": true,
  "data": {
    // Response data here
  },
  "message": "Human-readable success message"
}

For paginated endpoints, the data includes pagination info:

{
  "success": true,
  "data": {
    "items": [...],
    "pagination": {
      "page": 1,
      "per_page": 50,
      "total": 156,
      "total_pages": 4,
      "has_next": true,
      "has_prev": false
    }
  },
  "message": "Retrieved 50 items"
}

Error Response

Error responses follow a consistent format:

{
  "success": false,
  "detail": "Human-readable error message"
}

HTTP Status Codes

Rate Limits

API requests are rate limited per workspace:

See Rate Limits for details.

Pagination

List endpoints support page-based pagination:

GET /api/v1/brands?page=2&per_page=50

Response includes pagination metadata:

{
  "success": true,
  "data": {
    "competitors": [...],
    "pagination": {
      "page": 2,
      "per_page": 50,
      "total": 156,
      "total_pages": 4,
      "has_next": true,
      "has_prev": true
    }
  },
  "message": "Retrieved 50 brands"
}

Filtering

Most endpoints support filtering:

GET /api/v1/dashboard?models=openai,anthropic&start_date=2026-01-01&end_date=2026-01-31

Versioning

The API is versioned via URL path (/v1/). Breaking changes will be released under new versions.