Create post

POST

/v1/accounts/{accountId}/posts

curl --request POST \
  --url https://api-v1.tailwind.ai/v1/accounts/example/posts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "mediaUrl": "https://example.com", "mediaType": "image", "title": "example", "description": "example", "url": "https://example.com", "boardId": "example", "altText": "example", "sendAt": "2026-04-15T12:00:00Z", "isSimplifiedPin": true }'

• Production
• Development

Create a new post. If sendAt is provided, the post will be scheduled. Otherwise, it will be saved as a draft.

Authorizations

• bearerAuth

Parameters

Path Parameters

accountId

required

string

Numeric Tailwind account ID returned by GET /v1/accounts

Request Body^required

Media typeapplication/json

object

mediaUrl

required

URL of the media file to pin. Can be any publicly accessible URL — external media is automatically uploaded and processed.

string format: uri

mediaType

Type of media. Set to ‘video’ for video files (.mp4, .mov, .qt). Defaults to ‘image’ if omitted.

string

default: image

Allowed values: image video

title

Pin title. Required when sendAt is provided.

string

<= 100 characters

description

Pin description. Required when sendAt is provided.

string

<= 500 characters

url

Destination URL when pin is clicked. Required when sendAt is provided.

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. Required when sendAt is provided.

string

altText

Alt text for accessibility

string

<= 500 characters

sendAt

When to publish the pin. Must be in the future. If omitted, post is saved as draft. Requires boardId, title, description, and url.

string format: date-time

isSimplifiedPin

Whether to create a simplified pin. Defaults to true. Set to false for a standard pin.

boolean

default: true

Responses

201

Post created

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

title

Pin title

string

nullable

description

Pin description

string

nullable

url

Destination URL

string

nullable

boardId

Target board ID

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

meta

object

requestId

Unique request ID for debugging

string

Example

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

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.

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.

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

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.

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

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.

string

meta

object

requestId

Unique request ID for debugging

string

Example

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

422

Media could not be processed

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.

string

meta

object

requestId

Unique request ID for debugging

string

Example

{
  "error": {
    "code": "UNPROCESSABLE_ENTITY",
    "message": "Failed to process media URL. Ensure the URL is publicly accessible and points to a valid media file."
  },
  "meta": {
    "requestId": "abc123"
  }
}

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.

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