Skip to content

List Pinterest Boards API

The List Pinterest Boards API lists Pinterest boards for a connected account. Use it when you need to discover the boards available to that account before selecting a board for a later workflow, and parse either the boards array on success or the error field on failure.

List Pinterest Boards API overview

The List Pinterest Boards API uses GET {{API_BASE_URL}}/v1/pinterest/boards to list Pinterest boards for a connected account. Send the request with the x-access-key header set to your token. The endpoint returns application/json for every documented status, so your client should branch on the HTTP status before reading the body. On a 200 response, read success and boards. On a 404 or 502 response, read error. When you have more than one connected Pinterest account, pass accountId explicitly to select the account you want.

Authorization

Authorization uses the x-access-key header. Place the token in that header on every request to GET {{API_BASE_URL}}/v1/pinterest/boards. The source contract for this endpoint does not document a specific status for a missing or invalid header, so do not assume one from this page alone. Keep the token out of URLs and query strings, and do not log the full header value in client-side diagnostics.

Query Parameters

The only documented query parameter is accountId, a string. It is the integration ID of the Pinterest account. When accountId is omitted, the request uses the first connected Pinterest account. When you need a specific account, pass accountId explicitly as a query parameter. The source does not specify additional validation rules for this parameter beyond its type and optional status.

Response Body

A 200 response returns success as a required boolean and boards as a required array. Each item in boards is an object with required id, name, description, and privacy fields. The id, name, and privacy fields are strings. The description field is required but its type is string or null, so handle a null description explicitly instead of assuming every board has text. Use id to identify a board, name for display, description for descriptive text when present, and privacy to record the board privacy value returned by the API. The source contract does not define a fixed set of privacy values, so do not restrict parsing to an invented enum.

Error responses

A 404 response returns application/json with a required error string. A 502 response also returns application/json with a required error string. The documented contract distinguishes these failures by status code, but it does not specify the exact error message values or the semantic conditions that produce each status. Your client should therefore preserve the status code alongside the error message and surface both in diagnostics. Only parse boards after confirming a 200 status.

Worked example

To list boards for the default connected account, send GET {{API_BASE_URL}}/v1/pinterest/boards with the x-access-key header and no query parameter. To list boards for a specific account, add accountId to the query string while keeping the method, path, and header unchanged. After the call, check the status first: for 200, iterate boards and read each board id, name, description, and privacy; for 404 or 502, read error and stop. A practical failure check is to confirm that description is either a string or null before rendering it, as shown in the 200 success response example.

Authorization header
FieldLocationTypeRequiredNotes
x-access-keyHeaderstring tokenRequired for authenticated requestsAuthorization header identifier; value shown as <token> in source

Exact source contract

Query parameters
ParameterTypeRequiredDescription
accountIdstringNoIntegration ID of the Pinterest account. If omitted, uses the first connected Pinterest account.

Exact source contract

200 response fields
FieldTypeRequiredDescription
successbooleanYes200 response field
boardsarray<object>YesResponse array field containing board objects
boards[].idstringYesBoard identifier
boards[].namestringYesBoard name
boards[].descriptionstring | nullYesBoard description; may be null
boards[].privacystringYesBoard privacy value; no enum values specified in source

Exact source contract

Error response fields
StatusContent typeFieldTypeRequiredNotes
404application/jsonerrorstringYesError message value not specified
502application/jsonerrorstringYesError message value not specified

Exact source contract; error causes not specified

List Pinterest boards request
curl -X GET "{{API_BASE_URL}}/v1/pinterest/boards" -H "x-access-key: <token>"
List Pinterest boards request with accountId
curl -X GET "{{API_BASE_URL}}/v1/pinterest/boards?accountId=<accountId>" -H "x-access-key: <token>"
200 success response
{
  "success": true,
  "boards": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "privacy": "string"
    },
    {
      "id": "string",
      "name": "string",
      "description": null,
      "privacy": "string"
    }
  ]
}
404 and 502 error response
{
  "error": "string"
}
Interface fields
ScopeFieldTypeType referenceRequiredDescription
accountId#1accountIdstring__0NoIntegration ID of the Pinterest account. If omitted, uses the first connected Pinterest account.
response#2responseobject__0
response#2response.successboolean__1Yes
response#2response.boardsarray<object>__2Yes
response#2response.boards[]object__3
response#2response.boards[].idstring__4Yes
response#2response.boards[].namestring__5Yes
response#2response.boards[].descriptionstring | null__6Yes
response#2response.boards[].description[variant1]string__6_type:string
response#2response.boards[].description[variant2]null__6_type:null
response#2response.boards[].privacystring__7Yes
response#3responseobject__0
response#3response.errorstring__1Yes