NUDG3 User Preferences API
The User Preferences API from NUDG3 — 8 operation(s) for user preferences.
The User Preferences API from NUDG3 — 8 operation(s) for user preferences.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/nudg3-ai:nudg3-ai-user-preferences-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Nudg3 User Preferences API
description: '# Nudg3 Brand Intelligence API
The Nudg3 API provides programmatic access to brand visibility analytics across AI providers.
## Public API v1
The Public API (`/api/v1/`) is designed for third-party integrations and provides:
### Analytics Endpoints (Tier 1 - Basic)
- Brand visibility scores and trends
- Sentiment analysis across AI responses
- Source citation tracking
- Prompt performance metrics
- Google AI Overview (AIO) coverage
### Export Endpoints (Tier 2 - Premium)
- Full response data exports (CSV/TSV)
- Source citations bulk download
- Dashboard time-series data
- Prompt-mention pair exports
## Authentication
### API Key (Public API v1)
```bash
curl -H "Authorization: Bearer nudg3_live_ak_xxx..." \
https://api.nudg3.com/api/v1/dashboard
```
### JWT (Dashboard API)
```bash
curl -H "Authorization: Bearer eyJ..." \
https://api.nudg3.com/analytics/dashboard
```
## Rate Limits
| Tier | Per Minute | Per Hour | Monthly Quota |
|------|------------|----------|---------------|
| Basic | 60 | 600 | 5,000 |
| Premium | 300 | 3,000 | 50,000 |
## Response Format
All responses follow a standard envelope:
```json
{
"success": true,
"data": { ... },
"message": "Success"
}
```
## Support
- Documentation: https://docs.nudg3.com
- API Status: https://status.nudg3.com
- Support: support@nudg3.com'
version: 1.1.0
termsOfService: https://nudg3.com/terms
contact:
name: Nudg3 API Support
url: https://nudg3.com/support
email: support@nudg3.com
license:
name: Proprietary
url: https://nudg3.com/license
servers:
- url: https://api.nudg3.com
description: Production API
- url: https://api-staging.nudg3.com
description: Staging API (for testing)
- url: http://localhost:8000
description: Local Development
tags:
- name: User Preferences
paths:
/user/preferences/email:
get:
tags:
- User Preferences
summary: Get Email Preferences
description: 'Get current user''s email preferences.
Returns the user''s email notification settings including:
- weekly_report: Whether to receive weekly report emails
- muted_workspaces: List of workspace IDs with muted notifications
- unsubscribed_at: When user globally unsubscribed (null if subscribed)'
operationId: get_email_preferences_user_preferences_email_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EmailPreferencesResponse'
security:
- HTTPBearer: []
patch:
tags:
- User Preferences
summary: Update Email Preferences
description: 'Update user''s email preferences.
Allows setting:
- weekly_report: True to opt-in, False to opt-out of weekly emails'
operationId: update_email_preferences_user_preferences_email_patch
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EmailPreferencesUpdate'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EmailPreferencesResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/user/preferences/email/mute-workspace:
post:
tags:
- User Preferences
summary: Mute Workspace Emails
description: 'Mute or unmute email notifications for a specific workspace.
Users can selectively mute weekly reports for workspaces they
don''t want to receive emails about, while still receiving
reports for other workspaces.
The user must have access to the workspace to mute/unmute it.'
operationId: mute_workspace_emails_user_preferences_email_mute_workspace_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MuteWorkspaceRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/EmailPreferencesResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/user/preferences/email/unsubscribe:
post:
tags:
- User Preferences
summary: Unsubscribe Via Link
description: 'Process unsubscribe link from email.
This endpoint is called when a user clicks the unsubscribe link in
a weekly report email. The token is a JWT containing the user ID.
No authentication required - the token validates the request.'
operationId: unsubscribe_via_link_user_preferences_email_unsubscribe_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UnsubscribeRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
additionalProperties: true
type: object
title: Response Unsubscribe Via Link User Preferences Email Unsubscribe Post
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/user/gdpr/me:
delete:
tags:
- User Preferences
summary: Delete My Account
description: 'Delete your own account (GDPR Article 17 - Right to Erasure).
This action is IRREVERSIBLE. All your personal data will be
anonymized or deleted. Your account will be deactivated.
Requires explicit confirmation (confirm=True).'
operationId: delete_my_account_user_gdpr_me_delete
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteAccountRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteAccountResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/user/gdpr/me/export:
get:
tags:
- User Preferences
summary: Export My Data
description: 'Export all your personal data (GDPR Article 15 - Right of Access).
Returns a comprehensive export of all personal data we hold about you
in a machine-readable format (JSON), satisfying Article 20 requirements
for data portability.
Includes:
- Identity data (name, email)
- Account information
- Consent records
- Activity logs (last 100 entries)
- Your GDPR rights'
operationId: export_my_data_user_gdpr_me_export_get
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/DataExportResponse'
security:
- HTTPBearer: []
/user/gdpr/users/{user_id}:
delete:
tags:
- User Preferences
summary: Admin Delete User
description: 'Delete a user''s account (Admin only - GDPR Article 17).
Allows super users to process deletion requests on behalf of users.
Use cases:
- User requested deletion via support
- Account cleanup
- Regulatory compliance
By default, anonymizes data (recommended). Set anonymize=False for
hard deletion (not recommended unless required).
Note: Cannot delete other super users via this endpoint (security measure).'
operationId: admin_delete_user_user_gdpr_users__user_id__delete
security:
- HTTPBearer: []
parameters:
- name: user_id
in: path
required: true
schema:
type: string
format: uuid
title: User Id
- name: reason
in: query
required: false
schema:
type: string
description: Reason for deletion (for audit trail)
default: Admin requested deletion
title: Reason
description: Reason for deletion (for audit trail)
- name: anonymize
in: query
required: false
schema:
type: boolean
description: If True, anonymize data. If False, hard delete.
default: true
title: Anonymize
description: If True, anonymize data. If False, hard delete.
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteAccountResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/user/gdpr/users/{user_id}/export:
get:
tags:
- User Preferences
summary: Admin Export User Data
description: 'Export a user''s personal data (Admin only - GDPR Article 15).
Allows super users to generate data exports on behalf of users
who request access to their data via support.'
operationId: admin_export_user_data_user_gdpr_users__user_id__export_get
security:
- HTTPBearer: []
parameters:
- name: user_id
in: path
required: true
schema:
type: string
format: uuid
title: User Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/DataExportResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/user/tours/{tour_id}/complete:
post:
tags:
- User Preferences
summary: Complete Tour
description: 'Mark a feature tour as completed. Idempotent — safe to call multiple times.
Stores the tour_id in the user''s completed_tours JSONB array.'
operationId: complete_tour_user_tours__tour_id__complete_post
security:
- HTTPBearer: []
parameters:
- name: tour_id
in: path
required: true
schema:
type: string
title: Tour Id
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
MuteWorkspaceRequest:
properties:
workspace_id:
type: string
format: uuid
title: Workspace Id
description: The workspace ID to mute or unmute
mute:
type: boolean
title: Mute
description: True to mute, False to unmute
default: true
type: object
required:
- workspace_id
title: MuteWorkspaceRequest
description: Request schema to mute/unmute workspace emails.
example:
mute: true
workspace_id: 550e8400-e29b-41d4-a716-446655440000
DeleteAccountRequest:
properties:
reason:
anyOf:
- type: string
- type: 'null'
title: Reason
description: Reason for deletion (for audit trail)
default: User requested deletion
confirm:
type: boolean
title: Confirm
description: Must be True to confirm deletion
type: object
required:
- confirm
title: DeleteAccountRequest
description: Request to delete user account.
UnsubscribeRequest:
properties:
token:
type: string
title: Token
description: JWT token from unsubscribe link containing user ID
type: object
required:
- token
title: UnsubscribeRequest
description: 'Request schema for unsubscribe link handling.
This is used when processing unsubscribe links from emails.
The token is a JWT containing the user ID.'
example:
token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
DataExportResponse:
properties:
export_generated_at:
type: string
title: Export Generated At
data_controller:
type: string
title: Data Controller
data_subject:
additionalProperties: true
type: object
title: Data Subject
consent_records:
additionalProperties: true
type: object
title: Consent Records
organizational_context:
additionalProperties: true
type: object
title: Organizational Context
data_categories:
items: {}
type: array
title: Data Categories
data_retention:
additionalProperties:
type: string
type: object
title: Data Retention
your_rights:
additionalProperties:
type: string
type: object
title: Your Rights
activity_log:
items: {}
type: array
title: Activity Log
default: []
type: object
required:
- export_generated_at
- data_controller
- data_subject
- consent_records
- organizational_context
- data_categories
- data_retention
- your_rights
title: DataExportResponse
description: Response containing user data export.
EmailPreferencesResponse:
properties:
weekly_report:
type: boolean
title: Weekly Report
description: Whether user wants to receive weekly report emails
default: true
muted_workspaces:
items:
type: string
type: array
title: Muted Workspaces
description: List of workspace IDs for which emails are muted
unsubscribed_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Unsubscribed At
description: Timestamp when user globally unsubscribed (null if subscribed)
type: object
title: EmailPreferencesResponse
description: Response schema for user email preferences.
EmailPreferencesUpdate:
properties:
weekly_report:
anyOf:
- type: boolean
- type: 'null'
title: Weekly Report
description: Set to True to receive weekly reports, False to opt out
type: object
title: EmailPreferencesUpdate
description: Request schema to update email preferences.
example:
weekly_report: true
DeleteAccountResponse:
properties:
success:
type: boolean
title: Success
message:
type: string
title: Message
details:
additionalProperties: true
type: object
title: Details
default: {}
type: object
required:
- success
- message
title: DeleteAccountResponse
description: Response from account deletion.
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
msg:
type: string
title: Message
type:
type: string
title: Error Type
type: object
required:
- loc
- msg
- type
title: ValidationError
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
type: object
title: HTTPValidationError
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: '
API Key authentication for Public API v1 endpoints.
**Format:** `nudg3_live_ak_xxx...` or `nudg3_test_ak_xxx...`
**Usage:**
```
Authorization: Bearer nudg3_live_ak_your_key_here
```
Or use the header:
```
X-API-Key: nudg3_live_ak_your_key_here
```
**Obtain API Keys:**
Generate API keys from your Nudg3 dashboard under Settings > API Keys.
**Tiers:**
- **Basic:** `read:analytics` scope - Analytics endpoints only
- **Premium:** `read:analytics` + `export:data` scopes - Analytics + Exports
'
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: '
JWT authentication for internal dashboard endpoints.
Obtain tokens via `/auth/login` endpoint.
'
externalDocs:
description: Nudg3 API Documentation
url: https://docs.nudg3.com/api