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.
| Field | Location | Type | Required | Notes |
|---|---|---|---|---|
| x-access-key | Header | string token | Required for authenticated requests | Authorization header identifier; value shown as <token> in source |
Exact source contract
| Parameter | Type | Required | Description |
|---|---|---|---|
| accountId | string | No | Integration ID of the Pinterest account. If omitted, uses the first connected Pinterest account. |
Exact source contract
| Field | Type | Required | Description |
|---|---|---|---|
| success | boolean | Yes | 200 response field |
| boards | array<object> | Yes | Response array field containing board objects |
| boards[].id | string | Yes | Board identifier |
| boards[].name | string | Yes | Board name |
| boards[].description | string | null | Yes | Board description; may be null |
| boards[].privacy | string | Yes | Board privacy value; no enum values specified in source |
Exact source contract
| Status | Content type | Field | Type | Required | Notes |
|---|---|---|---|---|---|
| 404 | application/json | error | string | Yes | Error message value not specified |
| 502 | application/json | error | string | Yes | Error message value not specified |
Exact source contract; error causes not specified
curl -X GET "{{API_BASE_URL}}/v1/pinterest/boards" -H "x-access-key: <token>"curl -X GET "{{API_BASE_URL}}/v1/pinterest/boards?accountId=<accountId>" -H "x-access-key: <token>"{
"success": true,
"boards": [
{
"id": "string",
"name": "string",
"description": "string",
"privacy": "string"
},
{
"id": "string",
"name": "string",
"description": null,
"privacy": "string"
}
]
}{
"error": "string"
}| Scope | Field | Type | Type reference | Required | Description |
|---|---|---|---|---|---|
| accountId#1 | accountId | string | __0 | No | Integration ID of the Pinterest account. If omitted, uses the first connected Pinterest account. |
| response#2 | response | object | __0 | ||
| response#2 | response.success | boolean | __1 | Yes | |
| response#2 | response.boards | array<object> | __2 | Yes | |
| response#2 | response.boards[] | object | __3 | ||
| response#2 | response.boards[].id | string | __4 | Yes | |
| response#2 | response.boards[].name | string | __5 | Yes | |
| response#2 | response.boards[].description | string | null | __6 | Yes | |
| response#2 | response.boards[].description[variant1] | string | __6_type:string | ||
| response#2 | response.boards[].description[variant2] | null | __6_type:null | ||
| response#2 | response.boards[].privacy | string | __7 | Yes | |
| response#3 | response | object | __0 | ||
| response#3 | response.error | string | __1 | Yes |