Python SDK

parse-sdk is the runtime and the parse CLI. It generates a project-local, fully typed parse_apis package — the client for every API your key can call, with autocompleting resources, methods, enums, and typed responses. Clients are generated from the same spec that powers the REST and MCP surfaces.

Install

The SDK is managed with uv. Inside a uv project (run uv init first if you don’t have a pyproject.toml):

uv add parse-sdk      # runtime + `parse` CLI, into your project's .venv
uv run parse init     # one-time: authenticate, scaffold parse_apis, first sync

uv add installs the parse console script into the project’s .venv, which isn’t on your PATH. Invoke it as uv run parse <command>, or source .venv/bin/activate once and call parse directly. Examples below use the uv run form.

parse init is the one-time setup: it scaffolds the committed parse_apis package, records it as an editable path dependency ([tool.uv.sources]), appends a deny-by-default .gitignore block, ensures credentials, and runs the first parse sync. Run it from your project root, where the pyproject.toml lives.

Authenticate

parse init prompts for an API key on first run. To authenticate explicitly:

uv run parse login                      # browser sign-in (OAuth 2.1 + PKCE) — the default
uv run parse login --no-web             # paste an API key (dashboard: Settings → API Keys)
uv run parse login --api-key YOUR_KEY   # non-interactive (CI, agents)

Credentials are saved to ~/.config/parse/credentials (the same path on every OS). The CLI and generated clients also read PARSE_API_KEY from the environment. uv run parse whoami shows the active key and base URL.

Add an API

A fresh project tracks all APIs your key can call. To curate an explicit set, add APIs by slug.

One of your own APIs

uv run parse list               # see your account APIs and their slugs
uv run parse add my_zillow_api  # track it, then sync

A marketplace API

Pull a ready-made API from the marketplace by slug, listing id, or URL:

uv run parse search walmart                     # find it
uv run parse add --marketplace walmart-com-api  # add a pinned snapshot

parse add --marketplace downloads a pinned snapshot of a shared canonical API — it won’t change underneath you. Pass --version N to pin a specific release (the default is the latest at add time). To edit the API, subscribe and swap to your own copy in the dashboard.

Use it

Once you’ve added an API (here, the Walmart marketplace API above):

from parse_apis.walmart_com_api import Walmart, Sort, ProductNotFound
from parse_apis import RateLimitError   # runtime errors, re-exported

client = Walmart()                      # picks up your `parse login` credentials

# Typed resources + methods, with autocomplete and typed responses
for product in client.productsummaries.search(query="laptop", sort=Sort.PRICE_LOW, limit=5):
    print(product.name, product.price, product.rating)

# Typed errors
try:
    client.products.get(product_id="0000000000")
except ProductNotFound as exc:
    print(f"not found: {exc.product_id}")
except RateLimitError:
    ...

Run it in the project environment:

uv run python app.py

Resources and methods are generated from your API’s spec. The client class follows the API’s root type; the import module follows its slug. parse add prints the exact from parse_apis.… import … line, which also heads the generated README.md and example.py in each parse_apis/src/parse_apis/<slug>/ directory.

Project layout & manifest

parse init creates an installed, editable package — not a loose folder:

parse_apis/
  pyproject.toml               # committed: name="parse-apis", pins parse-sdk==X
  AGENTS.md  CLAUDE.md         # committed "start here" pointer (survives a fresh clone)
  src/parse_apis/
    __init__.py                # committed scaffold (re-exports runtime errors)
    py.typed                   # committed
    walmart_com_api/           # generated client + README.md + example.py (gitignored)
    _manifest.json             # generated (gitignored)
    AGENTS.md  CLAUDE.md       # generated cross-API index (gitignored)

Commit the scaffold files (those not marked generated); the generated payload is per-key (it reveals your API inventory) and stays gitignored. Because parse_apis is an installed editable package, import parse_apis resolves from any directory. The repo curates which APIs it syncs via a [tool.parse] table in your pyproject.toml. parse add and parse remove manage it for you — you rarely edit it by hand:

[tool.parse]
# Account APIs to track. Omit `apis` entirely to track ALL of them;
# an empty list means none.
apis = ["my_zillow_api"]

# Marketplace APIs downloaded into this repo, each pinned to a version.
[[tool.parse.marketplace]]
slug = "walmart-com-api"
version = 3

Reconcile the generated package with the manifest at any time:

uv run parse sync           # generate/refresh exactly what the manifest declares
uv run parse sync --check   # CI dry run: report drift without writing, exit 1 on any finding
uv run parse clean          # remove the generated payload, keep the committed scaffold

Commit the [tool.parse] table; the generated parse_apis/ payload is your choice. The manifest is the source of truth. Commit the payload too, or .gitignore it and run parse sync on checkout / in CI. After upgrading parse-sdk, re-run parse sync — generated code subclasses the runtime by version, and init/sync restamp the pin in parse_apis/pyproject.toml. (Release history.)

Agents & scripting

Most commands take --json for stable, machine-readable output — agents should prefer it. (init, login, and clean have no --json.) Errors still go to stderr; stdout stays parseable.

uv run parse list --json    # [{ "id", "slug", "name", "modeled", "endpoints", "resources" }, …]
uv run parse sync --json    # { "written", "skipped", "removed", "quarantined", "failures" }
uv run parse doctor --json  # { "ok": true|false, "findings": [ … ] }

parse sync --check exits non-zero on drift, so it drops straight into CI. The generated AGENTS.md and CLAUDE.md files give a coding agent a cross-API index of every client, its resources, and example calls.

Setup prompt for coding agents

Paste this into Claude Code, Codex, or any coding agent to set up and use the SDK end to end:

Set up and use the Parse Python SDK in this project.

1. Ensure this is a uv project — if there is no pyproject.toml, run `uv init`.
2. Install the SDK: `uv add parse-sdk`.
3. Authenticate: if PARSE_API_KEY is not set, get a key from the Parse
   dashboard (parse.bot → Settings → API Keys) and run
   `uv run parse login --api-key <KEY>`.
4. Initialize: `uv run parse init` (now non-interactive — credentials exist).
5. List the APIs this key can call: `uv run parse list --json`.
6. Add the API(s) I need by slug: `uv run parse add <slug>` (or
   `uv run parse add --marketplace <id|slug|url>` for a marketplace API).
   This regenerates parse_apis.
7. Read `parse_apis/src/parse_apis/<slug>/README.md` for the exact import line, then write
   code that imports the typed client from `parse_apis.<module>` and calls its
   resources and methods. Catch typed errors re-exported from `parse_apis`.
8. Run it with `uv run python <file>.py`.

Always invoke the CLI as `uv run parse …`. Prefer `--json` output when parsing
results. If imports or editor autocomplete don't resolve, run
`uv run parse doctor --fix`.

Command reference

Run every command as uv run parse <command> (or bare parse in an activated venv).

Command	What it does
`parse init [--api-key K] [--base-url U]`	One-time setup: authenticate, scaffold `parse_apis`, record deps, first sync
`parse login [--web \| --no-web] [--api-key K] [--base-url U]`	Sign in via browser (default), or save an API key
`parse whoami [--json]`	Show the active key + base URL
`parse list [--long] [--json]`	List the APIs your key can call (no generation)
`parse search <query…> [--limit N] [--json]`	Search the marketplace
`parse add <slug…> [--json]`	Track account API(s) by slug, then sync
`parse add --marketplace <id\|slug\|url> [--version N] [--json]`	Add a pinned marketplace API
`parse remove <slug…> [--json]`	Stop tracking API(s), then reconcile
`parse sync [--check] [--clean] [--json]`	Reconcile the generated package with the manifest
`parse clean`	Remove the generated payload, keep the committed scaffold
`parse doctor [--fix] [--json]`	Diagnose (and optionally fix) install / auth / import issues
`parse help [--json]`	Command overview

parse doctor checks uv, the parse_apis scaffold, your pyproject deps and editable source, parse-sdk version skew, whether the project interpreter can import parse_sdk + parse_apis (the usual cause of dead autocomplete), and credentials. parse doctor --fix auto-remediates what it safely can.

Prefer no SDK? Every API is also a plain REST endpoint and an MCP server.

Getting Started

Features

Reference

Install

Authenticate

Add an API

One of your own APIs

A marketplace API

Use it

Project layout & manifest

Agents & scripting

Setup prompt for coding agents

Command reference

​Install

​Authenticate

​Add an API

​One of your own APIs

​A marketplace API

​Use it

​Project layout & manifest

​Agents & scripting

​Setup prompt for coding agents

​Command reference

Install

Authenticate

Add an API

One of your own APIs

A marketplace API

Use it

Project layout & manifest

Agents & scripting

Setup prompt for coding agents

Command reference