parse-sdk

Typed Python SDK tooling for Parse APIs.

Requires Python 3.10 or newer.

parse-sdk is the shared runtime + CLI. It generates a project-local parse_apis package — a real, installed, editable dependency — that holds the typed client for every API your key can call. Your application code imports from parse_apis; parse-sdk provides the runtime bases and errors those clients use.

SDK and MCP

Use Parse MCP when an agent is discovering or calling APIs ad hoc, or managing account-owned server-side variants. Use this SDK for durable, typed Python clients committed to an application. Neither requires the other: the SDK can use parse search and parse add --marketplace <listing_id> without creating an MCP subscription.

Quickstart

In a uv-managed project (uv init first if you don't have a pyproject.toml):

uv add parse-sdk            # installs the runtime + `parse` CLI into your project
uv run parse init           # prompts for your API key, then scaffolds + syncs parse_apis

Non-interactive (CI, agents, scripts): export PARSE_API_KEY, then run uv run parse init. parse login --api-key persists a key, but is a less-safe automation fallback because argv can be recorded in process listings and shell history.

parse init is the one-time setup. It:

1. ensures credentials (prompts and stores to ~/.config/parse/credentials, or run parse login first);
2. creates the committed parse_apis scaffold;
3. records parse_apis as an editable path dependency (and a [tool.uv.sources] entry);
4. appends a deny-by-default .gitignore block (commits the scaffold, ignores generated payload);
5. migrates — or safely refuses — any legacy flat parse_apis/ layout;
6. runs the first parse sync.

Then use it:

from parse_apis.reddit_com_api import Reddit   # generated, typed client (slugs look like <domain>_<tld>_api)
from parse_apis import RateLimitError          # runtime errors, re-exported

reddit = Reddit()                              # picks up `parse login` credentials
try:
    # Navigate from a constructible resource, with a bounded fetch:
    for post in reddit.subreddit("smallbusiness").search_posts(query="hiring", limit=10):
        print(post.title)
except RateLimitError:
    ...

(The exact methods are generated from your API's spec — parse_apis/src/parse_apis/<slug>/README.md and example.py document each client's real surface.)

uv run python app.py        # run your app in the project environment
uv run parse sync           # later: refresh after you change APIs in Parse

Running commands (uv run vs. activation)

uv add parse-sdk installs the parse console script into your project's .venv, which isn't on your shell PATH by default. Two equivalent ways to reach it:

• uv run parse <cmd> — runs the venv's parse with no activation, auto-syncing first. (Recommended.)
• source .venv/bin/activate then parse <cmd> directly.

Prefer one of these over a global uv tool install parse-sdk: codegen must run with the same pinned parse-sdk your project runs against (see Versioning below), and a global copy can drift out of sync. Your end users running their app never invoke parse — they just import parse_apis.

On-disk layout

parse_apis/
  AGENTS.md  CLAUDE.md           # committed, byte-identical agent pointers
  pyproject.toml                 # committed: name="parse-apis", pinned parse-sdk==X
  src/parse_apis/
    __init__.py                  # committed scaffold — re-exports runtime errors
    py.typed                     # committed
    reddit_com_api/__init__.py   # generated (gitignored)
    _manifest.json               # generated (gitignored)
    AGENTS.md  CLAUDE.md         # generated cross-API index (gitignored)

Commit the five scaffold files; the generated payload is per-key (it reveals your API inventory) and stays gitignored. parse sync builds the next payload in a staging tree, self-tests it (secret scan, import-model, no-stale-docs), and promotes it with an atomic directory swap — a failed sync never leaves broken or secret-bearing files in your project.

Import model

• Application code imports generated clients from parse_apis.<slug>.
• Runtime errors/base types are re-exported from parse_apis (sourced from parse_sdk).
• Because parse_apis is an installed editable package, imports resolve from any directory — no sys.path or editor extraPaths tricks.
• Generated files are project-local and differ per Parse API key.

Fresh clone & CI (post-publish)

uv sync                     # installs deps incl. the editable parse_apis scaffold
uv run parse sync           # regenerate the per-key payload
uv run pytest && uv run pyright   # pyright must run against the PROJECT env —
                                  # add both as dev deps (`uv add --dev pytest pyright`);
                                  # a bare/global `pyright` can't resolve parse_apis

The committed scaffold is a valid dependency target before any slugs exist, so uv sync succeeds on a clean checkout.

CLI

Command	What it does
parse login	Save browser OAuth credentials by default, or an API key with --api-key. No project changes.
parse init	One-time: ensure creds, scaffold parse_apis, record deps + gitignore, first sync. Pass slugs to track just those APIs.
parse list	Print the APIs the current key can call (no generation).
parse sync	Regenerate the typed payload into parse_apis/src/parse_apis (staged + atomic). --check is a CI dry run.
parse add	Add APIs to the repo's synced set (--marketplace for shared canonicals; new entries pin the latest usable release, while re-add preserves existing pin/live state), then reconcile.
parse remove	Stop syncing APIs (account or marketplace) and prune their generated clients.
parse search	Search the Parse marketplace for ready-made APIs.
parse clean	Remove generated payload; keep the committed scaffold.
parse whoami	Show the current key + base URL.
parse doctor	Diagnose the project's SDK install; --fix applies safe remediations.
parse help	Guided getting-started workflow (--json for machine-readable orientation).

Run parse <cmd> --help for full per-command help — every command's help ends with copy-pasteable Examples.

Agents & automation

The CLI is built to run headless: prompts only fire on an interactive terminal (non-TTY runs fail fast with the exact fix), warnings go to stderr, and stdout stays machine-parseable under --json.

Machine-readable output. parse help --json is the orientation entrypoint: it lists every command with requires_auth / requires_init facts and (under agent_modes) which commands accept --json — the list is derived from the live command registry, so it never goes stale. The --json shapes are stable:

Command	Shape
whoami --json	object: base_url, api_key_masked, key_configured, key_sent_to_host, web_login, auth_method
list --json	array of {id, slug, name, modeled, endpoints, resources, version}
sync / add / remove --json	object: written[] {slug, id, root, status, warnings[]}, skipped[] {slug, id, reason}, removed[], quarantined[] {slug, id, retained, findings[]}, failures[] — on a gate abort, {failures} alone with exit 1; under sync --check, failures carries every finding (non-empty ⟺ exit 1)
doctor --json	object: ok, findings[] {level, title, detail, fix, kind}
search --json	array of {id, slug, name, source_url, endpoint_count, is_authenticated}

Exit codes. 0 — success. 1 — the command ran and detected a problem (sync's pre-promotion gate abort, sync --check findings, doctor error-level findings, init refusing to migrate a legacy tree with non-Parse files, a lost concurrent-promote race). 2 — the command couldn't run: usage errors, an uninitialized project, missing/withheld credentials or an untrusted host, network failures.

Credentials in automation. Prefer exporting PARSE_API_KEY over passing --api-key on the command line — argv is visible in process listings and shell history. parse login (browser OAuth by default; --web is explicit) requires an interactive terminal and fails fast headless.

Versioning

parse_apis/pyproject.toml pins the exact parse-sdk it was generated against — generated code subclasses the runtime by name. After upgrading parse-sdk, re-run parse sync to regenerate against the new runtime; init/sync restamp the pin.

Env vars

Var	Default	Notes
PARSE_API_KEY	–	Auth for real requests (or use parse login). Preferred over --api-key in automation.
PARSE_ACCESS_TOKEN	–	OAuth bearer token override (normally managed by interactive parse login).

Changelog

Release history is on the PyPI project page: https://pypi.org/project/parse-sdk/#history.

Security

To report a security issue, email security@parse.bot — please do not open a public issue.

License

MIT © 2026 Parse. The license covers the parse-sdk runtime, codegen, and CLI; use of the Parse API/service is governed separately by Parse's terms.