NUDG3 Content Generation API
The Content Generation API from NUDG3 — 4 operation(s) for content generation.
The Content Generation API from NUDG3 — 4 operation(s) for content generation.
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-content-generation-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 Content Generation 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: Content Generation
paths:
/content-generation/trigger:
post:
tags:
- Content Generation
summary: Trigger content generation workflow
description: 'Trigger an AI content generation workflow.
The workflow:
1. Classifies content type from action_text
2. Routes to optimal AI model based on content type
3. Optionally performs web research (for blog posts, documents)
4. Generates content using the selected model
5. Returns generated content with metadata
**Content Types & Model Routing:**
- Blog posts, documents: Claude Sonnet
- X/Twitter: Grok (native platform understanding)
- LinkedIn: GPT-4o (professional tone)
- Social media, images: Gemini Flash
- Email: Claude Haiku (cost-efficient)
**Returns immediately**: Use /content-generation/{run_id}/status to poll for completion'
operationId: trigger_content_generation_content_generation_trigger_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ContentGenerationRequest'
required: true
responses:
'202':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ContentGenerationTriggerResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/content-generation/{run_id}/status:
get:
tags:
- Content Generation
summary: Get content generation status
description: 'Poll the status of a content generation workflow.
Returns the current status and generated content when complete.
**Query Parameters:**
- `action_id`: Required. The action ID to check for content status.
**Database-Only Pattern:**
This endpoint reads content status directly from the database where
the workflow persists results. No LangGraph polling required.
**Statuses:**
- `in_progress`: Workflow is still running
- `completed`: Workflow completed successfully, content available
- `failed`: Workflow failed (check error field)'
operationId: get_content_generation_status_content_generation__run_id__status_get
security:
- HTTPBearer: []
parameters:
- name: run_id
in: path
required: true
schema:
type: string
title: Run Id
- name: action_id
in: query
required: true
schema:
type: string
description: Action ID to check for content status
title: Action Id
description: Action ID to check for content status
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ContentGenerationStatusResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/content-generation/generate:
post:
tags:
- Content Generation
summary: Generate content (synchronous)
description: 'Generate content synchronously - waits for completion.
Use this endpoint when you need the generated content immediately.
For background generation, use /content-generation/trigger instead.
**Timeout:** 60 seconds'
operationId: generate_content_sync_content_generation_generate_post
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ContentGenerationRequest'
required: true
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/ContentGenerationStatusResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
security:
- HTTPBearer: []
/content-generation/{run_id}/stream:
get:
tags:
- Content Generation
summary: Stream real-time content generation updates
description: 'Provides Server-Sent Events (SSE) stream of real-time content generation updates.
**Security**: Validates Firebase token (via query param) and action ownership before streaming.
**Use case**: Frontend EventSource connection for live progress updates
**Stream Events**:
- `started`: Workflow has begun
- `progress`: Node execution updates (classifying, routing, generating)
- `completed`: Content generated successfully
- `error`: Something went wrong
- `end`: Workflow finished (final event)
**Query Parameters**:
- `token`: Firebase ID token (required - EventSource doesn''t support headers)
- `action_id`: Action ID for authorization (required)
**Example EventSource Usage**:
```javascript
const eventSource = new EventSource(
`/content-generation/${runId}/stream?token=${idToken}&action_id=${actionId}`
);
eventSource.addEventListener(''progress'', (event) => {
const data = JSON.parse(event.data);
console.log(''Progress:'', data.message);
});
eventSource.addEventListener(''completed'', (event) => {
const data = JSON.parse(event.data);
console.log(''Content:'', data.generated_content);
eventSource.close();
});
```'
operationId: stream_content_generation_updates_content_generation__run_id__stream_get
parameters:
- name: run_id
in: path
required: true
schema:
type: string
title: Run Id
- name: token
in: query
required: true
schema:
type: string
description: Firebase ID token for authentication
title: Token
description: Firebase ID token for authentication
- name: action_id
in: query
required: true
schema:
type: string
description: Action ID for authorization
title: Action Id
description: Action ID for authorization
responses:
'200':
description: Successful Response
content:
application/json:
schema: {}
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
ContentGenerationRequest:
properties:
workspace_id:
type: string
format: uuid
title: Workspace Id
description: Target workspace UUID
action_text:
type: string
maxLength: 1000
minLength: 5
title: Action Text
description: The content generation request (e.g., 'Create blog post about AI visibility')
action_id:
anyOf:
- type: string
format: uuid
- type: 'null'
title: Action Id
description: Optional WorkspaceAction ID if triggered from visibility report
brand_name:
anyOf:
- type: string
maxLength: 200
- type: 'null'
title: Brand Name
description: Brand name (auto-populated from workspace if not provided)
industry:
anyOf:
- type: string
maxLength: 200
- type: 'null'
title: Industry
description: Industry context (auto-populated from workspace if not provided)
target_audience:
anyOf:
- type: string
maxLength: 500
- type: 'null'
title: Target Audience
description: Target audience hint for content generation
tone:
anyOf:
- type: string
pattern: ^(professional|casual|authoritative|friendly|technical)$
- type: 'null'
title: Tone
description: 'Tone preference: professional, casual, authoritative, friendly, technical'
additional_context:
anyOf:
- type: string
maxLength: 2000
- type: 'null'
title: Additional Context
description: Any additional context for the generation
type: object
required:
- workspace_id
- action_text
title: ContentGenerationRequest
description: Request to trigger content generation.
examples:
- action_text: Create a blog post about AI visibility trends
target_audience: Marketing professionals
tone: professional
workspace_id: 123e4567-e89b-12d3-a456-426614174000
- action_id: 789e4567-e89b-12d3-a456-426614174000
action_text: Generate a tweet about our product launch
workspace_id: 123e4567-e89b-12d3-a456-426614174000
ContentGenerationTriggerResponse:
properties:
run_id:
type: string
title: Run Id
description: LangGraph run ID for tracking
workspace_id:
type: string
format: uuid
title: Workspace Id
description: Workspace UUID
status:
type: string
title: Status
description: 'Status: triggered, running, completed, failed'
message:
type: string
title: Message
description: Human-readable status message
content_type:
anyOf:
- type: string
- type: 'null'
title: Content Type
description: Classified content type (blog_post, x_twitter, linkedin, etc.)
type: object
required:
- run_id
- workspace_id
- status
- message
title: ContentGenerationTriggerResponse
description: Response after triggering content generation workflow.
examples:
- content_type: blog_post
message: Content generation workflow started
run_id: abc123-def456
status: triggered
workspace_id: 123e4567-e89b-12d3-a456-426614174000
ContentGenerationStatusResponse:
properties:
run_id:
type: string
title: Run Id
description: LangGraph run ID
status:
type: string
title: Status
description: Current status
content_type:
anyOf:
- type: string
- type: 'null'
title: Content Type
description: Classified content type
selected_model:
anyOf:
- type: string
- type: 'null'
title: Selected Model
description: Selected AI model
generated_content:
anyOf:
- type: string
- type: 'null'
title: Generated Content
description: Generated content (if complete)
generated_title:
anyOf:
- type: string
- type: 'null'
title: Generated Title
description: Generated title (if applicable)
generated_metadata:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Generated Metadata
description: Generation metadata (word_count, read_time, etc.)
input_tokens:
anyOf:
- type: integer
- type: 'null'
title: Input Tokens
description: Total input tokens used
output_tokens:
anyOf:
- type: integer
- type: 'null'
title: Output Tokens
description: Total output tokens used
generation_cost_usd:
anyOf:
- type: number
- type: 'null'
title: Generation Cost Usd
description: Estimated generation cost
error:
anyOf:
- type: string
- type: 'null'
title: Error
description: Error message if failed
created_at:
anyOf:
- type: string
- type: 'null'
title: Created At
description: ISO timestamp of creation
updated_at:
anyOf:
- type: string
- type: 'null'
title: Updated At
description: ISO timestamp of last update
type: object
required:
- run_id
- status
title: ContentGenerationStatusResponse
description: Status of a content generation workflow run.
examples:
- content_type: blog_post
generated_content: '# AI Visibility Trends in 2025
...'
generated_metadata:
estimated_read_time: 4 min read
word_count: 850
generated_title: AI Visibility Trends in 2025
generation_cost_usd: 0.025
input_tokens: 500
output_tokens: 1200
run_id: abc123-def456
selected_model: claude_sonnet
status: completed
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