Skip to content

Integration Model

The White Label API is organized around one tenant boundary: the authenticated partner. API credentials authorize operations within that tenant, while workspaces group all resources for one customer website.

Resource ownership

flowchart TB
    P[Partner tenant] --> K[API credentials]
    P --> W[Workspace]
    W --> R[Visibility reports]
    W --> A[Actions]
    R --> A
    A --> E[Action executions]
    E --> O[Generated article<br/>or social post]
    O --> I[Article images]

API credential

A partner can have multiple server-to-server credentials. Each credential has its own scopes and may expire or be revoked. Credentials authorize operations but do not own resources. nBlick provisions and manages credentials outside the White Label API.

Workspace

A workspace is the logical container for one customer website. It belongs directly to the authenticated partner, not to an external actor or an nBlick user.

The same canonical website submitted again for the same partner returns the existing workspace. A workspace also stores the model-provider selection used by its reports.

Visibility report

A visibility report is one asynchronous analysis run for the website stored by its workspace. A workspace can contain multiple runs. A completed report includes visibility measurements, content opportunities, and actions.

Action

An action is a recommendation for a workspace. report_id identifies the report that most recently recommended it. Actions can remain available across report runs, so use the workspace action collection as the canonical list.

An action with executable: true can generate one of these outputs:

  • an article;
  • a LinkedIn post;
  • an X post;
  • a Reddit post.

Other action types describe work that the partner must complete outside this API.

Action execution and output

An execution is one asynchronous attempt to generate content from an action. It has its own status and attempt number. A successful execution exposes a separate output resource containing the generated article or social post.

Article outputs can include short-lived image URLs. The partner can retrieve those image bytes directly and can synchronously replace an existing article image slot through the image-generation endpoint.

External actor

X-External-Actor-Id is optional request metadata. Use it for a partner-side operator, service, job, or correlation identifier that is useful in support and trace workflows. It does not:

  • create or identify an nBlick account;
  • own or restrict a resource;
  • grant a role or permission;
  • replace the partner's own authorization checks.

Mapping partner resources

Use a workspace for each distinct website the partner wants to analyze. Store the returned workspace_id in the partner system and associate it with the correct customer account or project.

flowchart TB
    U[Partner user] -->|authorized by partner| B[Partner backend]
    B -->|Partner API key| A[nBlick White Label API]
    A --> W[Workspace]
    W --> R[Reports]
    W --> X[Actions and outputs]

Enforce user-level permissions in the partner system before calling nBlick. The White Label API credential authorizes the partner backend at tenant level; X-External-Actor-Id does not narrow that access.

Continue with Authentication & Hostnames for request requirements.