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 two tiers:

Tier	Scope	Endpoints
Basic	`read:analytics`	All analytics endpoints
Premium	`read:analytics` + `export:data`	Analytics + Export endpoints

Endpoint Categories

System

Basic API information and health checks.

Endpoint	Method	Description	Auth
`/`	GET	API root with endpoint listing	No
`/health`	GET	Health check endpoint	No

Analytics (Tier 1 - Basic)

Core analytics endpoints for brand visibility tracking.

Endpoint	Method	Description
`/dashboard`	GET	Brand visibility scores and metrics
`/brands`	GET	List brands/competitors
`/brands/{brand_id}`	GET	Get brand details with metrics
`/prompts`	GET	List prompt templates
`/prompts/{prompt_id}`	GET	Get prompt performance metrics
`/sources`	GET	Domain-level source analytics
`/urls`	GET	URL-level citations
`/urls-detailed`	GET	Detailed URL analytics with trends
`/responses`	GET	AI provider response list
`/aio-metrics`	GET	Google AI Overview metrics
`/aio-metrics/prompt/{id}`	GET	Per-prompt AIO metrics
`/filters`	GET	Available filter values

Analytics Endpoints

Detailed analytics endpoint documentation

Exports (Tier 2 - Premium)

Data export endpoints for BI tool integration.

Endpoint	Method	Description	Format
`/exports/chat-responses`	GET	Full LLM responses	CSV/TSV
`/exports/sources-citations`	GET	Complete citation records	CSV
`/exports/dashboard-graph`	GET	Time-series visibility data	CSV
`/exports/prompts-mentions`	GET	Prompt-mention pairs	CSV

Export Endpoints

Data export endpoint documentation

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:

Parameter	Type	Description
`start_date`	date	Filter start date (YYYY-MM-DD). Defaults to 30 days ago
`end_date`	date	Filter end date (YYYY-MM-DD). Defaults to today
`models`	array	Filter by AI provider names (openai, anthropic, google, perplexity)
`model_ids`	array	Filter by specific model IDs (gpt-4o-mini, claude-3-5-haiku)
`tags`	array	Filter by prompt template tags
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (max: 100, default: 50)

Export-Specific Parameters

Export endpoints use different date parameters and have additional options:

Parameter	Type	Required	Description
`date_from`	date	Yes	Start date for export (YYYY-MM-DD)
`date_to`	date	Yes	End date for export (YYYY-MM-DD)
`format`	string	No	Export format: `csv` (default) or `tsv`
`excel_compatible`	boolean	No	Add BOM for Excel compatibility
`include_type_hints`	boolean	No	Include type hints row in export

Important: Export endpoints use date_from and date_to (both required), while analytics endpoints use start_date and end_date (both optional).

Workspace Isolation: API keys are workspace-scoped. The workspace is automatically determined from your API key - you don't need to pass a workspace_id parameter.

Example Request

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

The Public API v1 is read-only. All endpoints use GET method.

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

Code	Description
200	Success
201	Created
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Rate Limits

API requests are rate limited per workspace:

Tier	Per Minute	Per Hour
Basic	60	600
Premium	300	3,000

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.

The current API version is v1. Subscribe to our changelog for updates.

API Reference

Analytics Endpoints

Export Endpoints

On this page