Content

Get a content opportunity

One opportunity in full: the prompts it covers, the score broken into its parts, what's blocking it, the sources to go after, how the published version is doing, and its history.

GEThttps://api.vidrys.com/v1/projects/{project_id}/content-assets/{asset_id}

Plan: Grow and above
Key: read
Rate cost: 1 unit
MCP tool: get_content_asset

curl --request GET \
  --url "https://api.vidrys.com/v1/projects/{project_id}/content-assets/{asset_id}" \
  --header "Authorization: Bearer $VIDRYS_API_KEY"

200 · success

{
  "asset": {
    "id": "d4e5f6a7-8b9c-40d1-92e3-4f5a6b7c8d9e",
    "title": "Comparison page — Acme Invoicing vs Northwind Billing",
    "category": "onsite",
    "state": "ready",
    "asset_type": "comparison",
    "audience_segment": "freelancers|india",
    "bullets": [
      "One step from winning — quality 0.43 against the 0.50 threshold on Perplexity",
      "6 competitor pages cited across 9 losing answers; none of yours",
      "Losing on 3 of 4 engines"
    ],
    "cluster_size": 3,
    "cluster_version": 2,
    "needs_review": false,
    "blocked": false,
    "draftable": true,
    "deliverable_label": null,
    "not_draftable_reason": null,
    "suggested_action": null,
    "suggested_source": null,
    "suggested_source_url": null,
    "suggested_target": null,
    "target_url": null,
    "prompt_ids": [
      "0e9a7c55-2b3d-4c1e-8f6a-9d0b1c2e3f4a",
      "b7c3d1e9-4a52-4f8b-91c6-3e5d7a9f2b10",
      "1f2e3d4c-5b6a-4790-8123-456789abcdef"
    ]
  },
  "score": 74,
  "classification": {
    "explanation": "Competitors' own pages are cited in the answers you lose, so a page of your own can compete.",
    "rule": "rule_2_vendor_pages_cited",
    "confidence": 0.62
  },
  "score_components": [
    {
      "name": "closeness",
      "value": 0.86,
      "points": 22.36
    },
    {
      "name": "reach",
      "value": 0.75,
      "points": 15
    },
    {
      "name": "cluster_size",
      "value": 0.63,
      "points": 10.08
    },
    {
      "name": "lever_confidence",
      "value": 0.62,
      "points": 8.68
    }
  ],
  "blocker_details": [],
  "target_url_conflict": null,
  "members": [
    {
      "prompt_id": "0e9a7c55-2b3d-4c1e-8f6a-9d0b1c2e3f4a",
      "text": "best invoicing software for freelancers in India",
      "similarity": 1
    }
  ],
  "fanout_questions": [
    "which invoicing tools support GST e-invoicing",
    "cheapest invoicing software for a solo consultant"
  ],
  "offsite_sources": [],
  "page_checks": null,
  "verification": [],
  "generations": [],
  "history": [
    {
      "created_at": "2026-09-14T06:12:08Z",
      "from_state": null,
      "to_state": "detected",
      "reason": "clustering",
      "actor": "system"
    },
    {
      "created_at": "2026-09-14T06:12:09Z",
      "from_state": "detected",
      "to_state": "ready",
      "reason": "clustering",
      "actor": "system"
    }
  ]
}

Authorization

Sent as a header on every request.

Authorizationstringrequired

A Vidrys API key, sent as Bearer vidrys_sk_…. A read key is enough. See Authentication.

Path parameters

project_idstringrequired

The project's id, from List projects.

asset_idstringrequired

The opportunity's id, from List content opportunities.

Response · 200

application/json

assetobject

The opportunity, as in the list.

+Show child attributes

idstring

Content-opportunity id.

titlestring

What to make, as the board shows it.

categorystring

onsite is a page to write or fix on your own site. offsite is a third-party page to get onto.

Values:onsiteoffsite

statestring

Where it is: ready to draft, blocked by a technical problem, generating, generated (a draft is waiting), verifying (published, being measured), won, stalled (published, nothing moved), dismissed, or one of the internal and terminal states.

Values:detectedreadyblockedgeneratinggeneratedverifyingwonstalledunaddressabledismissedarchivedmergedsplit

asset_typestring

The kind of page or asset to produce.

Values:comparisonpricingfaqdefinitiondocumentationintegrationhow-touse-caseproductcase-studytrust-signalsresearch

audience_segmentstringnullable

Who the prompts come from, e.g. startups or startups|india.

bulletsstring[]

Why it ranks here, strongest reason first. Up to three.

cluster_sizeinteger

Tracked prompts this one asset would answer.

cluster_versioninteger

Rises whenever the prompts in the cluster change.

needs_reviewboolean

True when the grouping is uncertain and worth a human glance.

blockedboolean

True while a hard technical problem on the site would waste the draft.

draftableboolean

Whether a draft can be written for it at all — research briefs and some off-site sources can't be drafted.

deliverable_labelstringnullable

What one credit buys here, e.g. page fixes, pitch email, review request. Null when it's a brand-new page.

not_draftable_reasonstringnullable

Why there's nothing to draft.

suggested_actionstringnullable

Off-site: what to do about the cited source.

suggested_sourcestringnullable

Off-site: the domain to get onto.

suggested_source_urlstringnullable

Off-site: the exact page cited.

suggested_targetstringnullable

Off-site: a readable name for that page.

target_urlstringnullable

On-site: the page being fixed, when it's an existing one.

prompt_idsstring[]

The tracked prompts in the cluster.

scoreinteger

Opportunity score the board ranks by. Normally 0–100; priority weighting can push it higher. 0 when it has never been scored.

classificationobject

Why this lever (write a page vs. get onto someone else's) was chosen.

+Show child attributes

explanationstringnullable

The reasoning in a sentence.

rulestringnullable

Which rule decided it.

Values:rule_0_unaddressablerule_1_refine_rejectedrule_2_vendor_pages_citedrule_3_aggregator_lockedrule_4_mixed_evidencerule_5_no_citationsescalationmanual

confidencenumber

How clear the evidence was, 0–1.

score_componentsobject[]

The bars behind the score. Empty until the opportunity has been scored.

+Show child attributes

namestring

closeness: how near the answers are to winning. reach: how many engines lose it. cluster_size: prompts covered. lever_confidence: how sure the lever is. winnability, urgency, ease: the rest of the ranking.

Values:closenessreachcluster_sizelever_confidencewinnabilityurgencyease

valuenumber

The signal itself, 0–1.

pointsnumber

What it contributed to the score.

blocker_detailsstring[]

The technical problems holding it back.

target_url_conflictstringnullable

Set when another opportunity is already being measured on the same page.

membersobject[]

The prompts in the cluster.

+Show child attributes

prompt_idstring

Prompt id.

textstring

The prompt.

similaritynumber

How well it fits the cluster, 0–1.

fanout_questionsstring[]

Sub-questions the piece should answer.

offsite_sourcesobject[]

Off-site only: the third-party pages worth being on, most cited first.

+Show child attributes

urlstringnullable

The page.

titlestringnullable

Its title.

domainstring

Its domain.

citationsinteger

Times answers cited this domain for prompts you lost.

presencestringnullable

Whether the brand is on that page already, and how it places. Null when the page couldn't be read.

Values:absentpresent_behindpresent_leading

deliverablestringnullable

What can be drafted for it. Null when nothing can.

Values:review_requestlisting_copysocial_postforum_replypitch_emailvideo_brief

actionstringnullable

What to do about it.

leading_competitorstringnullable

Who leads that page today.

selectedboolean

True for the source a draft would target.

page_checksobject[]nullable

How the existing page reads to an engine. Null unless this is a fix to a page we've been able to read.

+Show child attributes

idstring

Which check.

Values:answer_capsuletablefaq_blockexplicit_numbersdatessourcessection_lengthbyline

labelstring

Its name.

detailstring

What was found.

passedboolean

Whether it passed.

verificationobject[]

After publishing: how far each prompt has climbed on each engine.

+Show child attributes

prompt_idstring

Prompt id.

enginestring

Engine id.

Values:chatgptperplexitygeminicopilotai_overviewsclaude

runginteger

1 published, 2 crawled, 3 indexed, 4 cited, 5 mentioned, 6 recommended.

outcomestring

Where it has got to.

Values:pendingimprovedno_change

generationsobject[]

Every draft attempt, oldest first.

+Show child attributes

versioninteger

Which attempt, from 1.

kindstring

What was asked for.

Values:initialrefinementregeneration

statusstring

How it ended.

Values:pendingsucceededfailedrefunded

credit_consumedboolean

Whether it spent a credit.

historyobject[]

The state timeline, oldest first.

+Show child attributes

created_atstring

When (ISO 8601).

from_statestringnullable

State before. Null at creation.

to_statestring

State after.

Values:detectedreadyblockedgeneratinggeneratedverifyingwonstalledunaddressabledismissedarchivedmergedsplit

reasonstring

What caused it, e.g. user_action, generate, verification_won.

actorstring

Who did it. Never a name or an email.

Values:youa teammatesystem

Errors

404 not_found	The project or item doesn't exist in this workspace. A project from another workspace also returns 404, never 403.
401 unauthorized	No key was sent, or the key is unknown, revoked or expired, or the member who created it has left the workspace or been deactivated.
402 plan_required	The workspace's plan doesn't include API access. It's included on Grow, Scale and Custom.
403 workspace_not_approved	The workspace is still waiting for approval, or wasn't approved.
429 rate_limited	Too many requests this minute. Wait for the number of seconds in the `Retry-After` header, then retry.

Every code, and what to retry, is in Errors.