Skip to content

API Reference

Base URL

https://<partner-slug>.api.nblick.com

All JSON endpoints require:

Authorization: Bearer <partner-api-key>

They also accept:

Header Type Required Rules
X-External-Actor-Id string No Maximum 255 characters; trace metadata only

The article-image byte endpoint is the exception: follow the complete signed URL returned by an article output, without bearer authentication.

Endpoint summary

Method Path Purpose Authentication Success
POST /v1/workspaces Create or reuse a workspace workspaces:write 201
GET /v1/workspaces List partner workspaces workspaces:read 200
GET /v1/workspaces/{workspace_id} Retrieve a workspace workspaces:read 200
POST /v1/workspaces/{workspace_id}/visibility-reports Launch a report reports:write 202
GET /v1/workspaces/{workspace_id}/visibility-reports List workspace reports reports:read 200
GET /v1/visibility-reports/{report_id} Retrieve or poll a report reports:read 200
GET /v1/workspaces/{workspace_id}/actions List workspace actions actions:read 200
GET /v1/actions/{action_id} Retrieve an action and latest execution actions:read 200
POST /v1/actions/{action_id}/executions Launch content generation actions:write 202
GET /v1/action-executions/{execution_id} Retrieve or poll an execution actions:read 200
GET /v1/action-executions/{execution_id}/output Retrieve generated content actions:read 200
POST /v1/action-executions/{execution_id}/output/images/{image_index}/generate Generate or replace an article image actions:write 200
GET /v1/action-executions/{execution_id}/output/images/{image_index} Retrieve article image bytes Signed query URL 200

Identifiers

Treat every identifier as an opaque string. Prefixes identify the resource type; suffix length and alphabet are not part of the contract.

Resource Prefix Example
Workspace pws- pws-V1StGXR8_Z5jdHi6B-myT
Visibility report pvr- pvr-8xR2kQpL_5jdHi6B-myT
Action act- act-fG8kdE3yP0aX7sL2mN9qR
Action execution aex- aex-P6vB2nQ8rD4kW1yH7cM5t
Article output art- art-K9sD3fL6qT1vN8wC4xR2p
LinkedIn output lnk- lnk-W4mQ8dR2yT6pL1sN9cV3x
X output x- x-R8qL2dN5vT1mK7sC4yP9w
Reddit output rdt- rdt-C3mN7qR1vL8sT5yK2dW6p

Collection query parameters

GET /v1/workspaces, GET /v1/workspaces/{workspace_id}/visibility-reports, and GET /v1/workspaces/{workspace_id}/actions share:

Parameter Type Default Rules
limit integer 50 1–100
cursor string or null null Opaque cursor from the preceding page
created_after RFC 3339 date-time or null null Strict lower bound; timezone required
created_before RFC 3339 date-time or null null Strict upper bound; timezone required

Each also supports a status filter for its own status enum. Filters use AND. If both dates are set, created_after must be earlier than created_before.

Collection responses use:

{
  "data": [],
  "pagination": {
    "next_cursor": null,
    "has_more": false
  }
}

Use pagination.next_cursor on the next request while pagination.has_more is true. Results are ordered by created_at descending with id as a stable tie-breaker.

Workspace contract

The create request requires website and accepts an optional models array. Model IDs are openai, gemini, and claude. Each model object requires id and enabled. At least one provider must be enabled.

Workspace responses contain:

Field Type Nullable
id string No
website string No
status active or archived No
models array of {id, enabled} No
created_at date-time No
updated_at date-time Yes

See Workspaces for request and response examples for all three workspace endpoints.

Visibility report contract

Report statuses are queued, running, completed, and failed.

Field Type Nullable
id string No
workspace_id string No
status report status No
result object Yes
error string Yes
created_at date-time No
updated_at date-time Yes
completed_at date-time Yes

A completed result requires:

Field Type
report PartnerVisibilityAnalysisResponse
proposed_articles array of ContentOpportunity
action_list array of PartnerActionResponse

See Visibility Reports for complete typed fields and examples for launch, list, and flat report retrieval.

Action and execution contract

Action types:

create_article
create_linkedin_post
create_x_post
create_reddit_post
technical_change
check_llms_txt
check_robots_txt
request_third_party_mention

Action statuses:

recommended
generating
needs_review
completed
dismissed
snoozed
failed
superseded

Action execution statuses are queued, running, succeeded, and failed. Generated output types are article, linkedin_post, x_post, and reddit_post.

See Actions & Generated Content for action fields, type-specific payloads, execution overrides, article and social output schemas, and complete request and response examples.

Endpoint responses

Endpoint Relevant non-success responses
POST /v1/workspaces 401, 403, 422
GET /v1/workspaces 400, 401, 403, 422
GET /v1/workspaces/{workspace_id} 401, 403, 404, 422
POST /v1/workspaces/{workspace_id}/visibility-reports 401, 403, 404, 422, 503
GET /v1/workspaces/{workspace_id}/visibility-reports 400, 401, 403, 404, 422
GET /v1/visibility-reports/{report_id} 401, 403, 404, 422
GET /v1/workspaces/{workspace_id}/actions 400, 401, 403, 404, 422
GET /v1/actions/{action_id} 401, 403, 404, 422
POST /v1/actions/{action_id}/executions 401, 403, 404, 409, 422, 503
GET /v1/action-executions/{execution_id} 401, 403, 404, 422
GET /v1/action-executions/{execution_id}/output 401, 403, 404, 409, 422
POST /v1/action-executions/{execution_id}/output/images/{image_index}/generate 400, 401, 403, 404, 409, 422, 500
GET /v1/action-executions/{execution_id}/output/images/{image_index} 404, 422

Common machine-readable codes:

Status Code
401 invalid_partner_credentials
403 insufficient_scope
409 output_not_ready, article_output_required
422 invalid_created_range
503 report_not_queued, action_output_not_queued

See Permissions & Errors for every response shape and retry rule.

Interactive API descriptions

The partner hostname exposes a partner-only OpenAPI schema at /openapi.json and interactive views at /docs and /redoc. These routes use separately supplied HTTP Basic credentials.