Content

Generate a draft

Start writing the draft for an opportunity. This spends one of the month's content credits, so it needs confirm_credit: true and an idempotency key.

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

Plan: Scale and Custom
Key: read-and-write
Rate cost: 1 unit
MCP tool: generate_draft

Drafting runs in the background: this returns 202 with the generation pending, and the text arrives at Get the latest draft.

Send the same idempotency_key when you retry. A repeat of a key you have used before returns the original generation instead of spending a second credit.

Drafting is also rate-limited on its own: at most 10 generations a minute per workspace, dashboard ones included.

Generate a draft

curl --request POST \
  --url "https://api.vidrys.com/v1/projects/{project_id}/content-assets/{asset_id}/generate" \
  --header "Authorization: Bearer $VIDRYS_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
  "idempotency_key": "acme-comparison-2026-09-22",
  "confirm_credit": true
}'

202 · success

{
  "asset_id": "d4e5f6a7-8b9c-40d1-92e3-4f5a6b7c8d9e",
  "generation_version": 1,
  "status": "pending",
  "credit_consumed": true
}

Authorization

Sent as a header on every request.

Authorizationstringrequired

A Vidrys API key, sent as Bearer vidrys_sk_…. This call changes data, so the key must be read-and-write. See Authentication.

Path parameters

project_idstringrequired

The project's id, from List projects.

asset_idstringrequired

The opportunity's id, from List content opportunities.

Body

application/json

idempotency_keystringrequired

Your own key for this attempt, 1–128 characters. Reuse it on retries.

confirm_creditbooleandefault false

Send true to proceed. Left out, the call answers confirmation_required and nothing is spent.

Response · 202

application/json

asset_idstring

The content opportunity being drafted.

generation_versioninteger

Which draft this is for the opportunity, counting from 1.

statusstring

pending on a new request. A replayed idempotency_key returns the original generation's current status. refunded is a failure whose credit was returned.

Values:pendingsucceededfailedrefunded

credit_consumedboolean

Whether this generation spent a content credit.

Errors

403 write_not_allowed	The key is read-only. Writes need a read-and-write key, and read-and-write keys need Scale or Custom.
422 confirmation_required	A draft spends a content credit, and the call didn't confirm it with `confirm_credit: true`.
402 credits_exhausted	This month's content credits are used up. Retrying won't help until the credits reset on the 1st (UTC).
402 payment_required	The plan doesn't include this capability for the project, or the workspace has reached its daily usage limit. Drafting a content opportunity is the call that can return it.
409 conflict	The item isn't in a state that allows the change — for example marking an opportunity published before it has a draft, or drafting one that is already being drafted.
404 not_found	The project or item doesn't exist in this workspace. A project from another workspace also returns 404, never 403.
422 invalid_request	A parameter or body field is missing or has the wrong type or value. The message names the field. Also returned when a write would pass the plan's prompt limit.
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.