Generate Pins from a URL
const url = 'https://api-v1.tailwind.ai/v1/accounts/example/generations';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"url":"https://example.com","title":"example","designTier":"basic","premiumStyle":"image-highlight","keywords":["example"]}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://api-v1.tailwind.ai/v1/accounts/example/generations \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "url": "https://example.com", "title": "example", "designTier": "basic", "premiumStyle": "image-highlight", "keywords": [ "example" ] }'Start a one-shot AI Pin generation from a source URL (SmartPin). Asynchronous: the response returns a generation id to poll with GET /v1/generations/{generationId}; resulting drafts appear in the posts list carrying a matching generationId. Each generation spends plan credits by design tier (resolved server-side). If a generation for the same URL is already in flight, the response returns that generation with deduplicated: true and NO additional credit is charged by this call. If the URL already has a SmartPin on this account, it is reused as-is (its stored tier is billed; caller tier parameters are ignored); a SmartPin for the URL on a different account is a 409 conflict.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Numeric Tailwind account ID returned by GET /v1/accounts
Request Bodyrequired
Section titled “Request Bodyrequired”object
Source page to generate Pins from (http/https). Query parameters and fragments are ignored for identity — variants of one page map to one SmartPin.
Display name for the SmartPin in the Tailwind dashboard. Defaults to the URL (truncated to 256 characters).
Design tier for the generated Pins. Determines the credit cost (approximately: 3 basic / 7 premium / 1 no-template, resolved server-side). Ignored when the URL’s existing SmartPin on this account is reused.
Visual style for premium generations. Required when designTier is “premium”; must be absent otherwise.
Keywords to guide the generated Pin copy.
Responses
Section titled “Responses”Generation accepted and processing
object
object
object
Generation ID. Poll GET /v1/generations/{generationId} with it.
The SmartPin record this generation runs against.
Effective design tier of the referenced generation (“template-match” can appear only when an existing record with that tier was reused).
Nominal per-generation credit cost of the referenced generation’s tier. When deduplicated is true, the response refers to an already-charged in-flight generation — no additional credit is charged by this call.
True when an existing SmartPin for this URL and account was reused (caller tier parameters ignored).
True when a generation for this URL was already in flight and its id is returned instead of starting (and charging) a new one.
object
Unique request ID for debugging
Example
{ "data": { "generation": { "status": "processing", "designTier": "basic" } }}Invalid request
object
object
Error code
Error message
Machine-readable denial reason. Present on PAYMENT_REQUIRED errors: insufficient_credits, trial_exhausted, no_access, account_not_connected.
object
Unique request ID for debugging
Example
{ "error": { "code": "BAD_REQUEST", "message": "Invalid request body" }, "meta": { "requestId": "abc123" }}Authentication required or invalid bearer credentials
object
object
Error code
Error message
Machine-readable denial reason. Present on PAYMENT_REQUIRED errors: insufficient_credits, trial_exhausted, no_access, account_not_connected.
object
Unique request ID for debugging
Example
{ "error": { "code": "UNAUTHORIZED", "message": "Invalid API key" }, "meta": { "requestId": "abc123" }}Billing denied — scheduling requires an available credit or trial allowance on the account
object
object
Error code
Error message
Machine-readable denial reason. Present on PAYMENT_REQUIRED errors: insufficient_credits, trial_exhausted, no_access, account_not_connected.
object
Unique request ID for debugging
Example
{ "error": { "code": "PAYMENT_REQUIRED", "message": "Not enough credits to schedule this post.", "reason": "insufficient_credits" }, "meta": { "requestId": "abc123" }}Resource not found
object
object
Error code
Error message
Machine-readable denial reason. Present on PAYMENT_REQUIRED errors: insufficient_credits, trial_exhausted, no_access, account_not_connected.
object
Unique request ID for debugging
Example
{ "error": { "code": "NOT_FOUND", "message": "Account not found" }, "meta": { "requestId": "abc123" }}Conflict: the URL’s SmartPin belongs to a different account in the organization, or a concurrent request for the same URL holds the generation lock (retry shortly)
Rate limit exceeded
object
object
Error code
Error message
Machine-readable denial reason. Present on PAYMENT_REQUIRED errors: insufficient_credits, trial_exhausted, no_access, account_not_connected.
object
Unique request ID for debugging
Example
{ "error": { "code": "RATE_LIMIT_EXCEEDED", "message": "Daily rate limit of 5000 requests exceeded. Resets at midnight UTC." }, "meta": { "requestId": "abc123" }}