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

test/pinchflat_web/controllers/api/v1/api_media_item_controller_test.exs

@@ -0,0 +1,80 @@
+defmodule PinchflatWeb.Api.V1.ApiMediaItemControllerTest do
+  use PinchflatWeb.ConnCase
+
+  import Pinchflat.MediaFixtures
+  import Pinchflat.SourcesFixtures
+  import Pinchflat.ProfilesFixtures
+
+  alias Pinchflat.Downloading.MediaDownloadWorker
+
+  describe "GET /api/v1/media" do
+    test "lists all media items as JSON", %{conn: conn} do
+      media_item = media_item_fixture()
+      conn = get(conn, ~p"/api/v1/media")
+
+      assert %{status: 200} = conn
+      data = json_response(conn, 200)["data"]
+      assert length(data) == 1
+      assert hd(data)["id"] == media_item.id
+    end
+
+    test "filters by source_id", %{conn: conn} do
+      source1 = source_fixture()
+      source2 = source_fixture()
+      _media1 = media_item_fixture(%{source_id: source1.id})
+      _media2 = media_item_fixture(%{source_id: source2.id})
+
+      conn = get(conn, ~p"/api/v1/media?source_id=#{source1.id}")
+
+      assert %{status: 200} = conn
+      data = json_response(conn, 200)["data"]
+      assert length(data) == 1
+    end
+  end
+
+  describe "GET /api/v1/media/:id" do
+    test "shows a media item as JSON", %{conn: conn} do
+      media_item = media_item_fixture()
+      conn = get(conn, ~p"/api/v1/media/#{media_item.id}")
+
+      assert %{status: 200} = conn
+      assert json_response(conn, 200)["data"]["id"] == media_item.id
+    end
+
+    test "returns 404 for non-existent media item", %{conn: conn} do
+      conn = get(conn, ~p"/api/v1/media/999999")
+
+      assert %{status: 404} = conn
+    end
+  end
+
+  describe "GET /api/v1/media/search" do
+    test "returns search results as JSON", %{conn: conn} do
+      media_item = media_item_fixture(%{title: "Cool Video About Elixir"})
+      conn = get(conn, ~p"/api/v1/media/search?q=Elixir")
+
+      assert %{status: 200} = conn
+      data = json_response(conn, 200)["data"]
+      assert length(data) >= 1
+    end
+
+    test "returns empty for blank query", %{conn: conn} do
+      conn = get(conn, ~p"/api/v1/media/search?q=")
+
+      assert %{status: 200} = conn
+      assert json_response(conn, 200)["data"] == []
+    end
+  end
+
+  describe "POST /api/v1/media/:media_item_id/force_download" do
+    test "enqueues a download task", %{conn: conn} do
+      media_item = media_item_fixture(%{media_filepath: nil})
+
+      assert [] = all_enqueued(worker: MediaDownloadWorker)
+      conn = post(conn, ~p"/api/v1/media/#{media_item.id}/force_download")
+
+      assert %{status: 200} = conn
+      assert [_] = all_enqueued(worker: MediaDownloadWorker)
+    end
+  end
+end

test/pinchflat_web/controllers/api/v1/api_media_profile_controller_test.exs

@@ -0,0 +1,43 @@
+defmodule PinchflatWeb.Api.V1.ApiMediaProfileControllerTest do
+  use PinchflatWeb.ConnCase
+
+  import Pinchflat.ProfilesFixtures
+
+  describe "GET /api/v1/media_profiles" do
+    test "lists all media profiles as JSON", %{conn: conn} do
+      media_profile = media_profile_fixture()
+      conn = get(conn, ~p"/api/v1/media_profiles")
+
+      assert %{status: 200} = conn
+      data = json_response(conn, 200)["data"]
+      assert length(data) >= 1
+      ids = Enum.map(data, & &1["id"])
+      assert media_profile.id in ids
+    end
+  end
+
+  describe "GET /api/v1/media_profiles/:id" do
+    test "shows a media profile as JSON", %{conn: conn} do
+      media_profile = media_profile_fixture()
+      conn = get(conn, ~p"/api/v1/media_profiles/#{media_profile.id}")
+
+      assert %{status: 200} = conn
+      assert json_response(conn, 200)["data"]["id"] == media_profile.id
+    end
+  end
+
+  describe "POST /api/v1/media_profiles" do
+    test "creates a media profile and returns 201", %{conn: conn} do
+      conn = post(conn, ~p"/api/v1/media_profiles", media_profile: %{name: "Test Profile", output_path_template: "{{title}}.{{ext}}"})
+
+      assert %{status: 201} = conn
+      assert json_response(conn, 201)["data"]["name"] == "Test Profile"
+    end
+
+    test "returns 422 when data is invalid", %{conn: conn} do
+      conn = post(conn, ~p"/api/v1/media_profiles", media_profile: %{name: nil})
+
+      assert %{status: 422} = conn
+    end
+  end
+end

test/pinchflat_web/controllers/api/v1/api_setting_controller_test.exs

@@ -0,0 +1,45 @@
+defmodule PinchflatWeb.Api.V1.ApiSettingControllerTest do
+  use PinchflatWeb.ConnCase
+
+  import Pinchflat.ProfilesFixtures
+
+  alias Pinchflat.Settings
+
+  describe "GET /api/v1/settings" do
+    test "returns settings as JSON", %{conn: conn} do
+      conn = get(conn, ~p"/api/v1/settings")
+
+      assert %{status: 200} = conn
+      data = json_response(conn, 200)["data"]
+      assert data["onboarding"] != nil
+    end
+
+    test "does not expose route_token", %{conn: conn} do
+      conn = get(conn, ~p"/api/v1/settings")
+
+      assert %{status: 200} = conn
+      data = json_response(conn, 200)["data"]
+      refute Map.has_key?(data, "route_token")
+    end
+  end
+
+  describe "PUT /api/v1/settings" do
+    test "updates settings", %{conn: conn} do
+      conn = put(conn, ~p"/api/v1/settings", setting: %{onboarding: false})
+
+      assert %{status: 200} = conn
+      assert json_response(conn, 200)["data"]["onboarding"] == false
+    end
+  end
+
+  describe "GET /api/v1/app_info" do
+    test "returns app info as JSON", %{conn: conn} do
+      conn = get(conn, ~p"/api/v1/app_info")
+
+      assert %{status: 200} = conn
+      data = json_response(conn, 200)["data"]
+      assert data["version"] != nil
+      assert data["environment"] != nil
+    end
+  end
+end

test/pinchflat_web/controllers/api/v1/api_source_controller_test.exs

@@ -0,0 +1,187 @@
+defmodule PinchflatWeb.Api.V1.ApiSourceControllerTest do
+  use PinchflatWeb.ConnCase
+
+  import Pinchflat.MediaFixtures
+  import Pinchflat.SourcesFixtures
+  import Pinchflat.ProfilesFixtures
+
+  alias Pinchflat.Settings
+  alias Pinchflat.Downloading.MediaDownloadWorker
+  alias Pinchflat.SlowIndexing.MediaCollectionIndexingWorker
+  alias Pinchflat.Metadata.SourceMetadataStorageWorker
+  alias Pinchflat.Media.FileSyncingWorker
+
+  setup do
+    media_profile = media_profile_fixture()
+    Settings.set(onboarding: false)
+
+    {:ok,
+     %{
+       media_profile: media_profile,
+       create_attrs: %{
+         media_profile_id: media_profile.id,
+         collection_type: "channel",
+         original_url: "https://www.youtube.com/source/abc123"
+       },
+       update_attrs: %{
+         original_url: "https://www.youtube.com/source/321xyz"
+       },
+       invalid_attrs: %{original_url: nil, media_profile_id: nil}
+     }}
+  end
+
+  describe "GET /api/v1/sources" do
+    test "lists all sources as JSON", %{conn: conn} do
+      source = source_fixture()
+      conn = get(conn, ~p"/api/v1/sources")
+
+      assert %{status: 200} = conn
+      data = json_response(conn, 200)["data"]
+      assert length(data) == 1
+      assert hd(data)["id"] == source.id
+    end
+  end
+
+  describe "GET /api/v1/sources/:id" do
+    test "shows a source as JSON", %{conn: conn} do
+      source = source_fixture()
+      conn = get(conn, ~p"/api/v1/sources/#{source.id}")
+
+      assert %{status: 200} = conn
+      assert json_response(conn, 200)["data"]["id"] == source.id
+    end
+
+    test "returns 404 for non-existent source", %{conn: conn} do
+      conn = get(conn, ~p"/api/v1/sources/999999")
+
+      assert %{status: 404} = conn
+    end
+  end
+
+  describe "POST /api/v1/sources" do
+    test "creates a source and returns 201", %{conn: conn, create_attrs: create_attrs} do
+      expect(YtDlpRunnerMock, :run, 1, &runner_function_mock/5)
+
+      conn = post(conn, ~p"/api/v1/sources", source: create_attrs)
+
+      assert %{status: 201} = conn
+      assert json_response(conn, 201)["data"]["id"] != nil
+    end
+
+    test "returns 422 when data is invalid", %{conn: conn, invalid_attrs: invalid_attrs} do
+      conn = post(conn, ~p"/api/v1/sources", source: invalid_attrs)
+
+      assert %{status: 422} = conn
+      assert json_response(conn, 422)["errors"] != nil
+    end
+  end
+
+  describe "PUT /api/v1/sources/:id" do
+    setup [:create_source]
+
+    test "updates the source", %{conn: conn, source: source, update_attrs: update_attrs} do
+      expect(YtDlpRunnerMock, :run, 1, &runner_function_mock/5)
+
+      conn = put(conn, ~p"/api/v1/sources/#{source.id}", source: update_attrs)
+
+      assert %{status: 200} = conn
+      assert json_response(conn, 200)["data"]["original_url"] == "https://www.youtube.com/source/321xyz"
+    end
+
+    test "returns 422 when data is invalid", %{conn: conn, source: source, invalid_attrs: invalid_attrs} do
+      conn = put(conn, ~p"/api/v1/sources/#{source.id}", source: invalid_attrs)
+
+      assert %{status: 422} = conn
+    end
+  end
+
+  describe "DELETE /api/v1/sources/:id" do
+    setup [:create_source]
+
+    test "marks source for deletion", %{conn: conn, source: source} do
+      conn = delete(conn, ~p"/api/v1/sources/#{source.id}")
+
+      assert %{status: 200} = conn
+      assert json_response(conn, 200)["data"]["message"] =~ "deletion"
+    end
+  end
+
+  describe "POST /api/v1/sources/:source_id/force_download_pending" do
+    test "enqueues pending download tasks", %{conn: conn} do
+      source = source_fixture()
+      _media_item = media_item_fixture(%{source_id: source.id, media_filepath: nil})
+
+      assert [] = all_enqueued(worker: MediaDownloadWorker)
+      conn = post(conn, ~p"/api/v1/sources/#{source.id}/force_download_pending")
+
+      assert %{status: 200} = conn
+      assert [_] = all_enqueued(worker: MediaDownloadWorker)
+    end
+  end
+
+  describe "POST /api/v1/sources/:source_id/force_redownload" do
+    test "enqueues re-download tasks", %{conn: conn} do
+      source = source_fixture()
+      _media_item = media_item_fixture(source_id: source.id, media_downloaded_at: now())
+
+      assert [] = all_enqueued(worker: MediaDownloadWorker)
+      conn = post(conn, ~p"/api/v1/sources/#{source.id}/force_redownload")
+
+      assert %{status: 200} = conn
+      assert [_] = all_enqueued(worker: MediaDownloadWorker)
+    end
+  end
+
+  describe "POST /api/v1/sources/:source_id/force_index" do
+    test "forces an index", %{conn: conn} do
+      source = source_fixture()
+
+      assert [] = all_enqueued(worker: MediaCollectionIndexingWorker)
+      conn = post(conn, ~p"/api/v1/sources/#{source.id}/force_index")
+
+      assert %{status: 200} = conn
+      assert [_] = all_enqueued(worker: MediaCollectionIndexingWorker)
+    end
+  end
+
+  describe "POST /api/v1/sources/:source_id/force_metadata_refresh" do
+    test "forces a metadata refresh", %{conn: conn} do
+      source = source_fixture()
+
+      assert [] = all_enqueued(worker: SourceMetadataStorageWorker)
+      conn = post(conn, ~p"/api/v1/sources/#{source.id}/force_metadata_refresh")
+
+      assert %{status: 200} = conn
+      assert [_] = all_enqueued(worker: SourceMetadataStorageWorker)
+    end
+  end
+
+  describe "POST /api/v1/sources/:source_id/sync_files_on_disk" do
+    test "forces a file sync", %{conn: conn} do
+      source = source_fixture()
+
+      assert [] = all_enqueued(worker: FileSyncingWorker)
+      conn = post(conn, ~p"/api/v1/sources/#{source.id}/sync_files_on_disk")
+
+      assert %{status: 200} = conn
+      assert [_] = all_enqueued(worker: FileSyncingWorker)
+    end
+  end
+
+  defp create_source(_) do
+    source = source_fixture()
+    media_item = media_item_with_attachments(%{source_id: source.id})
+
+    %{source: source, media_item: media_item}
+  end
+
+  defp runner_function_mock(_url, :get_source_details, _opts, _ot, _addl) do
+    {:ok,
+     Phoenix.json_library().encode!(%{
+       channel: "some channel name",
+       channel_id: "some_channel_id_#{:rand.uniform(1_000_000)}",
+       playlist_id: "some_playlist_id_#{:rand.uniform(1_000_000)}",
+       playlist_title: "some playlist name"
+     })}
+  end
+end

test/pinchflat_web/controllers/api/v1/api_task_controller_test.exs

@@ -0,0 +1,48 @@
+defmodule PinchflatWeb.Api.V1.ApiTaskControllerTest do
+  use PinchflatWeb.ConnCase
+
+  import Pinchflat.SourcesFixtures
+  import Pinchflat.MediaFixtures
+
+  alias Pinchflat.SlowIndexing.MediaCollectionIndexingWorker
+
+  describe "GET /api/v1/tasks" do
+    test "lists all tasks as JSON", %{conn: conn} do
+      source = source_fixture()
+      {:ok, task} = MediaCollectionIndexingWorker.kickoff_with_task(source)
+
+      conn = get(conn, ~p"/api/v1/tasks")
+
+      assert %{status: 200} = conn
+      data = json_response(conn, 200)["data"]
+      ids = Enum.map(data, & &1["id"])
+      assert task.id in ids
+    end
+
+    test "filters by source_id", %{conn: conn} do
+      source1 = source_fixture()
+      source2 = source_fixture()
+      {:ok, task1} = MediaCollectionIndexingWorker.kickoff_with_task(source1)
+      {:ok, _task2} = MediaCollectionIndexingWorker.kickoff_with_task(source2)
+
+      conn = get(conn, ~p"/api/v1/tasks?source_id=#{source1.id}")
+
+      assert %{status: 200} = conn
+      data = json_response(conn, 200)["data"]
+      assert length(data) == 1
+      assert hd(data)["id"] == task1.id
+    end
+  end
+
+  describe "GET /api/v1/tasks/:id" do
+    test "shows a task as JSON", %{conn: conn} do
+      source = source_fixture()
+      {:ok, task} = MediaCollectionIndexingWorker.kickoff_with_task(source)
+
+      conn = get(conn, ~p"/api/v1/tasks/#{task.id}")
+
+      assert %{status: 200} = conn
+      assert json_response(conn, 200)["data"]["id"] == task.id
+    end
+  end
+end