Skip to content
Tailwind API

Update board list

PUT
/v1/accounts/{accountId}/board-lists/{boardListId}
curl --request PUT \
  --url https://api-v1.tailwind.ai/v1/accounts/example/board-lists/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "example", "boards": [ { "boardId": "example", "boardSectionId": "example" } ] }'

Replace a board list’s name and its full ordered set of boards. Send every board the list should hold, in publishing order: boards left out are removed from the list, and reordering is this same call with the boards in their new order. Removing a board from a list never changes the board or its Pins on Pinterest. Resubmitting the same body is safe and gives the same result.

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

boardListId
required
string

Numeric board list ID returned by GET /v1/accounts/{accountId}/board-lists

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
name
required

Board list name

string
>= 1 characters <= 255 characters
boards
required

Every board the list holds, in publishing order. Each board may appear once. Interval Pinning takes at most 20 boards per Pin, so a longer list cannot be passed whole as intervalBoards.

Array<object>
>= 1 items <= 100 items
object
boardId
required

Numeric Pinterest board ID from GET /v1/accounts/{accountId}/boards

string
boardSectionId

Pinterest board section ID, to target a section of that board

string
<= 255 characters
Examplegenerated
{
  "name": "example",
  "boards": [
    {
      "boardId": "example",
      "boardSectionId": "example"
    }
  ]
}

Responses

Section titled “Responses”

200

Section titled “200”

Board list updated

Media typeapplication/json
object
data
object
boardList
object
id

Board list ID

integer
name

Board list name; omitted when unnamed

string
accountId

Account ID

string
boards
Array<object>
object
id

Board ID

string
order

Order in the list

integer
boardSectionId

Pinterest board section ID, when the entry targets a section

string
meta
object
requestId

Unique request ID for debugging

string
Examplegenerated
{
  "data": {
    "boardList": {
      "id": 1,
      "name": "example",
      "accountId": "example",
      "boards": [
        {
          "id": "example",
          "order": 1,
          "boardSectionId": "example"
        }
      ]
    }
  },
  "meta": {
    "requestId": "example"
  }
}

400

Section titled “400”

Invalid request

Media typeapplication/json
object
error
object
code

Error code

string
message

Error message

string
reason

Machine-readable reason. On PAYMENT_REQUIRED errors it is the denial reason: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded. Other errors may carry an operation-specific reason, such as pinterest_reconnect_required, pinterest_rate_limited, pinterest_timeout, pinterest_request_failed or list_boards_upstream_failed; each operation’s documented error responses show the values it returns. Branch on reason rather than parsing message.

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 reason. On PAYMENT_REQUIRED errors it is the denial reason: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded. Other errors may carry an operation-specific reason, such as pinterest_reconnect_required, pinterest_rate_limited, pinterest_timeout, pinterest_request_failed or list_boards_upstream_failed; each operation’s documented error responses show the values it returns. Branch on reason rather than parsing message.

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

403

Section titled “403”

The account is no longer active in Tailwind, so its board lists cannot be changed (reason forbidden).

Media typeapplication/json
object
error
object
code

Error code

string
message

Error message

string
reason

Machine-readable reason. On PAYMENT_REQUIRED errors it is the denial reason: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded. Other errors may carry an operation-specific reason, such as pinterest_reconnect_required, pinterest_rate_limited, pinterest_timeout, pinterest_request_failed or list_boards_upstream_failed; each operation’s documented error responses show the values it returns. Branch on reason rather than parsing message.

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

404

Section titled “404”

The account or the board list was not found. A list that was deleted, or that belongs to another account, reads as not found (reason board_list_not_found).

Media typeapplication/json
object
error
object
code

Error code

string
message

Error message

string
reason

Machine-readable reason. On PAYMENT_REQUIRED errors it is the denial reason: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded. Other errors may carry an operation-specific reason, such as pinterest_reconnect_required, pinterest_rate_limited, pinterest_timeout, pinterest_request_failed or list_boards_upstream_failed; each operation’s documented error responses show the values it returns. Branch on reason rather than parsing message.

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": "Board list not found. Check the boardListId belongs to this account, from GET /v1/accounts/:accountId/board-lists."
  },
  "meta": {
    "requestId": "abc123"
  }
}

429

Section titled “429”

Rate limit exceeded

Media typeapplication/json
object
error
object
code

Error code

string
message

Error message

string
reason

Machine-readable reason. On PAYMENT_REQUIRED errors it is the denial reason: insufficient_credits, trial_exhausted, no_access, account_not_connected, legacy_post_limit_exceeded. Other errors may carry an operation-specific reason, such as pinterest_reconnect_required, pinterest_rate_limited, pinterest_timeout, pinterest_request_failed or list_boards_upstream_failed; each operation’s documented error responses show the values it returns. Branch on reason rather than parsing message.

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

Headers

Section titled “Headers”
Retry-After
integer

Seconds until the daily limit resets at midnight UTC.