ppl resources · Client guides

Read your ppl briefing with Python

A small Python example that reads a ppl briefing with a scoped token, handles errors, and keeps credentials out of source files.

Updated October 10, 2026 · ppl team

A briefing does not need a large agent framework. A small Python script can read birthdays, reconnect suggestions, and open tasks from ppl, then hand that information to the assistant or daily routine you already use.

Start with a scoped token

Sign in to ppl and open Settings > API Keys. Create a token and select the agent:briefing permission. Store it as the PPL_API_TOKEN environment variable in your own runtime. Do not paste it into the script, a URL, a public notebook, or a repository. The token grants access to account information; treat the returned briefing as private too.

The following example makes one read request, uses a timeout, and avoids printing credentials or server error bodies:

import json
import os
import sys
from urllib.error import HTTPError, URLError
from urllib.request import Request, urlopen

token = os.environ.get("PPL_API_TOKEN")
if not token:
    sys.exit("Set PPL_API_TOKEN before running this script.")

request = Request(
    "https://withppl.com/api/agent/briefing",
    headers={
        "Authorization": "Bearer " + token,
        "Accept": "application/json",
    },
)
try:
    with urlopen(request, timeout=30) as response:
        briefing = json.load(response)
except HTTPError as error:
    sys.exit("ppl request failed with HTTP " + str(error.code))
except (URLError, TimeoutError):
    sys.exit("Could not reach ppl. Check the connection and try again.")
except (ValueError, UnicodeError):
    sys.exit("ppl returned a response this script could not read.")

print(json.dumps(briefing, indent=2))

Save it as briefing.py and run python3 briefing.py in the environment where the variable is available. Output appears in your terminal. Run it somewhere appropriate for private relationship information, rather than a public build log.

Check the first result yourself

Open ppl and compare the returned birthdays, tasks, or contacts with your account. HTTP 401 usually means the token is missing, expired, or invalid. HTTP 403 means access was refused; check the token’s permissions instead of repeatedly retrying. A valid response with no upcoming items may simply mean there is nothing to report.

Add a schedule only when you want one

The script runs when you invoke it. It does not schedule itself, send a daily email, or message a contact. If you add it to an existing scheduler, choose where the private output goes and how failures reach you. Keep the first version read-only until you have checked its behavior.

A maintained version of this example, with setup notes and tests, is available in the public ppl Python examples. For API authentication and the browser-approved connect flow used by agents, see the ppl integration guide and the machine-readable service description.