Generate Pin copy

POST

/v1/copy-generations

curl --request POST \
  --url https://api-v1.tailwind.ai/v1/copy-generations \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "contentType": "lifestyle_content", "topic": "example", "keywords": [ "example" ], "cta": "example", "priorOutputs": [ { "title": "example", "description": "example" } ] }'

• Production
• Development

Generate Pinterest Pin titles and descriptions with Tailwind’s Ghostwriter, using the organization’s saved brand context so the copy matches how this account already writes, and saving the result to the account’s Ghostwriter history. Asynchronous: the response returns a job id to poll with GET /v1/copy-generations/{jobId}. Each generation spends plan credits and is charged when the request is accepted; on legacy (non-credit) plans an exhausted AI-credit balance is instead rejected synchronously as a 400. Org-scoped — no accountId is needed. This endpoint generates Pinterest Pin copy only; Tailwind’s other Ghostwriter generators are not exposed here.

Authorizations

• bearerAuth

Request Body^required

Media typeapplication/json

object

contentType

required

The angle the copy should take.

string

Allowed values: lifestyle_content featured_product seasonal_promotion behind_the_scenes education_content

topic

required

What the Pin is about — a product, post, or idea in the user’s words.

string

<= 500 characters

keywords

Keywords to work into the copy.

Array<string>

<= 10 items

cta

Call to action to end each Pin with.

string

<= 200 characters

priorOutputs

Copy you already have, so this generation varies from it rather than repeating it.

Array<object>

<= 10 items

object

title

string

description

string

Responses

202

Copy generation accepted and processing

Media typeapplication/json

object

data

object

generation

object

id

Copy generation ID. Poll GET /v1/copy-generations/{jobId} with it.

string

status

string

Allowed values: processing

creditCost

Credits this generation costs, charged when the request is accepted. 0 when the org’s free trial allowance covered it instead of a credit.

integer

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "data": {
    "generation": {
      "status": "processing"
    }
  }
}

400

Invalid request

Media typeapplication/json

object

error

object

code

Error code

string

message

Error message

string

reason

Machine-readable denial reason. Present on PAYMENT_REQUIRED errors: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded.

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 denial reason. Present on PAYMENT_REQUIRED errors: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded.

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

402

Billing denied — scheduling requires an available credit or trial allowance on the account, or would exceed the plan’s post limit for the billing period

Media typeapplication/json

object

error

object

code

Error code

string

message

Error message

string

reason

Machine-readable denial reason. Present on PAYMENT_REQUIRED errors: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded.

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": "PAYMENT_REQUIRED",
    "message": "Not enough credits to schedule this post.",
    "reason": "insufficient_credits"
  },
  "meta": {
    "requestId": "abc123"
  }
}

403

No Pinterest account exists to gate Ghostwriter against for this modular-billing org — connect one before generating.

429

Rate limit exceeded

Media typeapplication/json

object

error

object

code

Error code

string

message

Error message

string

reason

Machine-readable denial reason. Present on PAYMENT_REQUIRED errors: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded.

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 5000 requests exceeded. Resets at midnight UTC."
  },
  "meta": {
    "requestId": "abc123"
  }
}