Add JSON REST API for MCP integration

- Add /api/v1 namespace with Bearer token auth (PINCHFLAT_API_TOKEN env var)
- API controllers for sources, media items, media profiles, settings, tasks
- Support for all source actions: create, update, delete, force_download_pending,
  force_redownload, force_index, force_metadata_refresh, sync_files_on_disk
- Media item endpoints: list, show, search, force_download, update, delete
- Media profile CRUD endpoints
- Settings show/update and app_info endpoints
- Task listing endpoints
- Add Jason.Encoder for Task schema
- Comprehensive test suite for all API endpoints
- Gitea Actions CI workflow (runs existing checks + API-specific tests)
- API documentation in docs/API.md

lib/pinchflat_web/controllers/api/v1/api_media_item_controller.ex

@@ -0,0 +1,94 @@
+defmodule PinchflatWeb.Api.V1.ApiMediaItemController do
+  @moduledoc """
+  JSON API controller for MediaItems.
+  """
+
+  use PinchflatWeb, :controller
+
+  alias Pinchflat.Repo
+  alias Pinchflat.Media
+  alias Pinchflat.Media.MediaItem
+  alias Pinchflat.Downloading.MediaDownloadWorker
+
+  def index(conn, params) do
+    media_items =
+      case params do
+        %{"source_id" => source_id} ->
+          source = Pinchflat.Sources.get_source!(source_id)
+          Media.list_pending_media_items_for(source)
+
+        _ ->
+          Media.list_media_items()
+      end
+
+    media_items = Repo.preload(media_items, :source)
+    json(conn, %{data: media_items})
+  end
+
+  def show(conn, %{"id" => id}) do
+    media_item =
+      id
+      |> Media.get_media_item!()
+      |> Repo.preload([:source, tasks: [:job]])
+
+    json(conn, %{data: media_item})
+  end
+
+  def search(conn, %{"q" => query}) do
+    results = Media.search(query) |> Repo.preload(:source)
+    json(conn, %{data: results})
+  end
+
+  def search(conn, _params) do
+    json(conn, %{data: []})
+  end
+
+  def force_download(conn, %{"media_item_id" => id}) do
+    media_item = Media.get_media_item!(id)
+
+    case MediaDownloadWorker.kickoff_with_task(media_item, %{force: true}) do
+      {:ok, _} ->
+        json(conn, %{data: %{message: "Download task enqueued."}})
+
+      {:error, :duplicate_job} ->
+        json(conn, %{data: %{message: "Download task already enqueued."}})
+
+      {:error, reason} ->
+        conn
+        |> put_status(:internal_server_error)
+        |> json(%{errors: %{detail: "Failed to enqueue download: #{inspect(reason)}"}})
+    end
+  end
+
+  def update(conn, %{"id" => id, "media_item" => params}) do
+    media_item = Media.get_media_item!(id)
+
+    case Media.update_media_item(media_item, params) do
+      {:ok, media_item} ->
+        media_item = Repo.preload(media_item, :source)
+        json(conn, %{data: media_item})
+
+      {:error, %Ecto.Changeset{} = changeset} ->
+        conn
+        |> put_status(:unprocessable_entity)
+        |> json(%{errors: format_changeset_errors(changeset)})
+    end
+  end
+
+  def delete(conn, %{"id" => id} = params) do
+    prevent_download = Map.get(params, "prevent_download", "false") == "true"
+    media_item = Media.get_media_item!(id)
+
+    {:ok, _} = Media.delete_media_files(media_item, %{prevent_download: prevent_download})
+
+    json(conn, %{data: %{message: "Files deleted successfully."}})
+  end
+
+  defp format_changeset_errors(changeset) do
+    Ecto.Changeset.traverse_errors(changeset, fn {msg, opts} ->
+      Enum.reduce(opts, msg, fn {key, value}, acc ->
+        String.replace(acc, "%{#{key}}", to_string(value))
+      end)
+    end)
+  end
+end

lib/pinchflat_web/controllers/api/v1/api_media_profile_controller.ex

@@ -0,0 +1,68 @@
+defmodule PinchflatWeb.Api.V1.ApiMediaProfileController do
+  @moduledoc """
+  JSON API controller for MediaProfiles.
+  """
+
+  use PinchflatWeb, :controller
+
+  alias Pinchflat.Profiles
+  alias Pinchflat.Profiles.MediaProfile
+
+  def index(conn, _params) do
+    json(conn, %{data: Profiles.list_media_profiles()})
+  end
+
+  def show(conn, %{"id" => id}) do
+    json(conn, %{data: Profiles.get_media_profile!(id)})
+  end
+
+  def create(conn, %{"media_profile" => params}) do
+    case Profiles.create_media_profile(params) do
+      {:ok, media_profile} ->
+        conn
+        |> put_status(:created)
+        |> json(%{data: media_profile})
+
+      {:error, %Ecto.Changeset{} = changeset} ->
+        conn
+        |> put_status(:unprocessable_entity)
+        |> json(%{errors: format_changeset_errors(changeset)})
+    end
+  end
+
+  def update(conn, %{"id" => id, "media_profile" => params}) do
+    media_profile = Profiles.get_media_profile!(id)
+
+    case Profiles.update_media_profile(media_profile, params) do
+      {:ok, media_profile} ->
+        json(conn, %{data: media_profile})
+
+      {:error, %Ecto.Changeset{} = changeset} ->
+        conn
+        |> put_status(:unprocessable_entity)
+        |> json(%{errors: format_changeset_errors(changeset)})
+    end
+  end
+
+  def delete(conn, %{"id" => id}) do
+    media_profile = Profiles.get_media_profile!(id)
+
+    case Profiles.delete_media_profile(media_profile) do
+      {:ok, _} ->
+        json(conn, %{data: %{message: "Media profile deleted."}})
+
+      {:error, %Ecto.Changeset{} = changeset} ->
+        conn
+        |> put_status(:unprocessable_entity)
+        |> json(%{errors: format_changeset_errors(changeset)})
+    end
+  end
+
+  defp format_changeset_errors(changeset) do
+    Ecto.Changeset.traverse_errors(changeset, fn {msg, opts} ->
+      Enum.reduce(opts, msg, fn {key, value}, acc ->
+        String.replace(acc, "%{#{key}}", to_string(value))
+      end)
+    end)
+  end
+end

lib/pinchflat_web/controllers/api/v1/api_setting_controller.ex

@@ -0,0 +1,56 @@
+defmodule PinchflatWeb.Api.V1.ApiSettingController do
+  @moduledoc """
+  JSON API controller for Settings.
+  """
+
+  use PinchflatWeb, :controller
+
+  alias Pinchflat.Settings
+
+  def show(conn, _params) do
+    setting = Settings.record()
+    safe_data = setting_to_map(setting)
+    json(conn, %{data: safe_data})
+  end
+
+  def update(conn, %{"setting" => params}) do
+    setting = Settings.record()
+
+    case Settings.update_setting(setting, params) do
+      {:ok, setting} ->
+        safe_data = setting_to_map(setting)
+        json(conn, %{data: safe_data})
+
+      {:error, %Ecto.Changeset{} = changeset} ->
+        conn
+        |> put_status(:unprocessable_entity)
+        |> json(%{errors: format_changeset_errors(changeset)})
+    end
+  end
+
+  def app_info(conn, _params) do
+    info = %{
+      version: Application.spec(:pinchflat, :vsn) |> to_string(),
+      environment: Application.get_env(:pinchflat, :env),
+      yt_dlp_version: Settings.get!(:yt_dlp_version),
+      apprise_version: Settings.get!(:apprise_version),
+      onboarding: Settings.get!(:onboarding)
+    }
+
+    json(conn, %{data: info})
+  end
+
+  defp setting_to_map(setting) do
+    setting
+    |> Map.from_struct()
+    |> Map.drop([:route_token, :__meta__, :__struct__])
+  end
+
+  defp format_changeset_errors(changeset) do
+    Ecto.Changeset.traverse_errors(changeset, fn {msg, opts} ->
+      Enum.reduce(opts, msg, fn {key, value}, acc ->
+        String.replace(acc, "%{#{key}}", to_string(value))
+      end)
+    end)
+  end
+end

lib/pinchflat_web/controllers/api/v1/api_source_controller.ex

@@ -0,0 +1,118 @@
+defmodule PinchflatWeb.Api.V1.ApiSourceController do
+  @moduledoc """
+  JSON API controller for Sources.
+  """
+
+  use PinchflatWeb, :controller
+
+  alias Pinchflat.Repo
+  alias Pinchflat.Sources
+  alias Pinchflat.Sources.Source
+  alias Pinchflat.Tasks
+  alias Pinchflat.Downloading.DownloadingHelpers
+  alias Pinchflat.SlowIndexing.SlowIndexingHelpers
+  alias Pinchflat.Metadata.SourceMetadataStorageWorker
+  alias Pinchflat.Media.FileSyncingWorker
+  alias Pinchflat.Sources.SourceDeletionWorker
+
+  def index(conn, _params) do
+    sources = Sources.list_sources() |> Repo.preload(:media_profile)
+    json(conn, %{data: sources})
+  end
+
+  def show(conn, %{"id" => id}) do
+    source = Sources.get_source!(id) |> Repo.preload([:media_profile, :media_items])
+
+    pending_tasks =
+      source
+      |> Tasks.list_tasks_for(nil, [:executing, :available, :scheduled, :retryable])
+      |> Repo.preload(:job)
+
+    json(conn, %{data: source, pending_tasks: pending_tasks})
+  end
+
+  def create(conn, %{"source" => source_params}) do
+    case Sources.create_source(source_params) do
+      {:ok, source} ->
+        source = Repo.preload(source, :media_profile)
+        conn
+        |> put_status(:created)
+        |> json(%{data: source})
+
+      {:error, %Ecto.Changeset{} = changeset} ->
+        conn
+        |> put_status(:unprocessable_entity)
+        |> json(%{errors: format_changeset_errors(changeset)})
+    end
+  end
+
+  def update(conn, %{"id" => id, "source" => source_params}) do
+    source = Sources.get_source!(id)
+
+    case Sources.update_source(source, source_params) do
+      {:ok, source} ->
+        source = Repo.preload(source, :media_profile)
+        json(conn, %{data: source})
+
+      {:error, %Ecto.Changeset{} = changeset} ->
+        conn
+        |> put_status(:unprocessable_entity)
+        |> json(%{errors: format_changeset_errors(changeset)})
+    end
+  end
+
+  def delete(conn, %{"id" => id} = params) do
+    delete_files = Map.get(params, "delete_files", "false") == "true"
+    source = Sources.get_source!(id)
+
+    {:ok, _} = Sources.update_source(source, %{marked_for_deletion_at: DateTime.utc_now()})
+    SourceDeletionWorker.kickoff(source, %{delete_files: delete_files})
+
+    conn
+    |> put_status(:ok)
+    |> json(%{data: %{id: source.id, message: "Source deletion started."}})
+  end
+
+  def force_download_pending(conn, %{"source_id" => id}) do
+    source = Sources.get_source!(id)
+    DownloadingHelpers.enqueue_pending_download_tasks(source)
+
+    json(conn, %{data: %{message: "Forcing download of pending media items."}})
+  end
+
+  def force_redownload(conn, %{"source_id" => id}) do
+    source = Sources.get_source!(id)
+    DownloadingHelpers.kickoff_redownload_for_existing_media(source)
+
+    json(conn, %{data: %{message: "Forcing re-download of downloaded media items."}})
+  end
+
+  def force_index(conn, %{"source_id" => id}) do
+    source = Sources.get_source!(id)
+    SlowIndexingHelpers.kickoff_indexing_task(source, %{force: true})
+
+    json(conn, %{data: %{message: "Index enqueued."}})
+  end
+
+  def force_metadata_refresh(conn, %{"source_id" => id}) do
+    source = Sources.get_source!(id)
+    SourceMetadataStorageWorker.kickoff_with_task(source)
+
+    json(conn, %{data: %{message: "Metadata refresh enqueued."}})
+  end
+
+  def sync_files_on_disk(conn, %{"source_id" => id}) do
+    source = Sources.get_source!(id)
+    FileSyncingWorker.kickoff_with_task(source)
+
+    json(conn, %{data: %{message: "File sync enqueued."}})
+  end
+
+  defp format_changeset_errors(changeset) do
+    Ecto.Changeset.traverse_errors(changeset, fn {msg, opts} ->
+      Enum.reduce(opts, msg, fn {key, value}, acc ->
+        String.replace(acc, "%{#{key}}", to_string(value))
+      end)
+    end)
+  end
+end

lib/pinchflat_web/controllers/api/v1/api_task_controller.ex

@@ -0,0 +1,31 @@
+defmodule PinchflatWeb.Api.V1.ApiTaskController do
+  @moduledoc """
+  JSON API controller for Tasks.
+  """
+
+  use PinchflatWeb, :controller
+
+  alias Pinchflat.Repo
+  alias Pinchflat.Tasks
+
+  def index(conn, params) do
+    tasks =
+      case params do
+        %{"source_id" => source_id} ->
+          source = Pinchflat.Sources.get_source!(source_id)
+          Tasks.list_tasks_for(source)
+          |> Repo.preload(:job)
+
+        _ ->
+          Tasks.list_tasks()
+          |> Repo.preload(:job)
+      end
+
+    json(conn, %{data: tasks})
+  end
+
+  def show(conn, %{"id" => id}) do
+    task = Tasks.get_task!(id) |> Repo.preload(:job)
+    json(conn, %{data: task})
+  end
+end