Skip to content
Tailwind API

Recommend Pins to add to a board

GET
/v1/accounts/{accountId}/boards/{boardId}/recommended-pins
curl --request GET \
  --url 'https://api-v1.tailwind.ai/v1/accounts/example/boards/example/recommended-pins?keyword=example&limit=10' \
  --header 'Authorization: Bearer <token>'

Pins from Pinterest’s public search worth adding to this board for a keyword, strongest first, each carrying the relevance tier that earned its place. Excludes Pins already on the board, promoted/ad content, and anything that does not clear the relevance threshold — so relevance is never poor, and an empty list means nothing on-topic was found rather than that the board is bad. These are public Pins from across Pinterest, not the account’s own. Free: no credit is checked or spent.

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

boardId
required
string

Numeric Pinterest board ID returned by GET /v1/accounts/{accountId}/boards. Tailwind’s own b_-prefixed CSV export format is accepted and normalized; board names and board URLs are rejected with a 400.

Query Parameters

Section titled “Query Parameters”
keyword
required
string
>= 1 characters <= 255 characters

The keyword or topic to find Pins for

limit
integer
default: 10 >= 1 <= 25

How many recommendations to return. Bounds the response only — every candidate is scored regardless, so the top result is the best of the whole candidate set.

Responses

Section titled “Responses”

200

Section titled “200”

Recommended Pins, strongest first. Empty when nothing cleared the threshold.

Media typeapplication/json
object
data
object
pins
required
Array<object>

A public Pinterest Pin worth adding to the board. Not one of the account’s own Pins — creating it still requires a post.

object
id
required

Pinterest Pin ID

string
title
required
string
nullable
description
required
string
nullable
link
required

Destination URL, when set

string
nullable
thumbnailUrl
required
string
nullable
relevance
required

How well this Pin matches the keyword. Never “poor” — weaker Pins are dropped rather than recommended.

string
Allowed values: excellent very-good good fair
meta
object
requestId

Unique request ID for debugging

string
Example
{
  "data": {
    "pins": [
      {
        "relevance": "excellent"
      }
    ]
  }
}

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

422

Section titled “422”

The account’s Pinterest connection is no longer usable. Your API key is fine — this is not an authentication failure on Tailwind’s side, which is why it is not a 401. The account holder needs to reconnect Pinterest in Tailwind before this operation can succeed.

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": "UNPROCESSABLE_ENTITY",
    "message": "Reconnect your Pinterest account to manage Boards.",
    "reason": "pinterest_reconnect_required"
  },
  "meta": {
    "requestId": "abc123"
  }
}

429

Section titled “429”

Too many distinct keyword searches from this org in a short window. This is Tailwind’s own limit protecting the upstream search, not Pinterest refusing — repeating the same keyword is served from cache and does not count against it.

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": "TOO_MANY_REQUESTS",
    "message": "Too many Pin searches in a short window. Wait a minute before requesting recommendations for another keyword.",
    "reason": "recommended_pins_rate_limited"
  },
  "meta": {
    "requestId": "abc123"
  }
}

502

Section titled “502”

Pinterest’s public Pin search could not be reached. Distinct from a Pinterest v5 fault on the board read: nothing about the board or the account is wrong, and the request can be retried.

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_GATEWAY",
    "message": "Could not search Pinterest for Pins right now. Nothing was changed, so this can be retried.",
    "reason": "recommended_pins_search_failed"
  },
  "meta": {
    "requestId": "abc123"
  }
}

503

Section titled “503”

Pinterest rate-limited the upstream read. Distinct from a 429, which means the caller’s own API-key limit — retry this request rather than backing off across the API.

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": "SERVICE_UNAVAILABLE",
    "message": "Could not read this board from Pinterest.",
    "reason": "pinterest_rate_limited"
  },
  "meta": {
    "requestId": "abc123"
  }
}

504

Section titled “504”

The request ran out of budget. Nothing was changed. reason: "recommended_pins_board_too_large" means the board itself has more Pins than can be read completely within one request — the board must be read in full, because a partial read would recommend Pins the board already holds. reason: "recommended_pins_timeout" means the request as a whole (board read, search, and scoring together) ran past budget without any single step being identifiably at fault.

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": "GATEWAY_TIMEOUT",
    "message": "This board holds too many Pins to read within one request. Nothing was changed.",
    "reason": "recommended_pins_board_too_large"
  },
  "meta": {
    "requestId": "abc123"
  }
}