NUDG3 Integrations API
The Integrations API from NUDG3 — 12 operation(s) for integrations.
The Integrations API from NUDG3 — 12 operation(s) for integrations.
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-integrations-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 Integrations 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: Integrations
paths:
/workspace/{workspace_id}/integrations:
get:
tags:
- Integrations
summary: List Integrations
description: List all integration statuses for this workspace.
operationId: list_integrations_workspace__workspace_id__integrations_get
security:
- HTTPBearer: []
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationListResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/workspace/{workspace_id}/integrations/google_analytics/properties:
get:
tags:
- Integrations
summary: List Ga4 Properties
description: 'List GA4 properties accessible by the stored OAuth credentials.
Used after OAuth connection so the user can pick their property.'
operationId: list_ga4_properties_workspace__workspace_id__integrations_google_analytics_properties_get
security:
- HTTPBearer: []
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
type: object
additionalProperties: true
title: Response List Ga4 Properties Workspace Workspace Id Integrations Google Analytics Properties Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/workspace/{workspace_id}/integrations/search_console/sites:
get:
tags:
- Integrations
summary: List Gsc Sites
description: 'List Search Console sites accessible by the stored OAuth credentials.
Used after OAuth connection so the user can pick their site.'
operationId: list_gsc_sites_workspace__workspace_id__integrations_search_console_sites_get
security:
- HTTPBearer: []
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
type: array
items:
type: object
additionalProperties: true
title: Response List Gsc Sites Workspace Workspace Id Integrations Search Console Sites Get
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/workspace/{workspace_id}/integrations/gamma/connect:
post:
tags:
- Integrations
summary: Connect Gamma
description: 'Connect Gamma integration by providing an API key.
The API key is encrypted and stored in workspace_integrations.
Optionally accepts a theme_id for workspace branding.'
operationId: connect_gamma_workspace__workspace_id__integrations_gamma_connect_post
security:
- HTTPBearer: []
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GammaConnectRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationStatusResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/workspace/{workspace_id}/integrations/wordpress/connect:
post:
tags:
- Integrations
summary: Connect Wordpress
description: 'Connect a self-hosted WordPress site via Application Password.
The credentials are validated against ``GET /wp-json/wp/v2/users/me`` before
persistence — invalid configurations never make it past this endpoint.
Returns the standard ``IntegrationStatusResponse`` so the frontend renders
the connected card without provider-specific branching.'
operationId: connect_wordpress_workspace__workspace_id__integrations_wordpress_connect_post
security:
- HTTPBearer: []
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WordPressConnectRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationStatusResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/workspace/{workspace_id}/integrations/wordpress/publish:
post:
tags:
- Integrations
summary: Wordpress Publish
description: 'Publish a post to the workspace''s connected WordPress site.
Pre-checks the per-workspace daily quota, then calls
``POST {site_url}/wp-json/wp/v2/posts`` with the resolved credentials.
Returns the canonical post URL from the WP response on success.
Failure modes (granular for clean frontend error routing):
- 400: WordPress not connected for this workspace
- 401: Connection needs reauthentication (App Password revoked)
- 403: User lacks publish permissions in WordPress
- 404: Configured site URL is no longer reachable
- 429: Daily quota exhausted (Retry-After header included)
- Other 4xx/5xx: surfaced verbatim with HTTP status preserved'
operationId: wordpress_publish_workspace__workspace_id__integrations_wordpress_publish_post
security:
- HTTPBearer: []
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/WordPressPublishRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/WordPressPublishResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/workspace/{workspace_id}/integrations/linkedin/publish:
post:
tags:
- Integrations
summary: Linkedin Publish
description: 'Publish a post to the workspace''s connected LinkedIn member account.
Pre-checks the daily quota (LinkedIn caps at 100 posts per member per
day), then calls /rest/posts with the resolved credentials. Returns
the LinkedIn post URN + view URL on success.
Failure modes (see LINKEDIN_PUBLISH_IMPLEMENTATION.md §6):
- 400: LinkedIn not connected, missing credentials, validation failures
- 401: integration is REAUTH_REQUIRED, or the access token is
revoked/expired (LinkedIn returns 401 — we surface verbatim)
- 422: Pydantic schema validation (e.g. article_url without title)
- 429: daily quota exhausted (Retry-After header included)
- 4xx/5xx from LinkedIn: surfaced verbatim with the LinkedIn error message'
operationId: linkedin_publish_workspace__workspace_id__integrations_linkedin_publish_post
security:
- HTTPBearer: []
parameters:
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/LinkedInPublishRequest'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/LinkedInPublishResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/workspace/{workspace_id}/integrations/{provider}/status:
get:
tags:
- Integrations
summary: Get Integration Status
description: Get status of a single integration.
operationId: get_integration_status_workspace__workspace_id__integrations__provider__status_get
security:
- HTTPBearer: []
parameters:
- name: provider
in: path
required: true
schema:
$ref: '#/components/schemas/IntegrationProvider'
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationStatusResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/workspace/{workspace_id}/integrations/{provider}/auth:
get:
tags:
- Integrations
summary: Initiate Oauth
description: 'Get OAuth authorization URL.
Any Google child provider (google_analytics, search_console) triggers the
same shared Google OAuth flow with both analytics + webmasters scopes.
LinkedIn uses its own flow with the openid/profile/email/w_member_social
scope set.
Frontend should redirect the user to the returned auth_url.
The state token is used for CSRF verification on callback.'
operationId: initiate_oauth_workspace__workspace_id__integrations__provider__auth_get
security:
- HTTPBearer: []
parameters:
- name: provider
in: path
required: true
schema:
$ref: '#/components/schemas/IntegrationProvider'
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/OAuthInitResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/workspace/{workspace_id}/integrations/{provider}/callback:
get:
tags:
- Integrations
summary: Oauth Callback
description: 'OAuth callback endpoint.
Exchange authorization code for tokens, encrypt, and store.
Stores credentials on google_oauth parent, marks requesting provider as connected.
If the user denies consent, Google redirects with ?error=access_denied
instead of a code -- this endpoint handles that gracefully.'
operationId: oauth_callback_workspace__workspace_id__integrations__provider__callback_get
security:
- HTTPBearer: []
parameters:
- name: provider
in: path
required: true
schema:
$ref: '#/components/schemas/IntegrationProvider'
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
- name: code
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Authorization code from OAuth provider
title: Code
description: Authorization code from OAuth provider
- name: state
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: CSRF state token
title: State
description: CSRF state token
- name: error
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Error code if user denied access
title: Error
description: Error code if user denied access
- name: error_description
in: query
required: false
schema:
anyOf:
- type: string
- type: 'null'
description: Human-readable error from provider
title: Error Description
description: Human-readable error from provider
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationStatusResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/workspace/{workspace_id}/integrations/{provider}:
delete:
tags:
- Integrations
summary: Disconnect Integration
description: 'Disconnect integration and clear stored credentials.
For Google child providers: clears config only, keeps OAuth alive for other services.
For google_oauth: cascades disconnect to all Google services.'
operationId: disconnect_integration_workspace__workspace_id__integrations__provider__delete
security:
- HTTPBearer: []
parameters:
- name: provider
in: path
required: true
schema:
$ref: '#/components/schemas/IntegrationProvider'
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/SuccessResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
/workspace/{workspace_id}/integrations/{provider}/config:
patch:
tags:
- Integrations
summary: Update Integration Config
description: 'Update provider-specific config (e.g. GA4 property_id, GSC site_url).
Does NOT modify credentials -- only the unencrypted config dict.'
operationId: update_integration_config_workspace__workspace_id__integrations__provider__config_patch
security:
- HTTPBearer: []
parameters:
- name: provider
in: path
required: true
schema:
$ref: '#/components/schemas/IntegrationProvider'
- name: workspace_id
in: path
required: true
schema:
type: string
format: uuid
title: Workspace Id
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationConfigUpdate'
responses:
'200':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/IntegrationStatusResponse'
'422':
description: Validation Error
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
OAuthInitResponse:
properties:
auth_url:
type: string
title: Auth Url
state:
type: string
title: State
type: object
required:
- auth_url
- state
title: OAuthInitResponse
description: Response from initiating an OAuth flow.
IntegrationListResponse:
properties:
integrations:
items:
$ref: '#/components/schemas/IntegrationStatusResponse'
type: array
title: Integrations
type: object
required:
- integrations
title: IntegrationListResponse
description: List of integration statuses for a workspace.
IntegrationConfigUpdate:
properties:
config:
additionalProperties: true
type: object
title: Config
description: 'Provider-specific configuration, e.g. {''property_id'': ''123456789''}'
type: object
required:
- config
title: IntegrationConfigUpdate
description: Request body for updating provider-specific config.
LinkedInPublishRequest:
properties:
commentary:
type: string
maxLength: 3000
minLength: 1
title: Commentary
description: The post body. LinkedIn renders newlines and basic links.
visibility:
type: string
enum:
- PUBLIC
- CONNECTIONS
title: Visibility
description: 'PUBLIC: visible to all LinkedIn users. CONNECTIONS: 1st-degree only.'
default: PUBLIC
article_url:
anyOf:
- type: string
maxLength: 2083
minLength: 1
format: uri
- type: 'null'
title: Article Url
description: URL to share with a preview card. Triggers article-share post.
article_title:
anyOf:
- type: string
maxLength: 200
- type: 'null'
title: Article Title
description: REQUIRED if article_url is set — LinkedIn does not scrape URLs.
article_description:
anyOf:
- type: string
maxLength: 300
- type: 'null'
title: Article Description
description: REQUIRED if article_url is set — appears under the title in the preview.
type: object
required:
- commentary
title: LinkedInPublishRequest
description: "Request body for `POST /workspace/{id}/integrations/linkedin/publish`.\n\nTwo valid shapes:\n1. Text-only post: just `commentary` (and optional `visibility`).\n2. Article share: `commentary` + `article_url` + `article_title` +\n `article_description`. LinkedIn does NOT scrape URLs — title and\n description must be user-supplied.\n\nImage and video posts are deferred to Phase 1.5 (Images API + Videos API\nrequire a separate asset-upload step, adding ~2h that doesn't pay off\nfor the MVP)."
IntegrationStatusResponse:
properties:
provider:
type: string
title: Provider
status:
type: string
title: Status
connected_at:
anyOf:
- type: string
- type: 'null'
title: Connected At
token_refreshed_at:
anyOf:
- type: string
- type: 'null'
title: Token Refreshed At
last_used_at:
anyOf:
- type: string
- type: 'null'
title: Last Used At
config:
additionalProperties: true
type: object
title: Config
type: object
required:
- provider
- status
title: IntegrationStatusResponse
description: Public-facing integration status. Never includes credentials.
LinkedInPublishResponse:
properties:
post_urn:
type: string
title: Post Urn
description: 'LinkedIn post URN. Format: urn:li:share:{id} or urn:li:ugcPost:{id}'
post_url:
type: string
title: Post Url
description: Public URL to view the post on LinkedIn
posted_at:
type: string
title: Posted At
description: ISO-8601 UTC timestamp when our server received the 201 response
remaining_daily_quota:
type: integer
title: Remaining Daily Quota
description: Posts remaining today against the 100-per-member-per-day cap
credits_used:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Credits Used
description: Reserved for parity with other publish surfaces. Always None for LinkedIn (free API).
type: object
required:
- post_urn
- post_url
- posted_at
- remaining_daily_quota
title: LinkedInPublishResponse
description: 'Response from a successful LinkedIn publish.
`post_urn` is the canonical identifier (e.g. `urn:li:share:6844...`) —
use this to look up the post later via the Posts API. `post_url` is the
human-friendly URL for showing the user "view your post on LinkedIn".'
WordPressConnectRequest:
properties:
site_url:
type: string
maxLength: 255
minLength: 1
title: Site Url
description: HTTPS URL of the WordPress site (no trailing slash, no /wp-json suffix needed)
username:
type: string
maxLength: 100
minLength: 1
title: Username
description: WordPress username
app_password:
type: string
maxLength: 255
minLength: 1
title: App Password
description: Application Password from WP Admin → Users → Application Passwords
type: object
required:
- site_url
- username
- app_password
title: WordPressConnectRequest
description: 'Body for ``POST /workspace/{id}/integrations/wordpress/connect``.
Site URL must be HTTPS and self-hosted (not ``*.wordpress.com``). Username
is the WordPress account name; ``app_password`` is an Application Password
issued in *WP Admin → Users → Application Passwords*. Spaces in the
rendered password are tolerated — the service strips them before storage.'
WordPressPublishRequest:
properties:
title:
type: string
maxLength: 200
minLength: 1
title: Title
content:
type: string
minLength: 1
title: Content
status:
type: string
enum:
- draft
- publish
- pending
- private
title: Status
description: Default 'draft'. Use 'publish' only after explicit user confirmation.
default: draft
categories:
anyOf:
- items:
type: integer
type: array
- type: 'null'
title: Categories
description: WordPress category IDs. Each must already exist in the target site.
tags:
anyOf:
- items:
type: integer
type: array
- type: 'null'
title: Tags
description: WordPress tag IDs. Each must already exist in the target site.
featured_media:
anyOf:
- type: integer
- type: 'null'
title: Featured Media
description: WordPress media library ID for the post's featured image.
type: object
required:
- title
- content
title: WordPressPublishRequest
description: 'Body for ``POST /workspace/{id}/integrations/wordpress/publish``.
Defaults to ``status=''draft''`` — the safer, HITL-aligned starting point.
The action-aware companion endpoint is the only path that should set
``status=''publish''`` in production flows, and only after frontend
confirmation. Server doesn''t enforce that gate; defaults to safer.'
example:
categories:
- 4
- 12
content: <p>Long-form HTML or block-rendered content here.</p>
status: draft
tags:
- 21
- 33
title: Why BMW's tech edge wins for first-time luxury buyers
SuccessResponse:
properties:
status:
type: string
title: Status
description: Response status
default: success
message:
type: string
title: Message
data:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Data
type: object
required:
- message
title: SuccessResponse
description: Generic success response.
WordPressPublishResponse:
properties:
post_id:
type: integer
title: Post Id
post_url:
type: string
title: Post Url
post_status:
type: string
title: Post Status
posted_at:
type: string
format: date-time
title: Posted At
remaining_daily_quota:
type: integer
minimum: 0.0
title: Remaining Daily Quota
description: Posts remaining today for this workspace before hitting the daily cap.
type: object
required:
- post_id
- post_url
- post_status
- posted_at
- remaining_daily_quota
title: WordPressPublishResponse
description: 'Result of a successful WordPress publish.
``post_url`` comes from the WP response''s ``link`` field — the canonical
permalink. Trust it; never reconstruct from site_url + post_id.'
GammaConnectRequest:
properties:
api_key:
type: string
minLength: 10
title: Api Key
description: Gamma API key
theme_id:
anyOf:
- type: string
- type: 'null'
title: Theme Id
description: Optional Gamma theme ID for workspace branding
type: object
required:
- api_key
title: GammaConnectRequest
description: Request body for connecting Gamma via API key.
IntegrationProvider:
type: string
enum:
- google_oauth
- google_analytics
- search_console
- looker_studio
- gamma
- linkedin_oauth
- wordpress
title: IntegrationProvider
description: Supported integration providers.
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