Get a Pin's design

GET

/v1/accounts/{accountId}/posts/{postId}/design

curl --request GET \
  --url https://api-v1.tailwind.ai/v1/accounts/example/posts/example/design \
  --header 'Authorization: Bearer <token>'

• Production
• Development

Read the design of a Pin that SmartPin generated: its tier, every variation already rendered, and supportedOperations - the operations this particular draft accepts. Read this before any design write and follow supportedOperations, because the available operations differ by tier and calling an unsupported one is rejected. workspaceStatus reports whether the design metadata and the Pin agree; pending_apply means an earlier edit rendered a design the Pin never received, and pendingMediaUrl is what to pass to the variation endpoint to finish applying it, with no re-render. sourceImageCandidates lists the other source photos stored on the SmartPin behind this Pin; pass one as mediaUrl to the update endpoint (or to regenerate on a premium Pin) to rebuild the design around it.

Authorizations

• bearerAuth

Parameters

Path Parameters

accountId

required

string

Numeric Tailwind account ID returned by GET /v1/accounts

postId

required

string

Post ID

Responses

200

The Pin’s 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

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

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

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"
  }
}

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

Retry-After

integer

Seconds until the daily limit resets at midnight UTC.