# API Routes Specification Index

This folder is the source of truth for planned API endpoints for the Flutter app.

## Scope
- Focus only on API contract design.
- No implementation details.
- One markdown file per route.
- Route files are written in plain human language + exact contract fields.

## Conventions
- Base path placeholder: `/api/v1`
- JSON request/response unless noted.
- Times in ISO-8601 UTC.
- IDs are strings unless explicitly numeric.

## Route Files
- `routes/_ROUTE_TEMPLATE.md` (copy for each new route)
- `API_CONVENTIONS.md` (path and contract rules)
- `ERROR_CODES.md` (canonical machine-readable error codes)
- `openapi-strict.yaml` (strict per-endpoint request/response schema)

## How We Will Work Screen-by-Screen
1. You send a screen (image + user action intent).
2. I derive required routes.
3. I create/update route files in `routes/`.
4. I keep this index updated.

## Planned Route List
- `GET /api/v1/auth/login-config`
- `POST /api/v1/auth/otp/request`
- `POST /api/v1/auth/otp/verify`
- `POST /api/v1/auth/firebase/token`
- `POST /api/v1/auth/anonymous/session`
- `POST /api/v1/auth/session/refresh`
- `POST /api/v1/auth/logout`
- `GET /api/v1/users/me/onboarding/status`
- `PUT /api/v1/users/me/onboarding/profile-basics`
- `PUT /api/v1/users/me/onboarding/contacts`
- `POST /api/v1/uploads/presign`
- `POST /api/v1/uploads/complete`
- `GET /api/v1/uploads/{assetId}/download-url`
- `PUT /api/v1/users/me/onboarding/media`
- `GET /api/v1/users/by-username/{username}`
- `POST /api/v1/users/handles/availability`
- `GET /api/v1/users/me/profile`
- `PATCH /api/v1/users/me/profile`
- `GET /api/v1/users/me/hub-profile`
- `PATCH /api/v1/users/me/hub-profile`
- `GET /api/v1/users/me/hubs`
- `GET /api/v1/users/{userId}/followers`
- `GET /api/v1/users/{userId}/following`
- `POST /api/v1/users/{userId}/follow`
- `DELETE /api/v1/users/{userId}/follow`
- `POST /api/v1/users/{userId}/block`
- `DELETE /api/v1/users/{userId}/block`
- `POST /api/v1/reports/users/{userId}`
- `GET /api/v1/users/{userId}/feed`
- `GET /api/v1/posts`
- `POST /api/v1/posts`
- `GET /api/v1/posts/{postId}`
- `DELETE /api/v1/posts/{postId}`
- `GET /api/v1/users/me/saved-discussions`
- `GET /api/v1/posts/{postId}/comments`
- `POST /api/v1/posts/{postId}/comments`
- `DELETE /api/v1/comments/{commentId}`
- `GET /api/v1/posts/{postId}/frames`
- `POST /api/v1/posts/{postId}/vote`
- `GET /api/v1/posts/{postId}/vote/me`
- `GET /api/v1/posts/{postId}/vote/summary`
- `GET /api/v1/posts/{postId}/vote/distribution`
- `GET /api/v1/posts/{postId}/vote/hubs`
- `POST /api/v1/posts/{postId}/reposts`
- `POST /api/v1/posts/{postId}/share/feed`
- `POST /api/v1/posts/{postId}/share/hubs`
- `GET /api/v1/posts/{postId}/share-link`
- `POST /api/v1/reports/posts/{postId}`
- `POST /api/v1/hubs`
- `GET /api/v1/hubs/{hubId}`
- `PATCH /api/v1/hubs/{hubId}`
- `DELETE /api/v1/hubs/{hubId}/membership`
- `POST /api/v1/hubs/{hubId}/invitations`
- `GET /api/v1/hubs/{hubId}/invitations`
- `POST /api/v1/hub-invitations/{invitationId}/accept`
- `POST /api/v1/hub-invitations/{invitationId}/decline`
- `GET /api/v1/hubs/{hubId}/members`
- `POST /api/v1/hubs/{hubId}/members/{userId}/remove`
- `GET /api/v1/hubs/{hubId}/admins`
- `POST /api/v1/hubs/{hubId}/admins`
- `DELETE /api/v1/hubs/{hubId}/admins/{userId}`
- `PATCH /api/v1/hubs/{hubId}/link`
- `POST /api/v1/hubs/{hubId}/invite-links`
- `GET /api/v1/hub-invite-links/{token}`
- `POST /api/v1/hub-invite-links/{token}/join-requests`
- `GET /api/v1/hubs/{hubId}/join-requests`
- `POST /api/v1/hubs/{hubId}/join-requests/{requestId}/approve`
- `POST /api/v1/hubs/{hubId}/join-requests/{requestId}/reject`
- `GET /api/v1/hubs/{hubId}/notification-settings`
- `PATCH /api/v1/hubs/{hubId}/notification-settings`
- `GET /api/v1/hubs/{hubId}/feed`
- `GET /api/v1/hubs/{hubId}/discussions`
- `POST /api/v1/hubs/{hubId}/discussions/{discussionId}/save`
- `DELETE /api/v1/hubs/{hubId}/discussions/{discussionId}/save`
- `GET /api/v1/hubs/{hubId}/discussions/{discussionId}/messages`
- `POST /api/v1/hubs/{hubId}/discussions/{discussionId}/messages`
- `POST /api/v1/reports/hubs/{hubId}`
- `GET /api/v1/search/hubs`
- `GET /api/v1/search/users`
- `GET /api/v1/notifications`
- `PATCH /api/v1/notifications/read`
- `GET /api/v1/notifications/stream`

## Route Document Catalog

Every current API operation has one route document:

- [`auth-anonymous-session`](routes/auth-anonymous-session.md)
- [`auth-firebase-token`](routes/auth-firebase-token.md)
- [`auth-login-config`](routes/auth-login-config.md)
- [`auth-logout`](routes/auth-logout.md)
- [`auth-otp-request`](routes/auth-otp-request.md)
- [`auth-otp-verify`](routes/auth-otp-verify.md)
- [`auth-session-refresh`](routes/auth-session-refresh.md)
- [`comments-delete`](routes/comments-delete.md)
- [`hub-invitations-accept`](routes/hub-invitations-accept.md)
- [`hub-invitations-decline`](routes/hub-invitations-decline.md)
- [`hub-invite-links-get`](routes/hub-invite-links-get.md)
- [`hub-invite-links-join-requests-create`](routes/hub-invite-links-join-requests-create.md)
- [`hubs-admins-add`](routes/hubs-admins-add.md)
- [`hubs-admins-delete`](routes/hubs-admins-delete.md)
- [`hubs-admins-list`](routes/hubs-admins-list.md)
- [`hubs-create`](routes/hubs-create.md)
- [`hubs-discussion-messages-create`](routes/hubs-discussion-messages-create.md)
- [`hubs-discussion-messages-list`](routes/hubs-discussion-messages-list.md)
- [`hubs-discussion-save-create`](routes/hubs-discussion-save-create.md)
- [`hubs-discussion-save-delete`](routes/hubs-discussion-save-delete.md)
- [`hubs-discussions-list`](routes/hubs-discussions-list.md)
- [`hubs-feed-list`](routes/hubs-feed-list.md)
- [`hubs-get`](routes/hubs-get.md)
- [`hubs-invitations-create`](routes/hubs-invitations-create.md)
- [`hubs-invitations-list`](routes/hubs-invitations-list.md)
- [`hubs-invite-links-create`](routes/hubs-invite-links-create.md)
- [`hubs-join-requests-approve`](routes/hubs-join-requests-approve.md)
- [`hubs-join-requests-list`](routes/hubs-join-requests-list.md)
- [`hubs-join-requests-reject`](routes/hubs-join-requests-reject.md)
- [`hubs-leave`](routes/hubs-leave.md)
- [`hubs-link-patch`](routes/hubs-link-patch.md)
- [`hubs-members-list`](routes/hubs-members-list.md)
- [`hubs-members-remove`](routes/hubs-members-remove.md)
- [`hubs-notification-settings-get`](routes/hubs-notification-settings-get.md)
- [`hubs-notification-settings-patch`](routes/hubs-notification-settings-patch.md)
- [`hubs-patch`](routes/hubs-patch.md)
- [`notifications-list`](routes/notifications-list.md)
- [`notifications-read-patch`](routes/notifications-read-patch.md)
- [`notifications-stream`](routes/notifications-stream.md)
- [`posts-comments-create`](routes/posts-comments-create.md)
- [`posts-comments-list`](routes/posts-comments-list.md)
- [`posts-create`](routes/posts-create.md)
- [`posts-delete`](routes/posts-delete.md)
- [`posts-feed-list`](routes/posts-feed-list.md)
- [`posts-frames-list`](routes/posts-frames-list.md)
- [`posts-get`](routes/posts-get.md)
- [`posts-repost-create`](routes/posts-repost-create.md)
- [`posts-share-feed-create`](routes/posts-share-feed-create.md)
- [`posts-share-hubs-create`](routes/posts-share-hubs-create.md)
- [`posts-share-link-get`](routes/posts-share-link-get.md)
- [`posts-vote-create`](routes/posts-vote-create.md)
- [`posts-vote-distribution-get`](routes/posts-vote-distribution-get.md)
- [`posts-vote-hubs-get`](routes/posts-vote-hubs-get.md)
- [`posts-vote-me-get`](routes/posts-vote-me-get.md)
- [`posts-vote-summary-get`](routes/posts-vote-summary-get.md)
- [`reports-hub-create`](routes/reports-hub-create.md)
- [`reports-post-create`](routes/reports-post-create.md)
- [`reports-user-create`](routes/reports-user-create.md)
- [`search-hubs`](routes/search-hubs.md)
- [`search-users`](routes/search-users.md)
- [`uploads-complete`](routes/uploads-complete.md)
- [`uploads-download-url-get`](routes/uploads-download-url-get.md)
- [`uploads-presign`](routes/uploads-presign.md)
- [`users-block-create`](routes/users-block-create.md)
- [`users-block-delete`](routes/users-block-delete.md)
- [`users-feed-list`](routes/users-feed-list.md)
- [`users-follow-create`](routes/users-follow-create.md)
- [`users-follow-delete`](routes/users-follow-delete.md)
- [`users-followers-list`](routes/users-followers-list.md)
- [`users-following-list`](routes/users-following-list.md)
- [`users-handle-availability`](routes/users-handle-availability.md)
- [`users-me-hub-profile-get`](routes/users-me-hub-profile-get.md)
- [`users-me-hub-profile-patch`](routes/users-me-hub-profile-patch.md)
- [`users-me-hubs-list`](routes/users-me-hubs-list.md)
- [`users-me-onboarding-contacts`](routes/users-me-onboarding-contacts.md)
- [`users-me-onboarding-media`](routes/users-me-onboarding-media.md)
- [`users-me-onboarding-profile-basics`](routes/users-me-onboarding-profile-basics.md)
- [`users-me-onboarding-status`](routes/users-me-onboarding-status.md)
- [`users-me-profile-get`](routes/users-me-profile-get.md)
- [`users-me-saved-discussions-list`](routes/users-me-saved-discussions-list.md)
- [`users-profile-get`](routes/users-profile-get.md)
- [`users-profile-patch-me`](routes/users-profile-patch-me.md)