API Route Map

Every route the Python backend serves today, what it becomes in the TypeScript app, and what an agent needs from it. Read from the code on 5 November 2026: sondely/backend/app/main.py and every backend/app/api/*/routes.py. The design side follows TourCockpit's framework as it stands at commit f952d0eea (src/lib/api/openapi.ts, src/lib/api/errors.ts, src/lib/api/auth.ts, src/lib/assistant/refusal-legibility.ts). Sign-in itself is on Sign-in, Sessions and API Keys; the tables behind the routes are on Data Model.

Count

95 route decorators. Two of the app-level ones are exclusive (the SPA catch-all when a built frontend is present, the JSON root when not), so 94 answer at once. FastAPI also serves /api/v1/openapi.json, /docs and /redoc, which are generated, not written.

How to read the tables

Each router has two tables keyed by a route number: access (who may call it today and in the new design) and contract (request, response, writes, dry run, idempotency, errors).

Who may call it today names the FastAPI dependency and the role check:

Three things hold for every signed-in route today and are not repeated per row: a missing or bad credential is 401 "Not authenticated"; an API key over 60 requests a minute is 429 "Rate limit exceeded" (backend/app/middleware/rate_limit.py, in memory, per replica); an API key acts as the user who created it, and the organization on the key is never checked.

Registry Rbac is the value the route gets in Sondely's copy of RouteDef.rbac. TourCockpit's type is "any" | "office" | "manager" | "owner" | "operator"; Sondely's becomes:

An API key carries one organization and one scope: read (GET only), draft (create and edit drafts, never publish, delete or send), full. The Rbac cell adds the lowest key scope that may call the route, or "no key" where only a person may. A key on another organization's resource gets 404 NOT_FOUND, never 403, as TourCockpit does for cross-tenant ids.

TS path is "same" unless a reason is given: the bearer contract is kept at cutover so the Vite frontend does not change (Sign-in, Sessions and API Keys). The Next route folder was planned as server/src/app/api/v1/<path>/route.ts with one dynamic segment name per level ([surveyId], [orgId]), so the sessions and assignments routes that share /surveys/{survey_id} and /organizations/{org_id} prefixes live in the same folders as the survey and organization routes. As built on 7 November 2026 in CatalyzeUp/sondely-platform, the routes are registered in one route registry and served through src/lib/api/dispatch.ts from route files under src/app/api/v1/; the new app serves its own screens with a session cookie, while the bearer contract stays for the Vite app until the cutover.

The plan's folder rule: with one dynamic segment name per level ([surveyId], [orgId]), so the sessions and assignments routes that share /surveys/{survey_id} and /organizations/{org_id} prefixes live in the same folders as the survey and organization routes.

Dry run: ?dryRun=true runs the whole write in its transaction and rolls back (TourCockpit src/lib/api/request-transaction.ts). "yes, delivery" means the route sends something that cannot be taken back (an email, a model call) and answers its own dry run with what it would send, as TourCockpit's src/lib/api/delivery.ts does. Sign-in routes do not take dry run.

Idempotency key: Idempotency-Key header (TourCockpit src/lib/api/idempotency.ts). "yes" means a retry without it would do the thing twice. "optional" means the write is naturally idempotent but accepts a key. "no, rate limit" means a send that a person triggers and that is throttled instead.

Errors: today's status and detail text as written in the handler, then the code it becomes. The new envelope is {error: {code, message, details}}; the codes and their classes are in Error codes for Sondely.

auth

File: backend/app/api/auth/routes.py.

geo, languages, users

Files: backend/app/api/geo/routes.py, backend/app/api/languages/routes.py, backend/app/api/users/routes.py.

surveys

File: backend/app/api/surveys/routes.py.

organizations

File: backend/app/api/organizations/routes.py.

sessions

File: backend/app/api/sessions/routes.py. None of these routes checks that the survey is published or that the caller belongs to its organization: any signed-in token starts a session on any survey id, drafts included.

dashboard, invitations

Files: backend/app/api/dashboard/routes.py, backend/app/api/invitations/routes.py.

assignments

File: backend/app/api/assignments/routes.py.

templates, impact

Files: backend/app/api/templates/routes.py, backend/app/api/impact/routes.py (mounted under /api/v1/surveys).

notifications

File: backend/app/api/notifications/routes.py.

api_keys

File: backend/app/api/api_keys/routes.py (mounted under /api/v1/organizations). Keys are managed only by a signed-in person, never by another key.

app level

File: backend/app/main.py.

M2 and M3 move under one test prefix so a single guard and a single test cover every test-only route. The contract suite runs against both backends, so the Python side gets the same /api/v1/test/* paths (see Testing and Bugs).

Error codes for Sondely

TourCockpit keeps one class per code in src/lib/assistant/refusal-legibility.ts, typed so a new code does not compile until it is classed: ask (the person fixes it by saying something), explain (a fact of the data, with an offer), denied (their access does not reach it), retry (the data moved; read again and prepare again). Sondely keeps the envelope, the typing and the four classes and replaces the 65 tour codes with these. Status mapping follows TourCockpit src/lib/api/errors.ts: 403 strictly means wrong role, and anything outside the caller's organization is 404.

Framework, copied from TourCockpit

Access and sign-in

Organizations and members

Surveys, questions and translations

INVALID reasons for the survey validator, all new (today a survey is published with no checks): NO_QUESTIONS, CHOICE_WITHOUT_OPTIONS, SCORING_TYPE_MISMATCH (scoring type does not fit the question type), OPTION_WEIGHTS_MISMATCH, GROUP_UNKNOWN (a question points to a group the survey does not have), DUPLICATE_ORDER, RECURRENCE_INTERVAL_MISSING, TRANSLATION_SHAPE (a translation that changes ids or option counts, the rule services/translation.py already enforces), QUESTION_NOT_IN_SURVEY (S20 today writes to any question id). Each is judged: body when the request alone shows it, judged: record when only the stored survey does, as in TourCockpit.

Responses, sessions and assignments

That is 15 framework codes (three of them for batch) plus 42 Sondely codes, and 9 INVALID reasons. INTERNAL (500) stays unclassed: it is a defect, logged with the trace id, never a refusal.

Frontend call sites that depend on response shapes

From frontend/src. Two clients exist side by side: axios (src/api/client.ts, src/utils/api.ts) and plain fetch with API_ENDPOINTS (src/config/api.ts). Both send Authorization: Bearer <access_token from localStorage>. The TypeScript backend must answer these shapes unchanged until each screen moves.

Client code that calls routes that do not exist: surveyApi.getSurveyQuestions in utils/api.ts (GET /surveys/{id}/questions) and API_ENDPOINTS.sessions.bySurvey (/sessions/survey/{id}). Neither has a caller outside its own file; both are deleted, not ported. On every 401 both clients clear localStorage and send the browser to /auth/signin, so the 30-minute token is felt as a sign-out mid-task.

Routes that return raw dicts

These have no response model, or a model that does not match what the handler returns. Each needs a Zod response schema in the registry, which is also what lets the contract test fail when a response drifts.

New routes the agent layer needs

From Sondely as an Agent, step 1, and the Agent Layer page. All go into the registry, so each becomes a write tool or a read for Faro's Sondely copy and for MCP.

The fake model mode (translation) and the fake geo lookup are environment switches read when ENVIRONMENT=test, not routes. A test route answers 404 in every other environment, and a unit test asserts that for each one, so a wrong environment variable in production cannot open them.