{"id":8421,"library":"pinterest-api-sdk","title":"Pinterest API SDK","description":"The Pinterest API SDK is a Python library designed to simplify interaction with the Pinterest API v5. It provides functionalities for campaign management, streamlines authentication, and handles error reporting. The SDK is actively developed, with its current version being 0.2.6, and aims to expand its capabilities to cover organic Pins, shopping, analytics, and more over time.","status":"active","version":"0.2.6","language":"en","source_language":"en","source_url":"https://github.com/pinterest/pinterest-python-sdk","tags":["pinterest","api","sdk","marketing","ads","social media"],"install":[{"cmd":"pip install pinterest-api-sdk","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Internal HTTP request handling; version requirements were loosened in v0.2.5.","package":"urllib3","optional":false},{"reason":"Used for loading environment variables from .env files; version requirements were loosened in v0.2.5.","package":"python-dotenv","optional":false},{"reason":"Used for parsing YAML configurations; `yaml.safe_load` introduced in v0.2.6 for security.","package":"PyYAML","optional":false}],"imports":[{"note":"The primary client class is located within the 'pinterest.client' submodule, not directly under the top-level package.","wrong":"import pinterest_api_sdk","symbol":"PinterestSDKClient","correct":"from pinterest.client import PinterestSDKClient"},{"note":"Entity models are organized under specific API domains (e.g., `pinterest.ads`).","wrong":"from pinterest.models import AdAccount","symbol":"AdAccount","correct":"from pinterest.ads.ad_accounts import AdAccount"}],"quickstart":{"code":"import os\nfrom pinterest.client import PinterestSDKClient\nfrom pinterest.ads.ad_accounts import AdAccount\n\n# Set environment variables or create a .env file with PINTEREST_APP_ID, PINTEREST_APP_SECRET,\n# PINTEREST_ACCESS_TOKEN (or PINTEREST_REFRESH_ACCESS_TOKEN if using refresh token flow).\n# Example environment variables:\n# os.environ['PINTEREST_APP_ID'] = 'YOUR_APP_ID'\n# os.environ['PINTEREST_APP_SECRET'] = 'YOUR_APP_SECRET'\n# os.environ['PINTEREST_ACCESS_TOKEN'] = 'YOUR_ACCESS_TOKEN'\n\n# Create a default client (uses environment variables or config.json)\n# For production, consider using create_client_with_refresh_token for long-lived access\ntry:\n    client = PinterestSDKClient.create_default_client()\n    \n    # Example: List ad accounts\n    ad_accounts = AdAccount.get_all(client=client) # Pass client explicitly if not using default behavior\n    \n    if ad_accounts:\n        print(f\"Found {len(ad_accounts)} ad account(s).\")\n        for account in ad_accounts:\n            print(f\"  Ad Account ID: {account.id}, Name: {account.name}\")\n    else:\n        print(\"No ad accounts found or accessible.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Please ensure your Pinterest API credentials (APP_ID, APP_SECRET, ACCESS_TOKEN) are correctly set as environment variables or in a .env file.\")","lang":"python","description":"This quickstart demonstrates how to initialize the Pinterest SDK client using environment variables and retrieve a list of accessible ad accounts. Ensure your Pinterest App ID, Secret, and an Access Token (or Refresh Token) are configured as environment variables or in a `.env` file for the `create_default_client()` method to function."},"warnings":[{"fix":"Upgrade to pinterest-api-sdk v0.2.6 or newer: `pip install --upgrade pinterest-api-sdk`.","message":"Older versions (prior to v0.2.6) used `yaml.load`, which is insecure. This was updated to `yaml.safe_load` in v0.2.6. Applications parsing untrusted YAML with older versions may be vulnerable to arbitrary code execution.","severity":"breaking","affected_versions":"<0.2.6"},{"fix":"Always pass the `client` parameter to model methods if you are not exclusively using `PinterestSDKClient.create_default_client()` and expect its scope. This behavior was clarified and fixed in v0.2.2 regarding classmethod `create`.","message":"When creating multiple `PinterestSDKClient` instances or not relying on the globally configured default client, you must explicitly pass the `client` object to model methods (e.g., `AdAccount.get_all(client=my_custom_client)`). Forgetting this can lead to methods attempting to use an incorrect or uninitialized default client.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Ensure your Python environment and underlying OS libraries support and default to TLS 1.2+ for HTTPS connections. Most modern Python installations should handle this automatically, but older systems might require updates.","message":"Pinterest API v5 requires Transport Layer Security (TLS) version 1.2 or later. Older TLS protocols (1.0 and 1.1) are deprecated and will not work.","severity":"deprecated","affected_versions":"All versions using Pinterest API v5"},{"fix":"Avoid setting the `android_deep_link` parameter when creating or updating Ads through the SDK until Pinterest's API documentation indicates its availability.","message":"Using the `android_deep_link` field when creating an Ad via the SDK will currently generate an error as it is not yet available through the API.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Set `PINTEREST_APP_ID`, `PINTEREST_APP_SECRET`, and either `PINTEREST_ACCESS_TOKEN` or `PINTEREST_REFRESH_ACCESS_TOKEN` in your environment or a `.env` file. Alternatively, create a `config.json` file with these credentials.","cause":"The SDK client could not find required authentication credentials (APP_ID, APP_SECRET, ACCESS_TOKEN/REFRESH_TOKEN) in environment variables or a `config.json` file.","error":"pinterest.client.PinterestSDKClient.create_default_client() could not be instantiated"},{"fix":"Verify that your access token is current and has the correct permissions (scopes) for the API endpoint you are calling. If using a refresh token, ensure it's valid to obtain a new access token. Regenerate tokens if necessary.","cause":"The provided access token is invalid, expired, or does not have the necessary scopes for the requested API operation.","error":"requests.exceptions.HTTPError: 401 Client Error: Unauthorized for url: ..."},{"fix":"The correct import path for the main client is `from pinterest.client import PinterestSDKClient`.","cause":"Attempting to import `PinterestSDKClient` incorrectly, for example, `import pinterest.client.PinterestSDKClient` or `from pinterest import PinterestSDKClient`.","error":"AttributeError: module 'pinterest' has no attribute 'client'"}]}