Visibility report insights, workspace actions, and AI content generation endpoints

Insights & Actions Endpoints

Access AI-generated visibility insights, manage workspace actions, and trigger content generation programmatically.

Scope Requirements: Read endpoints require read:insights (Professional tier+). Write endpoints require write:actions (Enterprise tier only).

Tier Access

Endpoint Type	Required Scope	Tier
Reports (read)	`read:insights`	Professional, Enterprise
Actions (read)	`read:insights`	Professional, Enterprise
Actions (create)	`write:actions`	Enterprise
Content Generation	`write:actions`	Enterprise

Reports

List Reports

Retrieve a paginated list of visibility audit reports for your workspace.

GET /api/v1/reports

Parameters

Parameter	Type	Required	Description
`report_type`	string	No	Filter by type: `free_audit`, `weekly_report`, `on_demand`
`start_date`	date	No	Filter reports created after this date (YYYY-MM-DD)
`end_date`	date	No	Filter reports created before this date (YYYY-MM-DD)
`page`	integer	No	Page number (default: 1)
`per_page`	integer	No	Results per page (max: 50, default: 20)

Example Request

curl "https://api.nudg3.ai/api/v1/reports?report_type=weekly_report&per_page=10" \
  -H "Authorization: Bearer nudg3_live_ak_your_key"

Response

{
  "success": true,
  "data": {
    "reports": [
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "report_type": "weekly_report",
        "brand_name": "Acme Corp",
        "visibility_score": 72,
        "competitive_position": 3,
        "total_mentions": 1450,
        "total_responses": 2800,
        "mention_rate": 0.518,
        "analysis_confidence": "high",
        "executive_summary": "Your brand visibility improved 8% week-over-week...",
        "has_insights": true,
        "calculated_at": "2026-04-01T12:00:00",
        "start_date": "2026-03-25",
        "end_date": "2026-04-01",
        "created_at": "2026-04-01T12:05:00"
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 10,
      "total": 24,
      "total_pages": 3,
      "has_next": true,
      "has_prev": false
    }
  },
  "message": "Retrieved 10 reports"
}

Get Latest Report

Shortcut to retrieve the most recent report without pagination.

GET /api/v1/reports/latest

Parameters

Parameter	Type	Required	Description
`report_type`	string	No	Filter by report type
`include_insights`	boolean	No	Include AI insights in response (default: false)

Example Request

curl "https://api.nudg3.ai/api/v1/reports/latest?include_insights=true" \
  -H "Authorization: Bearer nudg3_live_ak_your_key"

Response

Returns a single report object (same shape as list items), optionally with an insights field containing the full AI analysis.

Get Report Detail

Retrieve full detail of a specific visibility report including provider breakdowns and rankings.

GET /api/v1/reports/{report_id}

Parameters

Parameter	Type	Required	Description
`report_id`	UUID	Yes	Report ID (path parameter)
`include_insights`	boolean	No	Include AI insights in response (default: false)

Example Request

curl "https://api.nudg3.ai/api/v1/reports/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer nudg3_live_ak_your_key"

Response

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "report_type": "weekly_report",
    "brand_name": "Acme Corp",
    "visibility_score": 72,
    "competitive_position": 3,
    "total_mentions": 1450,
    "mention_rate": 0.518,
    "analysis_confidence": "high",
    "executive_summary": "Your brand visibility improved 8% week-over-week...",
    "has_insights": true,
    "provider_scores": {
      "ChatGPT": 68,
      "Gemini": 75,
      "Claude": 71,
      "Perplexity": 82
    },
    "ranked_brands": [
      {"name": "Competitor A", "mentions": 1800, "score": 85},
      {"name": "Competitor B", "mentions": 1600, "score": 78},
      {"name": "Acme Corp", "mentions": 1450, "score": 72}
    ],
    "sentiment_summary": {
      "positive": 0.62,
      "neutral": 0.28,
      "negative": 0.10
    },
    "data_quality_notes": ["Sufficient data for high confidence analysis"]
  },
  "message": "Report retrieved"
}

Get Report Insights

Retrieve AI-generated insights from a specific visibility report. Returns structured opportunities, threats, quick wins, and recommendations.

GET /api/v1/reports/{report_id}/insights

Parameters

Parameter	Type	Required	Description
`report_id`	UUID	Yes	Report ID (path parameter)
`type`	string	No	Filter by insight type: `opportunities`, `threats`, `quick_wins`, or `all` (default)
`priority`	string	No	Filter by priority: `high`, `medium`, `low`
`category`	string	No	Filter by category: `tech`, `content`, `marketing`, `leadership`

Example Request

curl "https://api.nudg3.ai/api/v1/reports/a1b2c3d4.../insights?type=quick_wins&priority=high" \
  -H "Authorization: Bearer nudg3_live_ak_your_key"

Response

{
  "success": true,
  "data": {
    "schema_version": "2026-04-02",
    "opportunities": [
      {
        "title": "Expand Perplexity presence",
        "description": "Your brand scores 82 on Perplexity but only 68 on ChatGPT. Focus content optimization on ChatGPT prompts to close the gap.",
        "priority": "high",
        "category": "content",
        "impact": "Estimated +12 visibility points"
      }
    ],
    "threats": [
      {
        "title": "Competitor A gaining on Gemini",
        "description": "Competitor A increased Gemini mentions by 15% this week.",
        "priority": "medium",
        "category": "marketing",
        "impact": "Risk of losing position 3 ranking"
      }
    ],
    "quick_wins": [
      {
        "title": "Update product FAQ page",
        "description": "3 AI providers cite an outdated FAQ. Updating it could improve citation accuracy across all providers.",
        "priority": "high",
        "category": "content",
        "impact": "Immediate citation improvement"
      }
    ],
    "provider_strategies": [
      {
        "provider": "ChatGPT",
        "strategy": "Add structured data markup to improve content extraction",
        "priority": "high",
        "current_score": 68.0
      }
    ],
    "content_recommendations": [
      {
        "title": "Publish comparison guide",
        "description": "Create a detailed comparison page targeting 'best X' queries",
        "content_format": "blog_post",
        "target_platform": "website",
        "priority": "medium"
      }
    ],
    "prompt_edit_suggestions": []
  },
  "message": "Insights retrieved"
}

Schema Versioning: The schema_version field indicates the response shape version. New fields may be added in future versions, but existing fields will never be removed or renamed. Clients should ignore unknown fields for forward compatibility.

Actions

List Actions

Retrieve workspace actions (recommendations, tasks, content items) with optional filters.

GET /api/v1/actions

Parameters

Parameter	Type	Required	Description
`status`	string	No	Filter: `pending`, `in_progress`, `ready`, `completed`, `dismissed`
`priority`	string	No	Filter: `high`, `medium`, `low`
`recommendation_type`	string	No	Filter: `opportunity`, `threat`, `quick_win`, `prompt_edit`
`owner_team`	string	No	Filter: `tech`, `content`, `marketing`, `leadership`
`content_format`	string	No	Filter: `blog_post`, `linkedin_post`, `x_thread`, etc.
`source_report_id`	UUID	No	Filter by source visibility report
`page`	integer	No	Page number (default: 1)
`per_page`	integer	No	Results per page (max: 50, default: 20)

Example Request

curl "https://api.nudg3.ai/api/v1/actions?status=pending&priority=high" \
  -H "Authorization: Bearer nudg3_live_ak_your_key"

Response

{
  "success": true,
  "data": {
    "actions": [
      {
        "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "recommendation_type": "quick_win",
        "action_text": "Update product FAQ page with current pricing",
        "status": "pending",
        "priority": "high",
        "content_format": "blog_post",
        "target_platform": "website",
        "owner_team": "content",
        "source_report_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "created_at": "2026-04-01T12:10:00",
        "updated_at": "2026-04-01T12:10:00"
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total": 8,
      "total_pages": 1,
      "has_next": false,
      "has_prev": false
    }
  },
  "message": "Retrieved 8 actions"
}

Get Action Detail

Retrieve full detail of a specific action including context and brief information.

GET /api/v1/actions/{action_id}

Example Request

curl "https://api.nudg3.ai/api/v1/actions/b2c3d4e5-f6a7-8901-bcde-f12345678901" \
  -H "Authorization: Bearer nudg3_live_ak_your_key"

Create Action

Create a new workspace action. Requires write:actions scope (Enterprise tier).

POST /api/v1/actions

Enterprise Only: This endpoint requires the write:actions scope, available on Enterprise tier API keys.

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer nudg3_live_ak_your_key`
`Content-Type`	Yes	`application/json`
`Idempotency-Key`	Recommended	Unique string to prevent duplicate creation on retry (24hr window)

Request Body

{
  "action_text": "Create blog post comparing our product vs Competitor A",
  "recommendation_type": "opportunity",
  "priority": "high",
  "content_format": "blog_post",
  "target_platform": "website",
  "owner_team": "content",
  "source_report_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "context": {
    "brand_name": "Acme Corp",
    "industry": "SaaS"
  }
}

Field	Type	Required	Description
`action_text`	string	Yes	Action description (max 2000 chars)
`recommendation_type`	string	Yes	`opportunity`, `threat`, `quick_win`, or `prompt_edit`
`priority`	string	No	`high`, `medium` (default), or `low`
`content_format`	string	No	`blog_post`, `linkedin_post`, `x_thread`, `editorial`, etc.
`target_platform`	string	No	`website`, `linkedin`, `x_twitter`, `reddit`, etc.
`owner_team`	string	No	`tech`, `content`, `marketing`, or `leadership`
`source_report_id`	UUID	No	Link to source visibility report
`context`	object	No	Additional context for the action

Response (201 Created)

Returns the full action detail object.

Content Generation

Generate Brief

Generate a structured content brief for an action. The brief provides guidance for content creation.

POST /api/v1/actions/{action_id}/generate-brief

Rate Limited: Max 5 generations per action per hour, max 50 per workspace per day. Cost: ~$0.001 per brief (Gemini Flash).

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer nudg3_live_ak_your_key`
`Idempotency-Key`	Recommended	Prevents duplicate generation on retry

Request Body

{
  "custom_instructions": "Focus on technical audience, include code examples"
}

Field	Type	Required	Description
`custom_instructions`	string	No	Custom instructions for brief generation (max 1000 chars)

Response

Returns a structured brief with objective, target audience, key messages, tone, content structure, SEO considerations, CTA, and success metrics.

Response Headers

Header	Description
`X-Generation-Remaining-Action`	Remaining generations for this action this hour
`X-Generation-Remaining-Workspace-Daily`	Remaining generations for this workspace today

Generate Content

Trigger asynchronous AI content generation for an action. Returns a run_id for polling.

POST /api/v1/actions/{action_id}/generate-content

Rate Limited: Max 5 generations per action per hour, max 50 per workspace per day. Cost varies by content type ($0.005 - $0.30 per generation).

Request Body

{
  "use_brief": true
}

Field	Type	Required	Description
`use_brief`	boolean	No	Use existing brief if available (default: true)

Response

{
  "success": true,
  "data": {
    "run_id": "run_abc123xyz",
    "thread_id": "thread_def456",
    "status": "triggered",
    "estimated_model": "claude-sonnet",
    "estimated_cost_range_usd": {
      "min": 0.04,
      "max": 0.06
    }
  },
  "message": "Content generation triggered"
}

Cost Estimates by Content Type

Content Type	Model	Estimated Cost
Blog post	Claude Sonnet	$0.04 - $0.06
LinkedIn post	GPT-4o	$0.03 - $0.05
X/Twitter thread	Grok	$0.02 - $0.04
Social media	Gemini Flash	$0.005 - $0.01
Email	Claude Haiku	$0.005 - $0.01

Poll Generation Status

Check the status of an asynchronous content generation run.

GET /api/v1/actions/{action_id}/generation-status/{run_id}

Parameters

Parameter	Type	Required	Description
`action_id`	UUID	Yes	Action ID (path parameter)
`run_id`	string	Yes	Run ID returned from generate-content (path parameter)

Example Request

curl "https://api.nudg3.ai/api/v1/actions/b2c3d4e5.../generation-status/run_abc123xyz" \
  -H "Authorization: Bearer nudg3_live_ak_your_key"

Response (completed)

{
  "success": true,
  "data": {
    "run_id": "run_abc123xyz",
    "status": "completed",
    "generated_content": "# Why Acme Corp Outperforms Competitor A\n\nIn the rapidly evolving...",
    "generated_title": "Why Acme Corp Outperforms Competitor A in AI Visibility",
    "generation_cost_usd": 0.047,
    "selected_model": "claude-sonnet-4-5",
    "error": null,
    "created_at": "2026-04-01T12:15:00",
    "updated_at": "2026-04-01T12:15:45"
  },
  "message": "Generation status: completed"
}

Status Values

Status	Description
`triggered`	Generation request accepted, queued for processing
`running`	AI model is generating content
`completed`	Content generated successfully
`failed`	Generation failed (check `error` field)

Polling Recommendation: Poll every 3-5 seconds. Most generations complete within 30-60 seconds. Webhook support for push notifications is coming in a future release.

Idempotency

All POST endpoints support the Idempotency-Key header to prevent duplicate operations on retry.

curl -X POST "https://api.nudg3.ai/api/v1/actions" \
  -H "Authorization: Bearer nudg3_live_ak_your_key" \
  -H "Idempotency-Key: my-unique-request-id-123" \
  -H "Content-Type: application/json" \
  -d '{"action_text": "...", "recommendation_type": "opportunity"}'

If the same Idempotency-Key is sent twice within 24 hours, the second request returns the stored response from the first
Keys are scoped per API key (different API keys can use the same idempotency key without collision)
The idempotency window is 24 hours

Error Responses

Code	Scenario	Example Message
403	Missing scope	`Insufficient scope: read:insights required`
404	Report/action not found or belongs to another workspace	`Report not found`
429	Generation rate limit	`Rate limit exceeded: max 5 generations per action per hour`
429	Workspace daily limit	`Rate limit exceeded: max 50 generations per workspace per day`

Insights & Actions Endpoints

On this page