Skip to main content

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