Skip to content
Tailwind API

Create post

POST
/v1/accounts/{accountId}/posts

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

Authorizations

Parameters

Path Parameters

accountId
required
string

Pinterest account ID

Request Body required

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. 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

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

400

Invalid request

object
error
object
code

Error code

string
message

Error message

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 API key

object
error
object
code

Error code

string
message

Error message

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

object
error
object
code

Error code

string
message

Error message

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

object
error
object
code

Error code

string
message

Error message

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