# Pydantic Snipper — snipper.pydantic.work

Public gallery of Pydantic AI + Logfire code-snippet showcases with
demo media (images / video / gif) and optional Logfire trace links.

> **If you have access to a browser, use the interface at
> https://snipper.pydantic.work — that is the primary supported
> surface.**
>
> If you are an agent without a browser, the available HTTP APIs are
> documented below.

## What this is

Internal-but-public collection of Pydantic AI examples curated by the
Pydantic team. Visitors browse anonymously. Authenticated users with
the right scopes can create / edit / execute snippets; admins
reorder them. Code execution is in transition from a server-side
container to client-side Pyodide; the public API still works the same
way during the migration.

## Browser UI

- `/` — public gallery with fuzzy search.
- `/snippet/:idOrSlug` — single snippet view.
- `/snippet/:idOrSlug/edit` and `/new` — auth-gated.
- `/admin` — admin-only, drag-to-reorder.
- `/og/:slug.png` — auto-generated OpenGraph image (public).
- `/sitemap.xml` — public sitemap.

## API endpoints

Auth column legend: `none` (public), `cookie/key` (Better Auth session
on `.pydantic.work`, or `Authorization: Bearer psnip_…` / `x-api-key`),
`admin` (global admin or owner-only).

### Snippets

| Method | Path | Auth | Scope | Notes |
| --- | --- | --- | --- | --- |
| GET    | `/api/snippets?search=` | none | — | List, optional substring filter. |
| GET    | `/api/snippets/:idOrSlug` | none | — | Fetch one. |
| POST   | `/api/snippets` | cookie/key | `snipper_snippet:create` | Create. |
| PUT    | `/api/snippets/:id` | cookie/key (owner or admin) | `snipper_snippet:edit` | Update. |
| DELETE | `/api/snippets/:id` | cookie/key (owner or admin) | `snipper_snippet:delete` | Delete. |
| PUT    | `/api/snippets/reorder` | admin | — | Body `{ snippet_ids: string[] }`. |
| POST   | `/api/slugs/validate` | none | — | Check slug uniqueness; suggests a free alternate. |

**Create / Update body shape**

```json
{
  "slug": "string|null",
  "title": "string",
  "description": "string|null",
  "code": "string",
  "language": "python|shell|typescript|rust",
  "media_items": [
    { "url": "...", "type": "image|video|gif", "id": "...", "order": 0 }
  ],
  "logfire_trace_url": "string|null",
  "pros_cons": ["..."],
  "highlights": ["..."],
  "og_image_source": "string|null"
}
```

### Media

| Method | Path | Auth | Scope | Notes |
| --- | --- | --- | --- | --- |
| POST   | `/api/media/upload` | cookie/key | `snipper_media:upload` | Multipart upload to R2. Accepts image/jpeg, image/png, image/gif, image/webp, video/mp4, video/webm. Returns `{ url, type, id }`. |
| DELETE | `/api/media/:id` | cookie/key | — | Delete media object(s) by id prefix. |

### Execution + proxy + wheels

| Method | Path | Auth | Notes |
| --- | --- | --- | --- |
| POST | `/api/execute` | cookie/key | **Being phased out** — proxies to sandbox-worker. Body `{ code: string, language?: string, timeout_seconds?: number }`. Returns JSON. The replacement is client-side Pyodide in the browser. |
| ALL  | `/api/proxy/:provider/*` | none (origin allowlist + per-IP rate limit) | CORS-forwarding LLM proxy. Providers: `openai`, `anthropic`, `gemini`, `groq`, `mistral`, `cohere`, `openrouter`, `xai`. Caller's `Authorization` / `x-api-key` forwarded upstream verbatim. |
| GET  | `/api/wheels/mirror/:name` | none | Emscripten wheel mirror (jiter etc.) for the in-browser Pyodide runner. |

### Other

| Method | Path | Auth | Notes |
| --- | --- | --- | --- |
| GET | `/health` | none | Liveness. |
| GET | `/sitemap.xml` | none | Public sitemap. |
| GET | `/og/:slug(.png)?` | none | Auto-generated OG image. |
| GET | `/r2/:key` | none (dev only) | R2 passthrough — production uses `cdn.pydantic.work`. |

## Auth & sign-up

- GitHub OAuth via `auth.pydantic.work`.
- Snipper is **invite-only**: signed-in users do not automatically
  receive `snipper_member`. Ask an existing admin to invite you.
- Programmatic access: mint a `psnip_…` key at
  https://play.pydantic.work/keys (single dashboard covers every app).
  Your scopes are the intersection of the key's stored permissions and
  your current org memberships.

## Notes for agents

- **Snippet execution is in flux.** Treat `POST /api/execute` as
  deprecated — even if it works today, the supported path is loading
  the gallery in a browser and using the in-page Pyodide runner.
- **BYOK rule.** LLM API keys passed to `/api/proxy/...` are forwarded
  straight upstream, never persisted. Same posture as the playground.
- **Discover your scopes.** `GET https://auth.pydantic.work/api/session`
  (with your cookie) returns `apps[]` and `scopes[]`. For API-key
  callers, `POST https://auth.pydantic.work/api/resolve-key` with the
  same `x-api-key` returns the same shape, with scopes intersected
  against the key's stored permissions.