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

# API DOCS DRIFT

# Trace API Docs — Reconciliation Report

Generated 2026-05-29. Backend code is canonical. This report reconciles the Mintlify API
reference pages (`trace-docs-mintlify/api/*.mdx`) against the FastAPI backend in
`/Users/elcruzo/Desktop/Trace/backend`. It is an internal report (gitignored; never
deployed).

## Backend topology (ground truth)

* `app/main.py` mounts `app/api/router.py` at `/api`, which includes the `v1`, `v2`, `v3`,
  `v4` routers (prefixes `/v1`..`/v4`).
* Most resource routers (auth, endpoints, payments, downloads, plans, playground, teams,
  conversations, notifications, user, ...) are included under **multiple** version prefixes
  with no extra prefix, so the same path exists under each.
* **Components** (`app/api/v3/components.py`) is **v3-only**.
* **Chat/streaming** routes live under v1–v4 (v2/v3/v4 override v1 to inject `api_version`
  and an additive tool set).
* **v1-only routers:** `signals`, `export` (not mounted under v2/v3/v4).
* The public API reference now standardizes on **`/api/v3`** as the canonical prefix.
* Base URL: `https://api.buildwithtrace.com`.

***

## Per-page changes

### api/overview\.mdx (API Reference)

* Removed fabricated `X-RateLimit-Limit/Remaining/Reset` headers — backend only sends
  `Retry-After` on 429 (plus security headers + `X-Process-Time`).
* Corrected base prefix from hard-coded `/api/v2/` to the real v1–v4 matrix; recommended
  `/api/v3` (Components are v3-only).
* Corrected error envelope: backend never returns `status_code` in the body. Real shapes:
  FastAPI `{"detail": ...}` (422 = array) and `{"success": false, "error": ...}`
  (manufacturer/preferences/tools).
* Rewrote the plan-tier table: only `free` is restricted (ask mode only); all other plans get
  all chat modes. The old "Free = read-only API access" claim was unsubstantiated; gating is
  per-route.
* Noted v1-only `signals`/`export` routers.

### api/endpoints.mdx (this index)

* Fully rewritten as a grouped master index of every endpoint (method/path/auth/summary)
  with per-domain reachable-prefix notes and `<Card>` links to all detail pages.
* Removed stale rows that no longer exist (see consolidated list below): `GET /auth/me`,
  `GET /auth/google`, `GET /auth/github`, `GET /downloads/check-update`, and the entire
  fabricated `/payments/*` checkout block, plus standalone `Beta`/`Feedback`/`Projects`
  sections that have no detail page in this set (their endpoints belong to v1
  beta/feedback/projects routers not reconciled in this batch — intentionally not invented
  here).
* Added Components (16), Chat telemetry/task-stream, conversation share, user
  preferences/linked-accounts/public/payments-plans, teams invite-info/leave/access/checkout/
  auto-join, notifications delete, downloads stats, playground.

### api/authentication.mdx

* All 17 auth endpoints documented; also reachable under v1/v2/v3/v4.
* Removed fabricated: `magic_link` flag on `/auth/login`; `GET /auth/google` &
  `GET /auth/github` with `?redirect_uri`; `provider` field on `/auth/exchange-code`;
  `token` body field on reset-password; logout via Authorization header; `token_type:bearer`
  in login response.
* Corrected OAuth paths to `/auth/google/login` and `/auth/github/login` (query is `callback`,
  not `redirect_uri`; no public callback endpoint).
* Added `/auth/user`, `/auth/check-admin`, `/auth/magic-link`, `/auth/verify-otp`,
  `/auth/change-password`, `/auth/reauthenticate`, `/auth/change-email`.
* Clarified the `user` object in token responses is the raw Supabase user (snake\_case
  `user_metadata`, `created_at`, ...), not a flattened plan/full\_name object.

### api/components.mdx (new)

* New page; all 16 endpoints are additions, all under `/api/v3/components` only.
* Flagged: router import is wrapped in try/except, so it silently does not mount if generator
  tools fail to import; generate endpoints need `tools.symbol_generator` /
  `tools.footprint_generator` at runtime, else `503`.
* Quirk: `rate_component` hardcodes `component_type` as `symbol` on new rating rows
  regardless of actual type.

### api/user.mdx

* Replaced fabricated minimal profile shape and the JSON-`full_name` PUT claim; the real
  `PUT /user/profile` is multipart-only (\~15 form fields + avatar/remove\_avatar).
* Rewrote quota as cost-based (USD) with a code enum (old doc said message/token based).
* Added: `/user/preferences`, `/user/linked-accounts` (GET+DELETE), `/user/account`,
  `/user/public/{username}`, `/payments/plans`.
* Flagged fail-soft convention (HTTP 200 with `success:false`) on most user endpoints.

### api/conversations.mdx

* Added `POST /conversations/{id}/share` and the `include_archived` query param; added
  `session_id` and `shared_with_team` to the list response example.
* Flagged that "create"/"delete" conversation endpoints do **not** exist (create happens via
  chat flow; delete = soft archive).

### api/chat.mdx

* Corrected base path to v1–v4 (examples now v4, the current prefix).
* Replaced fabricated SSE event names with the real `EventType` enum (`text_delta`,
  `thinking`, `tool_call`, `tool_result`, `file_edit`, `progress`, `status`, `title_update`,
  `mode_transition`, `phase_update`, `plan_document`, `interrupt`, `metrics`,
  `symbol_preview`, `footprint_preview`, `bom_preview`, `quota_warning`, `context_status`,
  `heartbeat`, `done`, `error`).
* Corrected `app_type` values from `schematic`/`pcb` to `eeschema`/`pcbnew`.
* Added required `session_id` and optional `is_error` to `/tools/result`.
* Added `/bad-file` and `/task/{task_id}/stream`.

### api/teams.mdx

* Fixed invite body: `role` is optional (default `member`); added optional `access_level`
  (default `full`).
* Added missing fields to `UpdateTeam` (`logo_url`, `invite_policy`) and to get-team/usage
  responses (`invite_policy`, `access_level`, raw `usage` array).
* Added: `/teams/invite-info`, `DELETE /teams/{id}/invites/{invite_id}`, `/teams/{id}/leave`,
  `/teams/{id}/members/{user_id}/access`, `/teams/{id}/checkout`, `/teams/internal/auto-join`.

### api/notifications.mdx

* Corrected base prefix to v1/v2/v3.
* Fixed `investor_updates` default (backend defaults `true`, not `false`).
* Added `limit`/`offset` params + `total` to the list endpoint; added
  `DELETE /notifications/{id}`, the `link` field, PUT empty-body `400`, and WebSocket legacy
  `?token=` auth + close codes (4001/1011).

### api/downloads.mdx

* Removed nonexistent `GET /downloads/check-update`.
* Added `GET /downloads/stats` (admin).
* Removed `filename` from the `/public` response example (not returned); added the `version`
  query param to `/public`.
* Noted v1/v2/v3 reachability (no v4).

### api/playground.mdx

* Replaced wrong content (it had documented direct proxied targets as "the playground"). The
  real playground router exposes only `GET /playground/endpoints` and
  `POST /playground/execute`, both public, reachable under v1–v4.
* Flagged whitelist quirk: submitted `endpoint` must start with `/api/v3/`.

### api/schematic.mdx / api/pcb.mdx / api/manufacturer.mdx

* Schematic: real fields `project_file_path`/`schematic_content`; versions list is `POST`
  (not `GET`); restore is path-param only, no body.
* PCB: params nested; SES result in `done.ses_content`.
* Manufacturer: 18 endpoints documented; `submit` is multipart; `/pay` is Pikkolo-only.

***

## (a) Endpoints found in code but newly documented

Authentication: `/auth/user`, `/auth/check-admin`, `/auth/magic-link`, `/auth/verify-otp`,
`/auth/change-password`, `/auth/reauthenticate`, `/auth/change-email`.

Components (all 16, v3-only): `/components/generate/symbol`, `/generate/footprint`,
`/generated` (POST), `/my`, `/generated/{id}` (PATCH, DELETE), `/generated/{id}/rate`,
`/generated/{id}/rating`, `/comments/{component_id}` (GET), `/comments` (POST),
`/comments/{comment_id}` (DELETE), `/community`, `/search`, `/submit`, `/submissions`,
`/submissions/{id}/review`.

Conversations: `POST /conversations/{id}/share`.

Chat & AI: `POST /bad-file`, `GET /task/{task_id}/stream`.

User: `PUT /user/preferences`, `GET /user/linked-accounts`,
`DELETE /user/linked-accounts/{provider}`, `DELETE /user/account`,
`GET /user/public/{username}`, `GET /payments/plans`.

Teams: `GET /teams/invite-info`, `DELETE /teams/{id}/invites/{invite_id}`,
`POST /teams/{id}/leave`, `POST /teams/{id}/members/{user_id}/access`,
`POST /teams/{id}/checkout`, `POST /teams/internal/auto-join`.

Notifications: `DELETE /notifications/{id}`.

Downloads: `GET /downloads/stats` (admin).

Manufacturer: full set including `/autofill`, `/enrich-bom`, `/orders/{id}/file`,
`/orders/{id}/initiate-payment`, `/orders/{id}/resume-payment`, `/orders/{id}/pay`,
`/shipping-options`, `/payment-options`, `/pcbway/{countries,states,cities}`.

## (b) Documented in old pages but NOT in code (removed/flagged)

* `GET /auth/me` — replaced by `GET /auth/user`.
* `GET /auth/google` and `GET /auth/github` with `?redirect_uri` — real paths are
  `/auth/google/login` and `/auth/github/login` with `?callback`.
* `magic_link` flag on `/auth/login`; `provider` field on `/auth/exchange-code`; `token`
  body on `/auth/reset-password`; `token_type:bearer` in login response — none exist.
* `GET /downloads/check-update` — no such route.
* Entire `/payments/*` checkout block from the old endpoints index
  (`/payments/checkout`, `/billing-portal`, `/subscription`, `/cancel`, `/reactivate`,
  `/webhook`) — not reconciled/verified in this batch and not present on a detail page; the
  only payments path confirmed is the public `GET /payments/plans`. Removed from the index
  rather than asserted. **See open question 4.**
* `filename` field on `GET /downloads/public` response — not returned.
* Conversation `create`/`delete` endpoints — do not exist (create via chat flow; delete =
  archive).
* Playground "endpoints" that were actually proxied targets (`/auth/verify`,
  `/user/profile`, etc.) — those are not playground routes.

## (c) Version-prefix mismatches

* Old pages and the overview hard-coded `/api/v2/`. Reality:
  * Auth, Chat/Tools, Teams, Conversations, Playground: **v1, v2, v3, v4**.
  * User, Notifications, Downloads, Schematic\*, PCB\*, Manufacturer\*: **v1, v2, v3**
    (downloads has no v4). *(Schematic/PCB/Manufacturer live in `endpoints.py` which is
    included under v1–v4.)*
  * Components: **v3 only**.
  * `signals`, `export`: **v1 only**.
* Canonical/recommended prefix is now **`/api/v3`** (overview/index), except chat examples
  use **v4** (current). Detail pages historically used v2 examples; some were kept at v2 for
  sibling consistency with an Info note — flagged as a future cleanup if a single prefix is
  desired site-wide.

## (d) Open questions / uncertainties to confirm

1. **Access-token lifetime.** Docs say \~1h based on the `expires_in=3600` fallback; actual
   lifetime is governed by Supabase project config and may differ. Confirm the real value.
2. **`payments/plans` contents.** `ONE_TIME_PLANS` may be non-empty depending on config; the
   JSON example is illustrative. Treat the live response as canonical.
3. **`GET /downloads/versions` schema.** Returns raw DB rows (no Pydantic model); documented
   columns (`id`, `storage_path`, `version`, `file_size`, `is_latest`, `channel`, `platform`)
   are inferred from usage, not enforced.
4. **Payments router.** A `payments` router exists (`app/api/v1/payments.py`) but its
   checkout/subscription/webhook endpoints were not reconciled in this batch and have no
   detail page. Should we add an `api/payments.mdx` and document them? They were removed from
   the index to avoid asserting unverified shapes.
5. **Beta / Feedback / Projects routers.** These exist in the backend (`beta.py`,
   `feedback.py`, `projects.py`) and appeared in the old index, but have no detail page in
   this reconciliation set. Confirm whether they should be documented (and on which page).
6. **Per-plan mode matrix.** Which plans allow `agent`/`plan` modes is computed server-side
   (`check_mode_access`); only `free` is known-restricted. Confirm the full matrix if it
   should be enumerated.
7. **Notifications `GET /preferences` extra columns.** Returns the raw Supabase row
   (`select=*`), so it may include `id`/`created_at`/`updated_at` beyond the four documented
   flags. Confirm the intended public shape.
8. **`api/components.mdx` link target.** The overview/index link to `/api/components` assumes
   that new page exists (it was created in this batch). Verify it builds and is wired
   correctly while remaining hidden from `docs.json`.