> ## Documentation Index
> Fetch the complete documentation index at: https://docs.parse.bot/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Typed Python clients for your Parse APIs, generated by the parse CLI

`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](https://docs.astral.sh/uv/). Inside a uv project (run `uv init` first if you don't have a `pyproject.toml`):

```bash theme={null}
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.

<Note>
  `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.
</Note>

## Authenticate

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

```bash theme={null}
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

```bash theme={null}
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](/marketplace) by slug, listing id, or URL:

```bash theme={null}
uv run parse search walmart                     # find it
uv run parse add --marketplace walmart-com-api  # add a pinned snapshot
```

<Warning>
  `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.
</Warning>

## Use it

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

```python theme={null}
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:

```bash theme={null}
uv run python app.py
```

<Note>
  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.
</Note>

## Project layout & manifest

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

```text theme={null}
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:

```toml theme={null}
[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:

```bash theme={null}
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
```

<Note>
  **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](https://pypi.org/project/parse-sdk/#history).)
</Note>

## 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.

```bash theme={null}
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:

```text theme={null}
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                                                             |

<Tip>
  `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.
</Tip>

<Note>
  Prefer no SDK? Every API is also a plain [REST endpoint](/quickstart) and an [MCP server](/mcp).
</Note>