Install the Meow SDK and Make Your First Request

Install the Meow SDK in an isolated Python environment, connect it safely to your account and send a temperature reading with a few lines of code.

This guide continues the Weather Station example from What Is an API? A Practical Beginner’s Guide. You will replace the raw curl command with a small Python program, then read the record back and handle the most common errors.

What you need

• Python 3.8 or newer
• A terminal
• A Meow Meow Scratch account
• A Weather Station app with a readings collection and required Number field named temperature
• A platform token for the account-wide learning exercise

If you have not created the Weather Station resources, complete the beginner API guide first. The names and slugs in this article assume that setup.

1. Check your Python version

Open a terminal and run:

python3 --version

You should see Python 3.8 or newer, for example:

Python 3.11.14

On Windows, the command may be py --version. If the command is not found or reports an older version, install a current Python 3 release before continuing.

2. Create a project and virtual environment

A virtual environment gives this project its own Python packages. It prevents one project’s dependencies from unexpectedly changing another project.

mkdir meow-sdk-quickstart
cd meow-sdk-quickstart
python3 -m venv .venv

Activate it on macOS, Linux, Git Bash or WSL:

source .venv/bin/activate

For Windows PowerShell, use:

.venv\Scripts\Activate.ps1

Your prompt will usually begin with (.venv) after activation. Confirm that the terminal is using the environment’s interpreter:

python --version
python -m pip --version

From this point onward, use python rather than python3. The activated virtual environment supplies the correct command.

3. Install the Meow SDK

Install the current release from PyPI:

python -m pip install meow-sdk

Using python -m pip is deliberate: it runs pip through the same Python interpreter that will run your program.

Verify the installed version and import:

python -c "import importlib.metadata as m; from meow_sdk import Meow; print(m.version('meow-sdk'))"

At the time this guide was tested, the command printed:

0.7.0

The exact version may be newer when you follow this guide. Check the meow-sdk package page on PyPI for the current release.

4. Choose the right credential

Credential	Scope	Use it for
Platform token	Resources across your account	SDK, CLI and account-wide automation
App API key	One app, with separate Read and Write scopes	Raspberry Pis, deployed devices and single-app integrations
No key	Public data only	Reading an endpoint that its owner deliberately made public

Use a platform token for this learning exercise because the SDK can work with account-level resources. Create one under Account → Platform Tokens.

On a deployed device, use an app API key whenever possible. If that device is lost or compromised, the key cannot reach unrelated apps. Grant only the Read and Write scopes the device actually needs.

Do not put a real token in the Python file. Do not commit one to Git or paste one into chat, an issue or a screenshot.

For a temporary terminal session on macOS, Linux, Git Bash or WSL, enter the token without placing it in your shell history:

read -s MEOW_PLATFORM_API_KEY
export MEOW_PLATFORM_API_KEY

Paste the token when the terminal waits for input, press Enter, then run the export command. Nothing appears while you paste because -s disables echo. The variable disappears when you close that terminal.

The current tools use MEOW_PLATFORM_API_KEY for account-wide access and MEOW_APP_API_KEY for one app. Do not use the ambiguous legacy name MEOW_API_KEY.

5. Send a reading and read it back

Create a file named first_request.py with this code:

import os

from meow_sdk import AuthError, Meow, MeowError, NotFoundError


api_key = os.environ.get("MEOW_PLATFORM_API_KEY")
if not api_key:
    raise SystemExit(
        "MEOW_PLATFORM_API_KEY is not set. "
        "Set it in your terminal, then run this program again."
    )

api = Meow(api_key=api_key, timeout=30)

try:
    created = api.send(
        "weather-station",
        "readings",
        {"temperature": 22.5},
    )
    print("Created record:", created["uuid"])
    print("Created data:", created["data"])

    page = api.records(
        "weather-station",
        "readings",
        limit=5,
    )
    print("Total records:", page["count"])
    print("Records returned:", len(page["results"]))

except AuthError:
    print("Authentication failed. Check your platform token.")
except NotFoundError:
    print("Check the weather-station and readings slugs.")
except MeowError as error:
    print(f"API error {error.status_code}: {error}")

Run it while the virtual environment is active:

python first_request.py

A successful run will resemble this:

Created record: 2d8e…your-record-uuid…91ab
Created data: {'temperature': 22.5}
Total records: 3
Records returned: 3

Your UUID and counts will be different. api.send() creates one record and returns it. api.records() reads a page of records through the authenticated management API. Its response includes count for the total and results for the records in the current page.

What each important line does

Code	Purpose
os.environ.get(...)	Reads the token from the current process environment instead of source code.
Meow(api_key=..., timeout=30)	Creates the API client, adds Bearer authentication and limits how long a request may wait.
api.send(...)	POSTs a new record to the selected collection.
created["uuid"]	Reads the unique identifier returned for the new record.
api.records(...)	GETs a paginated list through the authenticated management API.
except AuthError	Handles missing, invalid or disallowed authentication separately.

Public reads use a username

A deliberately public endpoint can be read without a key. Create a client with the owner’s username and call get():

from meow_sdk import Meow

api = Meow(username="YOUR_USERNAME")
data = api.get("YOUR_PUBLIC_APP", "YOUR_PUBLIC_ENDPOINT")
print(data)

Replace all three placeholders with a real public resource. This is different from records(): get() uses the stable consumer URL and requires a username, while records() uses authentication and can read private collections.

Troubleshooting

Problem	Likely cause	Fix
ModuleNotFoundError: No module named 'meow_sdk'	The SDK was installed into a different Python environment.	Activate .venv, then run python -m pip install meow-sdk again.
MEOW_PLATFORM_API_KEY is not set	The environment variable is missing from this terminal.	Enter and export the token, then rerun the program in the same terminal.
AuthError	The token is missing, invalid or not permitted.	Create or recopy the correct credential. Never print the token while debugging.
NotFoundError	An app or endpoint slug does not exist for this account.	Compare the web-app slugs with the two strings passed to the SDK.
ValidationError	The record does not match the endpoint schema.	Check required fields, field names and value types.
RateLimitError	The client is sending requests too quickly.	Slow down and retry with increasing delays.
meow: command not found	The virtual environment is inactive or its scripts directory is not on PATH.	Activate .venv and run meow --help again.

The installed package provides typed AuthError, NotFoundError, ValidationError, RateLimitError and general MeowError exceptions. Catching specific exceptions lets a program explain what the reader can actually fix.

The SDK also installed a CLI

The same package installs a meow command. Confirm it is available:

meow --help

The CLI can send and read records, manage apps and endpoints, work with dashboards and inspect limits. The Python client is the focus here because it gives you a foundation for scripts and devices; see the CLI reference when you want terminal-first automation.

Upgrade, leave or remove the environment

Upgrade the SDK inside the active environment with:

python -m pip install --upgrade meow-sdk

Leave the virtual environment without deleting it:

deactivate

If you no longer want the package in that environment, activate it and run:

python -m pip uninstall meow-sdk

What to build next

You now have an isolated Python project, a safely configured SDK client and a complete write-and-read loop. The natural next step is to display these readings in a dashboard, then replace the fixed value with data from a sensor or another program.

Keep the Meow Meow Scratch SDK documentation and complete SDK API reference nearby. The package source and issue tracker are in the meow-sdk GitHub repository.