Skip to content
Tailwind API

Select a design variation

POST
/v1/accounts/{accountId}/posts/{postId}/design/variation
curl --request POST \
  --url https://api-v1.tailwind.ai/v1/accounts/example/posts/example/design/variation \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "templateImageUrl": "example" }'

Make one of the Pin’s already-rendered variations the active design. Free and instant: no rendering and no credits. The URL must be one this draft already carries - a templateImageUrl from the design read, the variationUrl a finished regeneration produced, or the pendingMediaUrl reported when workspaceStatus is pending_apply.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
accountId
required
string

Numeric Tailwind account ID returned by GET /v1/accounts

postId
required
string

Post ID

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
templateImageUrl
required

A variation URL this draft already carries

string
<= 2048 characters
Examplegenerated
{
  "templateImageUrl": "example"
}

Responses

Section titled “Responses”

200

Section titled “200”

The updated design

Media typeapplication/json
object
data
object
design

A generated Pin’s design, plus the operations this particular draft accepts.

object
postId
required
string
tier

How the Pin was generated. template and original are re-renderable; premium is AI-designed. Legacy values are normalized for display, which is why eligibility is reported separately in supportedOperations rather than inferred from this.

string
nullable
supportedOperations
required

The operations this draft actually accepts. Each entry mirrors the predicate its own endpoint enforces; anything absent here is rejected.

Array<string>
Allowed values: update regenerate select_variation revert
activeMediaUrl
required

The image the Pin will publish with

string
originalPhotoUrl
string
nullable
title

Text overlaid on the design, not the Pin’s title

string
nullable
colors
Array<string>
nullable
variations
required
Array<object>
object
templateImageUrl
string
templateGroupId
string
generationMethod
string
nullable
isActive
boolean
workspaceStatus
required

Pending_apply means a previous edit rendered a design the Pin never received. Apply pendingMediaUrl through the variation endpoint; no re-render is needed.

string
Allowed values: in_sync pending_apply
pendingMediaUrl

Present only when workspaceStatus is pending_apply

string
sourceImageCandidates

Returned by GET only. Source photos stored on the SmartPin that generated this Pin, as the SmartPin stands now rather than when this draft was generated. These are not designs: pass a url as mediaUrl to the design update endpoint, or to regenerate on a premium Pin.

object
status
required
string
Allowed values: available unavailable
reason

Present when status is unavailable. smart_pin_not_found: the SmartPin was deleted or the Pin predates the link. lookup_failed: temporary; read again.

string
Allowed values: smart_pin_not_found lookup_failed
userPicked
required

Images the user chose for the SmartPin. Empty when Tailwind picks images itself.

Array<string>
ranked
required

Images Tailwind scraped from the source page and scored at its latest ranking. Hosted by Tailwind.

Array<object>
object
url
required
string
quality
required
string
Allowed values: great good poor
aspectRatio
required

Width divided by height

number
meta
object
requestId

Unique request ID for debugging

string
Example
{
  "data": {
    "design": {
      "supportedOperations": [
        "update"
      ],
      "workspaceStatus": "in_sync",
      "sourceImageCandidates": {
        "status": "available",
        "reason": "smart_pin_not_found",
        "ranked": [
          {
            "quality": "great"
          }
        ]
      }
    }
  }
}

400

Section titled “400”

Invalid request

Media typeapplication/json
object
error
object
code

Error code

string
message

Error message

string
reason

Machine-readable reason. On PAYMENT_REQUIRED errors it is the denial reason: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded. Other errors may carry an operation-specific reason, such as pinterest_reconnect_required, pinterest_rate_limited, pinterest_timeout, pinterest_request_failed or list_boards_upstream_failed; each operation’s documented error responses show the values it returns. Branch on reason rather than parsing message.

string
resolve_url

Present on PAYMENT_REQUIRED errors: where the denial can be resolved. Reason-specific, because buying credits does not clear a trial, access or connection denial. Requests sent with X-Request-Source: mcp receive an informational plans page instead, so agent surfaces never present a purchase link.

string
meta
object
requestId

Unique request ID for debugging

string
Example
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid request body"
  },
  "meta": {
    "requestId": "abc123"
  }
}

401

Section titled “401”

Authentication required or invalid bearer credentials

Media typeapplication/json
object
error
object
code

Error code

string
message

Error message

string
reason

Machine-readable reason. On PAYMENT_REQUIRED errors it is the denial reason: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded. Other errors may carry an operation-specific reason, such as pinterest_reconnect_required, pinterest_rate_limited, pinterest_timeout, pinterest_request_failed or list_boards_upstream_failed; each operation’s documented error responses show the values it returns. Branch on reason rather than parsing message.

string
resolve_url

Present on PAYMENT_REQUIRED errors: where the denial can be resolved. Reason-specific, because buying credits does not clear a trial, access or connection denial. Requests sent with X-Request-Source: mcp receive an informational plans page instead, so agent surfaces never present a purchase link.

string
meta
object
requestId

Unique request ID for debugging

string
Example
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  },
  "meta": {
    "requestId": "abc123"
  }
}

404

Section titled “404”

Resource not found

Media typeapplication/json
object
error
object
code

Error code

string
message

Error message

string
reason

Machine-readable reason. On PAYMENT_REQUIRED errors it is the denial reason: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded. Other errors may carry an operation-specific reason, such as pinterest_reconnect_required, pinterest_rate_limited, pinterest_timeout, pinterest_request_failed or list_boards_upstream_failed; each operation’s documented error responses show the values it returns. Branch on reason rather than parsing message.

string
resolve_url

Present on PAYMENT_REQUIRED errors: where the denial can be resolved. Reason-specific, because buying credits does not clear a trial, access or connection denial. Requests sent with X-Request-Source: mcp receive an informational plans page instead, so agent surfaces never present a purchase link.

string
meta
object
requestId

Unique request ID for debugging

string
Example
{
  "error": {
    "code": "NOT_FOUND",
    "message": "Account not found"
  },
  "meta": {
    "requestId": "abc123"
  }
}

409

Section titled “409”

The Pin changed status mid-edit

429

Section titled “429”

Rate limit exceeded

Media typeapplication/json
object
error
object
code

Error code

string
message

Error message

string
reason

Machine-readable reason. On PAYMENT_REQUIRED errors it is the denial reason: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded. Other errors may carry an operation-specific reason, such as pinterest_reconnect_required, pinterest_rate_limited, pinterest_timeout, pinterest_request_failed or list_boards_upstream_failed; each operation’s documented error responses show the values it returns. Branch on reason rather than parsing message.

string
resolve_url

Present on PAYMENT_REQUIRED errors: where the denial can be resolved. Reason-specific, because buying credits does not clear a trial, access or connection denial. Requests sent with X-Request-Source: mcp receive an informational plans page instead, so agent surfaces never present a purchase link.

string
meta
object
requestId

Unique request ID for debugging

string
Example
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Daily rate limit of 10000 requests for this organization exceeded. Resets at midnight UTC."
  },
  "meta": {
    "requestId": "abc123"
  }
}

Headers

Section titled “Headers”
Retry-After
integer

Seconds until the daily limit resets at midnight UTC.