# Backend API

> Quick Access

> - App: http://127.0.0.1:8000/
> - Sign In: http://127.0.0.1:8000/sign_in.html
> - Wiki: http://127.0.0.1:8000/wiki/

The Flask app (`server.py`) provides:

- Authentication endpoints (`/api/login`, `/api/logout`).
- Static file serving and the protected `/wiki/` docs.
- API endpoints to be added for asset CRUD, search, and integration with workers and storage.

In production run behind Gunicorn and use environment variables for secrets and DB connection strings.

New: Asset creation and upload endpoints - `POST /api/assets` — create an asset using JSON payload; requires authentication (session). Example body:

    {
        "title": "Project Image",
        "filename": "image.jpg",
        "mime_type": "image/jpeg",
        "size": 12345,
        "url": "https://...",
        "metadata": "{...}"
    }

- `POST /api/assets/upload` — multipart/form-data file upload (field name `file`). The server stores uploaded files in the `uploads/` folder and records a local `url` in the `assets` table. Requires authentication. Example (curl):

    curl -F "file=@./image.jpg" -F "title=My Upload" -b cookies.txt -c cookies.txt http://127.0.0.1:8000/api/assets/upload

Tests: `tests/test_assets.py` contains basic tests for JSON creation and file uploads (run with `pytest`, assumes the dev server is running at `http://127.0.0.1:8000`).

List / Search endpoint - `GET /api/assets` — list assets. Supports query parameters: - `q` — search text (matches title, filename, or metadata using SQL LIKE) - `page` — 1-based page number (defaults to 1) - `limit` — items per page (defaults to 20) - `sort` — one of `created_at`, `title`, `size` (defaults to `created_at`)

Example:

    curl 'http://127.0.0.1:8000/api/assets?q=project&page=1&limit=12' -b cookies.txt -c cookies.txt

The response includes pagination metadata `{assets: [...], page: 1, limit: 12, total: 123}`.

Storage OAuth Integration - Environment variables: `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, `ONEDRIVE_CLIENT_ID`, `ONEDRIVE_CLIENT_SECRET`. Optionally set `OAUTH_REDIRECT_URI` (defaults to `http://127.0.0.1:8000/api/auth/drive/callback`). - Endpoints added: - `GET /api/auth/drive/start?provider=google|onedrive` — returns an OAuth authorization URL for redirecting the user to the provider. - `GET|POST /api/auth/drive/callback?provider=google|onedrive` — receives the provider callback `code` and exchanges it for tokens (placeholder exchange — tokens are not persisted by default). - Implementation notes: connectors are in `storage/connectors.py` and currently provide URL generation and simulated token exchange. In production implement secure token storage and server-side token exchange using the provider token endpoints.

Upload hardening - Environment variables: `UPLOAD_MAX_BYTES` (bytes, default 52428800 = 50MB), `UPLOAD_ALLOWED_MIMETYPES` (comma-separated list of allowed MIME types). - The server enforces mime type checks and a hard file size limit for uploads. If a file exceeds `UPLOAD_MAX_BYTES` the server returns `413 Payload Too Large`. If the mime type is not allowed it returns `415 Unsupported Media Type`. - For production consider scanning uploads, virus scanning, and moving files to secure object storage (S3/GCS) and not serving uploads directly from the app server.

## Health endpoint

- `GET /api/health` — returns basic application status and checks DB connectivity. Response:

    { "success": true, "status": "ok" }

- If a problem occurs, the endpoint returns HTTP 500 with:

    { "success": false, "status": "error", "message": "..." }

Usage (curl):

    curl http://127.0.0.1:8000/api/health

Notes: - MkDocs home uses this endpoint to show a banner indicating whether the app is running. - Consider extending to include build/version info and additional checks (storage, disk space) for production.

« Previous Next »