Skip to content

Getting Started

This guide walks you through installing the SDK, creating an app, and sending your first data — all in about 5 minutes.

1. Install the SDK

pip install meow-sdk

This also installs the meow CLI tool.

2. Get your API key

Sign up at meowmeowscratch.com, then go to Account > Platform Tokens and create a token. Store the key when it is created; the full value is only shown once.

Save your key

The full key is only shown once. If you lose it, revoke it and create a new one.

3. Create a client

from meow_sdk import Meow

api = Meow(api_key="YOUR_PLATFORM_TOKEN")

The client has three optional parameters:

Parameter What it does When you need it
api_key Authenticates your requests Writing data, managing apps, reading private endpoints
username Sets the username for public reads Reading someone's public endpoints
base_url Override the API URL (default: https://meowmeowscratch.com) Local development, self-hosted instances 
# Read-only (public endpoints)
api = Meow(username="jake")

# Read + write
api = Meow(username="jake", api_key="YOUR_PLATFORM_TOKEN")

# Local development
api = Meow("http://localhost:8099", api_key="YOUR_PLATFORM_TOKEN")

4. Create an app and endpoint

Apps are containers for your endpoints. Endpoints hold your data.

# Create an app
api.create_app("Weather Station", "weather-station")

# Add a collection endpoint for sensor readings
api.create_endpoint("weather-station", "Readings", "readings")

# Define the schema
api.create_field("weather-station", "readings",
    "temperature", "Temperature", "number")
api.create_field("weather-station", "readings",
    "humidity", "Humidity", "number")

Apps and endpoints are private by default. Pass is_public=True only when the data is safe for anonymous internet access.

Tip

You can also create apps and endpoints from the web dashboard — the SDK and website are interchangeable.

5. Send data

result = api.send("weather-station", "readings", {
    "temperature": 22.5,
    "humidity": 65,
})

print(result["uuid"])  # unique ID for this record

6. Read it back

page = api.records("weather-station", "readings")
print(page["count"])    # total records
print(page["results"])  # this page of records

api = Meow(username="jake")
data = api.get("weather-station", "readings")

Your public API lives at:

https://meowmeowscratch.com/api/v1/jake/weather-station/readings/

Anyone can read this URL — from a browser, curl, another Raspberry Pi, or a phone app.

7. Try the CLI

Set your credentials once:

export MEOW_PLATFORM_API_KEY=YOUR_PLATFORM_TOKEN
export MEOW_APP_API_KEY=YOUR_APP_API_KEY
export MEOW_USERNAME=jake

Then use the meow command:

# Send data
meow send weather-station readings temperature=22.5 humidity=65

# Read it back
meow get weather-station readings

# List your apps
meow apps

# See all commands
meow --help

Three types of endpoints

Type What it's for Example
collection Time-series data — each send() adds a new record Sensor readings, form submissions, event logs
static A single JSON blob — set_payload() replaces it Device status, config, feature flags
proxy Wraps an external API — meow caches and transforms it Weather API, stock prices, any third-party data 
# Collection — stores many records
api.create_endpoint("my-app", "Readings", "readings", "collection")
api.send("my-app", "readings", {"temp": 22.5})

# Static — one payload, overwritten each time
api.create_endpoint("my-app", "Status", "status", "static")
api.set_payload("my-app", "status", {"online": True, "version": "1.2"})

# Proxy — wraps an external URL
api.create_endpoint("my-app", "Weather", "weather", "proxy")
api.set_proxy("my-app", "weather", "https://api.weather.com/v1/current")

What's next