NUDG3 Content Generation API

The Content Generation API from NUDG3 — 4 operation(s) for content generation.

GitHub OpenAPI

Operations 4

POST /content-generation/trigger Trigger content generation workflow #
GET /content-generation/{run_id}/status Get content generation status #
POST /content-generation/generate Generate content (synchronous) #
GET /content-generation/{run_id}/stream Stream real-time content generation updates #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • 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.
All 92 tools →

Call it yourself

curl for this page
This API
curl "https://apis.io/api/v1/apis/nudg3-ai:nudg3-ai-content-generation-api"
All apis
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.

Get an API 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 Specification

nudg3-ai-content-generation-api-openapi.yml Raw ↑
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