Skip to content
Tailwind API

Update post

PATCH
/v1/accounts/{accountId}/posts/{postId}
curl --request PATCH \
  --url https://api-v1.tailwind.ai/v1/accounts/example/posts/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "title": "example", "description": "example", "url": "https://example.com", "boardId": "example", "boardSectionId": "example", "altText": "example", "productTagPinIds": [ "example" ] }'

Edit an unpublished Pin’s copy. Fields absent from the body are left unchanged. Only drafts and scheduled (queued) Pins can be edited — a Pin already published to Pinterest is terminal in Tailwind and must be edited in the Pinterest app. Editing does not consume credits. sendAt, status and the Pin’s media are deliberately not accepted here and are rejected with a message naming the operation that does handle them: scheduling goes through POST /v1/accounts/{accountId}/posts/{postId}/schedule, which is where putting a Pin on the schedule is charged — one credit on modular billing with Publishing access (winback plans excepted), and no credits on legacy and Shopify accounts, which count it against the plan’s post limit instead. title and description cannot be set to an empty string — a scheduled Pin left without them could not be published. Moving a Pin to a different board clears any board section it was in, since a section belongs to one board. productTagPinIds replaces the Pin’s tags wholesale — an empty array clears them, and omitting the field leaves them alone; tagging forces a simplified Pin, and tags are refused on a carousel Pin because Pinterest will not publish that combination. A 409 means the Pin changed status while the edit was being applied and the edit was not saved.

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

At least one field must be supplied. Fields you omit are left unchanged. sendAt, status, mediaUrl and uploadId are rejected rather than ignored — see the endpoint description.

object
>= 1 properties
title

Pin title

string
>= 1 characters <= 100 characters
description

Pin description

string
>= 1 characters <= 800 characters
url

Destination link for the Pin

string format: uri
boardId

Target board ID. Must be the numeric Pinterest board ID from GET /v1/accounts/{accountId}/boards — not a board name or URL. A leading “b_” (Tailwind CSV export format) is accepted and stripped.

string
boardSectionId

Section to publish into, validated against the board the Pin ends up on (boardId if you send one, otherwise its current board). Send “” to move the Pin to the board root. Supplying boardId WITHOUT this field clears any section the Pin already had, since a section is only valid on its own board. Use GET /v1/accounts/{accountId}/boards/{boardId}/sections to look up section IDs.

string
altText

Accessibility alt text

string
<= 500 characters
productTagPinIds

Pinterest product-catalog pin IDs to tag on the Pin, replacing any it already had (business accounts only; max 24). Send an empty array to remove every tag — omitting the field leaves the existing tags untouched. Tagging forces a simplified Pin, since Pinterest rejects tags on standard Pins. Rejected on carousel Pins, which Pinterest refuses to publish with tags; an empty array is still accepted on one, so tags can be cleared off it.

Array<string>
<= 24 items
Examplegenerated
{
  "title": "example",
  "description": "example",
  "url": "https://example.com",
  "boardId": "example",
  "boardSectionId": "example",
  "altText": "example",
  "productTagPinIds": [
    "example"
  ]
}

Responses

Section titled “Responses”

200

Section titled “200”

Updated post

Media typeapplication/json
object
data
object
post
object
id

Post ID

string
status

Post status

string
Allowed values: draft queued sent uploading
mediaUrl

URL of the media file

string
mediaType

Type of media

string
Allowed values: image video
carouselItems

Further images of a carousel Pin, in order after the cover in mediaUrl. Absent on a single-image Pin. Per-slide title, description and link are reported when the Pin carries them, but cannot be set through this API yet.

Array<object>
object
url

URL of this image

string
title

Per-slide title, when the Pin has one

string
description

Per-slide description, when the Pin has one

string
link

Per-slide destination, when the Pin has one

string
title

Pin title

string
nullable
description

Pin description

string
nullable
url

Destination URL

string
nullable
boardId

Target board ID

string
nullable
boardSectionId

Section of boardId the Pin publishes into. Null when it publishes to the board root.

string
nullable
altText

Alt text for accessibility

string
nullable
sendAt

Scheduled send time (Unix timestamp)

integer
nullable
sentAt

Actual send time (Unix timestamp)

integer
nullable
createdAt

Creation time (Unix timestamp)

integer
pinId

Pinterest pin ID (only present after publishing)

string
nullable
isSimplifiedPin

Whether this is a simplified pin (as opposed to a standard pin)

boolean
productTagPinIds

Pinterest product-catalog pin IDs tagged on the pin (business accounts only).

Array<string>
generationId

ID of the AI generation that produced this post, when it was generated from a URL (matches the id returned by POST /v1/accounts/{accountId}/generations). Absent for posts created any other way.

string
nullable
meta
object
requestId

Unique request ID for debugging

string
Example
{
  "data": {
    "post": {
      "status": "draft",
      "mediaType": "image"
    }
  }
}

400

Section titled “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

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

404

Section titled “404”

Resource not found

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": "NOT_FOUND",
    "message": "Account not found"
  },
  "meta": {
    "requestId": "abc123"
  }
}

409

Section titled “409”

The Pin changed status while the edit was being applied — it is no longer a draft or scheduled Pin, and the edit was not saved.

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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "reason": "example",
    "resolve_url": "example"
  },
  "meta": {
    "requestId": "example"
  }
}

429

Section titled “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"
  }
}