`test/openagents_web/controllers/api_error_contract_test.exs`, and

`test/openagents_web/controllers/api_extension_controller_test.exs`.

### FORGEAPI-002 — The path names this API's version, and `/api/v3` is a dated alias

### FORGEAPI-002 — The path names this API's version, and `/api/v3` is gone

Status: Current

and this application serves neither, so the prefix buys no working command.

The one surface it does serve, the `gh api` passthrough, already reaches

`/api/v1` when it is given a full URL. `gh` is therefore not a supported

client, and `/api/v3` is a migration alias for released clients with a

deletion scheduled, not a compatibility promise. The reasoning and the

measurements are

client, and `/api/v3` was a migration alias rather than a compatibility

promise. The reasoning and the measurements are

`docs/decisions/0009-serve-a-github-shaped-api-not-a-gh-compatible-one.md`.

Because the alias is temporary, nothing may come to depend on it. Every

versioned route is declared at `/api/v1`, and every URL a response emits names

`/api/v1`, so a link this API hands a client survives the deletion.

`OpenAgentsWeb.Plugs.ApiV3Rewrite` is the only file under `lib/` that names the

old prefix at all, and a proof reads the tree for that, because the reasoning

does not survive on care alone: the trace ingest route landed mid-rename and

returned a `url` field naming `/api/v3/traces/{id}`, a link that would have

gone dead the day the alias did. Deleting the alias stays what it should be, a

one-file change with one test.

The alias was deleted on 2026-08-25 (#216), the day `@openagentsinc/cli@0.4.0`

was published and the one client still on the old prefix was upgraded to it.

Nothing under `lib/` names the old prefix now, and a proof reads the tree for

that rather than trusting care: the trace ingest route landed mid-rename and

returned a `url` field naming `/api/v3/traces/{id}`, a link that went dead the

day the alias did. Every versioned route is declared at `/api/v1` and every URL

a response emits names `/api/v1`.

Evidence: `lib/openagents_web/plugs/api_v3_rewrite.ex`,

`lib/openagents_web/router.ex`,

  # Analytics hints only; identity still comes from the session.

  plug PostHog.Integrations.Plug

  plug OpenAgentsWeb.Plugs.ApiV3Rewrite

  plug OpenAgentsWeb.Router

end

defmodule OpenAgentsWeb.Plugs.ApiV3Rewrite do

  @moduledoc """

  Transparently rewrites `/api/v3/*` requests to `/api/v1/*`.

  The API moved from `/api/v3` to `/api/v1` in one deploy, so clients released

  against the old prefix keep working while the fleet upgrades. This plug

  modifies `conn.path_info` before the router sees it, rather than redirecting,

  because the old clients `POST` and do not follow redirects reliably.

  The alias is dated, not permanent. It exists for released clients, not for

  `gh`: `gh` reaches a non-github.com host at `/api/v3`, but its ported

  commands run on GraphQL and `GET /api/v3/meta`, neither of which this

  application serves, so keeping the prefix would not make `gh` work. See

  `docs/decisions/0009-serve-a-github-shaped-api-not-a-gh-compatible-one.md`

  and `INVARIANTS.md`, FORGEAPI-002.

  This module is the only place in `lib/` that names the old prefix. Nothing

  routes at it and no response emits it, which is what makes deleting the alias

  a one-file change.

  """

  @behaviour Plug

  @impl true

  def init(opts), do: opts

  @impl true

  def call(%Plug.Conn{path_info: ["api", "v3" | rest]} = conn, _opts) do

    %{conn | path_info: ["api", "v1" | rest]}

  end

  def call(conn, _opts), do: conn

end

  https://openagents.com/api/v1/repos/OWNER/REPO/issues`, but `curl` and the

  `openagents` CLI do the same job without the confusion.

Requests to `/api/v3` still answer today. That prefix is a temporary alias for

clients released before the API moved to `/api/v1`, and it is scheduled for

removal. Send new work to `/api/v1`.

`/api/v3` no longer answers. It was a migration alias for clients released

before the API moved to `/api/v1`, and it was removed on 2026-08-25 once the

last client using it was upgraded. Send everything to `/api/v1`.

## Know the compatibility limits

defmodule OpenAgentsWeb.ApiVersionPostureTest do

  @moduledoc """

  Proves FORGEAPI-002: the version in the path is this API's own, and `/api/v3`

  is a dated alias nothing is allowed to depend on.

  Proves FORGEAPI-002: the version in the path is this API's own, and the

  `/api/v3` alias is gone.

  The alias is one plug and one deletion away from gone. These assertions keep

  it that way, because the failure mode is quiet: a route or a rendered link

  written against the old prefix works perfectly until the day the alias is

  removed, and then it does not.

  The alias was removed on 2026-08-25 (#216), once the only client that used

  it was upgraded. These assertions keep the old prefix from coming back by

  the same quiet route it would have left by: a link or a rendered `url`

  written against it looks fine until someone follows it.

  """

  use ExUnit.Case, async: true

  @alias_plug "lib/openagents_web/plugs/api_v3_rewrite.ex"

  @legacy_prefix "api/v3"

  test "every versioned route is declared at /api/v1" do

    #{Enum.map_join(misversioned, "\n", &"  #{&1}")}

    The path names this API's version. Old prefixes are served by

    OpenAgentsWeb.Plugs.ApiV3Rewrite, never declared in the router.

    The path names this API's version, and no other version is served.

    """

  end

  test "the alias plug is the only file under lib/ that names the old prefix" do

  test "no file under lib/ names the old prefix" do

    offenders =

      Path.wildcard("lib/**/*.ex")

      |> Enum.reject(&(&1 == @alias_plug))

      |> Enum.filter(&String.contains?(File.read!(&1), @legacy_prefix))

    assert offenders == [], """

defmodule OpenAgentsWeb.Plugs.ApiV3RewriteTest do

  use OpenAgentsWeb.ConnCase, async: true

  alias OpenAgentsWeb.Plugs.ApiV3Rewrite

  describe "unit test call/2" do

    test "rewrites api/v3 prefix to api/v1" do

      conn = %Plug.Conn{path_info: ["api", "v3", "repos", "owner", "repo", "issues"]}

      rewritten = ApiV3Rewrite.call(conn, [])

      assert rewritten.path_info == ["api", "v1", "repos", "owner", "repo", "issues"]

    end

    test "rewrites root api/v3 path" do

      conn = %Plug.Conn{path_info: ["api", "v3"]}

      rewritten = ApiV3Rewrite.call(conn, [])

      assert rewritten.path_info == ["api", "v1"]

    end

    test "leaves api/v1 and other paths untouched" do

      conn_v1 = %Plug.Conn{path_info: ["api", "v1", "repos"]}

      assert ApiV3Rewrite.call(conn_v1, []) == conn_v1

      conn_status = %Plug.Conn{path_info: ["status"]}

      assert ApiV3Rewrite.call(conn_status, []) == conn_status

    end

  end

  describe "integration through Endpoint" do

    test "GET /api/v3 transparently answers from the /api/v1 root document", %{conn: conn} do

      res = get(conn, "/api/v3")

      assert json_response(res, 200)["api_version"] == "v1"

    end

    test "GET /api/v3/repos/:owner/:repo/issues transparently answers from /api/v1", %{conn: conn} do

      res = get(conn, "/api/v3/repos/OpenAgentsInc/openagents.com/issues")

      assert json_response(res, 200)["issues"] != nil

    end

  end

end