`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

Status: Current

The version segment in `/api/v1` names this API's own version. It does not

name GitHub's. The API is GitHub-shaped — familiar paths and response shapes,

so a client you already know is cheap to adapt — and it is not GitHub, so a

version GitHub chose is the wrong number to serve under.

That distinction is load-bearing because one tool disagrees with it. GitHub's

`gh` reaches any non-github.com host at a hardcoded `/api/v3` prefix, which

reads as a reason to serve that prefix forever. It is not one. Measured

against `gh` 2.89.0, the ported commands never reach REST: `gh issue list`

sends GraphQL to `/api/graphql` and `gh issue view` probes `GET /api/v3/meta`,

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

`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.

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

`lib/openagents_web/router.ex`,

`lib/openagents_web/controllers/trace_controller.ex`,

`test/openagents_web/api_version_posture_test.exs`, and

`test/openagents_web/plugs/api_v3_rewrite_test.exs`.

## Executable proof index

This index is part of the ledger. Every `Current` invariant has at least one

| NOTIFY-001 | `test/openagents/notifications_test.exs`, `test/openagents_web/live/notifications_live_test.exs` |

| FORGEAPI-001 | `test/openagents_web/controllers/api_error_contract_test.exs`, `test/openagents_web/controllers/api_extension_controller_test.exs`, `test/openagents_web/api_error_test.exs`, `test/openagents_web/controllers/issue_controller_test.exs` |

| FORGEAPI-002 | `test/openagents_web/api_version_posture_test.exs`, `test/openagents_web/plugs/api_v3_rewrite_test.exs` |

| DATA-001 | `test/openagents/conversations_test.exs` |

| DATA-002 | `test/openagents/accounts_test.exs`, `test/openagents/conversations_test.exs` |

| DATA-003 | `test/openagents/conversations_test.exs` |

# ADR 0009: Serve a GitHub-shaped API, not a `gh`-compatible one

Date: 2026-08-25

Status: Accepted

## Context

The API moved from `/api/v3` to `/api/v1` (issue #211). The version in the path

names this API's own version, and this API is at its first. One deploy serves

both paths: `OpenAgentsWeb.Plugs.ApiV3Rewrite` rewrites `/api/v3/*` to

`/api/v1/*` so that clients released against the old prefix keep working while

the fleet upgrades.

That alias raised a question the rename audit

(`docs/2026-08-24-api-v1-rename-audit.md`) left open, and issue #215 asks you

to settle: GitHub's own CLI hardcodes `https://HOST/api/v3/` for any host other

than github.com, with no way to override the path segment. If `gh` is a client

this forge wants, the alias can never be deleted.

The audit stopped at the path. Reading the path alone suggests that keeping

`/api/v3` buys `gh` compatibility for the price of one plug. Running `gh`

against the live application says otherwise. Every row below is `gh` 2.89.0

against `openagents.com` on 2026-08-25, captured with `GH_DEBUG=api`:

| Command | Request `gh` makes | Result |

| --- | --- | --- |

| `gh issue list -R …` | `POST /api/graphql` | `404` |

| `gh issue view 215 -R …` | `GET /api/v3/meta` | `406` |

| `gh api repos/OWNER/REPO/issues` | `GET /api/v3/repos/…/issues` | `200` |

| `gh api https://openagents.com/api/v1/repos/OWNER/REPO/issues` | `GET /api/v1/repos/…/issues` | `200` |

Three facts follow.

- The ported commands do not use REST. `gh issue list` sends a GraphQL query to

  `/api/graphql`, and `gh issue view` first probes `GET /api/v3/meta`. This

  application serves neither endpoint, so no alias makes those commands work.

- The one `gh` surface the alias keeps alive is `gh api`, the raw REST

  passthrough, which is a `curl` substitute rather than a reason to use `gh`.

- Even `gh api` does not need the alias. Given a full URL it calls `/api/v1`

  directly and answers `200`. Only a bare path picks up the `/api/v3` prefix.

## Decision

Serve a GitHub-shaped API, and do not claim `gh` compatibility.

- `gh` is not a supported client. The supported clients are the `openagents`

  CLI, which is first-class, and any GitHub-shaped client that takes an

  explicit base URL, such as Octokit configured with

  `baseUrl: "https://openagents.com/api/v1"`.

- `/api/v3` stays a dated migration alias for released clients, and it gets

  deleted on the schedule issue #216 describes. Nothing about `gh` makes it

  permanent.

- Every versioned route is declared at `/api/v1`, and every URL a response

  emits names `/api/v1`. `OpenAgentsWeb.Plugs.ApiV3Rewrite` is the only place

  in `lib/` that names the old prefix, so removing the alias stays a one-file

  change. `INVARIANTS.md` records this as FORGEAPI-002, and

  `test/openagents_web/api_version_posture_test.exs` proves it.

## Consequences

- Issue #216 proceeds. The gh-posture decision it waited on does not make the

  alias permanent.

- Documentation states the limit rather than implying drop-in tooling.

  `priv/docs/rest-api.md` names `gh` as unsupported and gives you the two

  clients that work. The episode 273 summary in `docs/episode-triage.md`

  carries a dated correction, because "so `gh` and octokit work unchanged"

  recorded an intent that the evidence does not support.

- A response that emits an `/api/v3` URL is now a build failure. The trace

  ingest route landed during the rename and returned a `url` field naming

  `/api/v3/traces/{id}`, a link that would have gone dead with the alias. That

  is fixed, and the proof stops the next one.

- If `gh` compatibility is ever worth having, the work is a GraphQL endpoint

  and `GET /api/v1/meta`, plus restoring the `/api/v3` prefix. That is a

  product decision about serving GraphQL, not a decision about a path segment,

  and it belongs in its own ADR.

app; build order: issues first so development organizes itself publicly, then

Projects V2 reads, then write endpoints, targeting GitHub API parity on the

subset actually used (84 endpoints in the March 2026 spec tied to

issues/projects) so `gh` and octokit work unchanged. DaisyUI-vs-Basecoat debate

resolved toward simplicity (later reversed by the staging incident recorded in

AGENTS.md). Bounties, leaderboard, and in-forge chat teased.

issues/projects) so `gh` and octokit work unchanged (half true, and corrected

2026-08-25 by ADR 0009: the shape carries octokit given a base URL, but never

carried `gh`, whose ported commands run on GraphQL rather than REST). The

DaisyUI-vs-Basecoat debate resolved toward simplicity (later reversed by the

staging incident recorded in AGENTS.md). Bounties, leaderboard, and in-forge

chat teased.

#### 274 — Importing Repos

- Nonnumeric issue and milestone numbers can produce `500 Internal Server

  Error` instead of `404 Not Found`.

- Pagination and link headers are a bounded local contract, not complete

  Octokit or `gh` parity.

  Octokit parity. `gh` is not a supported client at any level: its ported

  commands run on GraphQL, which this application does not serve. See

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

- The error envelope is a superset of GitHub's: `message` and `errors` keep

  GitHub-compatible meaning, and `code`, `status`, `documentation_url`, and

  `request_id` are additions. GitHub's `errors` is an array of resource

(`projectsV2`). It mimics GitHub REST shapes as a compatibility aid and

implements only a subset of the real API. Authorization here comes from API

tokens with scopes such as `forge:write`; path similarity to GitHub proves

nothing about authorization.

nothing about authorization. **GitHub-shaped** is not **GitHub-compatible**:

the shape carries a client you configure with a base URL, and it does not

carry GitHub's `gh`, which is unsupported. `/api/v3` is a dated alias for

clients released before the rename, not a version this API claims. See

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

**GitHub contexts (`OpenAgents.GitHub`, `github_oauth`)** — code that talks

*to* GitHub: OAuth identity, delegated repository access. Tokens are

      "put /api/v1/repos/:owner/:repo/labels/:name" => {:required_bearer, :label, :envelope},

      "put /api/v1/repos/:owner/:repo/milestones/:milestone_number" =>

        {:required_bearer, :milestone, :envelope},

      # Landed at `/api/v3` while the rename was in flight. It moves with

      # everything else; the alias answers the prefix it was written against.

      # Landed under the old prefix while the rename was in flight. It moves

      # with everything else; the alias answers the prefix it was written

      # against until that alias goes away.

      "post /api/v1/traces" => {:required_bearer, :trace, :envelope}

    }

  end

defmodule OpenAgentsWeb.TraceController do

  @moduledoc """

  Accept ATIF v1 trace uploads at `POST /api/v3/traces`.

  Accept ATIF v1 trace uploads at `POST /api/v1/traces`.

  """

  use OpenAgentsWeb, :controller

  defp trace_view(trace) do

    %{

      "id" => trace.id,

      "url" => OpenAgentsWeb.Endpoint.url() <> "/api/v3/traces/" <> trace.id,

      "url" => OpenAgentsWeb.Endpoint.url() <> "/api/v1/traces/" <> trace.id,

      "digest" => trace.digest,

      "byte_size" => trace.byte_size,

      "visibility" => trace.visibility,

  @moduledoc """

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

  During the `/api/v3` to `/api/v1` migration, legacy clients continue to call

  `/api/v3/*`. This plug modifies `conn.path_info` so the router routes the

  request to the `/api/v1` scopes without requiring an HTTP redirect.

  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

with write access receives `403 Forbidden`, and an activity entry is never

editable. See [Projects](/docs/projects).

## Choose a client

The paths are GitHub-shaped so that you can adapt a client you already know.

They are not a promise that GitHub's own tooling runs against this host.

- **The `openagents` CLI** is the first-class client. It finds the API origin,

  loads your stored credential, and returns JSON. See

  [Call the API with the CLI](/docs/cli-api).

- **A client that takes a base URL** works on shape alone. Point Octokit at

  `https://openagents.com/api/v1` and the issue, comment, label, assignee,

  milestone, and project reads and writes described on this page behave as the

  paths suggest, within the limits below.

- **GitHub's `gh` CLI is not supported.** Its ported commands do not use REST:

  `gh issue list` sends a GraphQL query to `/api/graphql`, and `gh issue view`

  first probes `GET /api/v3/meta`. OpenAgents serves neither, so those commands

  fail whatever the base path is. The `gh api` passthrough does work if you

  give it a full URL, as in `gh api

  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`.

## Know the compatibility limits

- List responses use named envelopes such as `issues`, `comments`, `labels`,

  `milestones`, `assignees`, `projects`, `items`, and `fields`. GitHub commonly

  returns a bare array.

- Pagination, filters, link headers, and error envelopes form a bounded local

  contract. They do not provide complete Octokit or `gh` compatibility.

  contract. They do not provide complete Octokit compatibility, and `gh` is not

  a supported client at all.

- Ancillary issue-resource reads do not yet use the optional-bearer pipeline

  for private repositories.

- A nonnumeric issue or milestone number can produce `500 Internal Server

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.

  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.

  """

  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

    misversioned =

      OpenAgentsWeb.Router.__routes__()

      |> Enum.map(& &1.path)

      |> Enum.filter(&Regex.match?(~r{^/api/v\d}, &1))

      |> Enum.reject(&String.starts_with?(&1, "/api/v1"))

    assert misversioned == [], """

    These routes declare a version segment other than v1:

    #{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.

    """

  end

  test "the alias plug is the only file under lib/ that 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 == [], """

    These files name `/#{@legacy_prefix}`:

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

    A route, a rendered `url` field, or a receipt hint that names the alias

    breaks when the alias is deleted. Name `/api/v1`, which is what the router

    serves and what the alias rewrites to.

    """

  end

end

defmodule OpenAgentsWeb.TraceControllerTest do

  @moduledoc """

  Accept ATIF v1 trace uploads at `POST /api/v3/traces`.

  Accept ATIF v1 trace uploads at `POST /api/v1/traces`.

  """

  use OpenAgentsWeb.ConnCase, async: false

  alias OpenAgents.Repo

  alias OpenAgents.Traces.Trace

  describe "POST /api/v3/traces" do

  describe "POST /api/v1/traces" do

    test "returns the trace id and url for a valid ATIF v1.7 document", %{conn: conn} do

      body =

        conn

        |> put_chat_api_token("trace-valid")

        |> post(~p"/api/v3/traces", %{

        |> post(~p"/api/v1/traces", %{

          "schema_version" => "ATIF/1.7",

          "trace" => %{"events" => [%{"type" => "step"}]}

        })

      assert %{"id" => id, "url" => url} = body

      assert is_binary(id)

      assert url =~ "/api/v3/traces/#{id}"

      assert url =~ "/api/v1/traces/#{id}"

      assert body["visibility"] == "dark"

      assert is_integer(body["byte_size"])

      assert is_binary(body["digest"])

      first =

        conn

        |> put_chat_api_token("trace-dedup")

        |> post(~p"/api/v3/traces", document)

        |> post(~p"/api/v1/traces", document)

        |> json_response(201)

      second =

        conn

        |> put_chat_api_token("trace-dedup")

        |> post(~p"/api/v3/traces", document)

        |> post(~p"/api/v1/traces", document)

        |> json_response(200)

      assert second["id"] == first["id"]

      body =

        conn

        |> put_chat_api_token("trace-oversize")

        |> post(~p"/api/v3/traces", %{

        |> post(~p"/api/v1/traces", %{

          "schema_version" => "ATIF/1.7",

          "data" => big

        })

    test "rejects an unauthenticated call", %{conn: conn} do

      conn

      |> post(~p"/api/v3/traces", %{"schema_version" => "ATIF/1.7"})

      |> post(~p"/api/v1/traces", %{"schema_version" => "ATIF/1.7"})

      |> assert_api_error(401, "unauthenticated")

    end

      conn =

        conn

        |> put_chat_api_token("trace-invalid")

        |> post(~p"/api/v3/traces", %{"schema_version" => "ATIF/2.0"})

        |> post(~p"/api/v1/traces", %{"schema_version" => "ATIF/2.0"})

      assert_api_error(conn, 422, "validation_failed",

        errors: %{"document" => ["The document is not a valid ATIF v1 object."]}

      conn =

        conn

        |> put_chat_api_token("trace-no-version")

        |> post(~p"/api/v3/traces", %{"trace" => %{}})

        |> post(~p"/api/v1/traces", %{"trace" => %{}})

      assert_api_error(conn, 422, "validation_failed")

    end

      body =

        conn

        |> put_chat_api_token("trace-visibility")

        |> post("/api/v3/traces?visibility=ledger", %{

        |> post("/api/v1/traces?visibility=ledger", %{

          "schema_version" => "ATIF/1.7",

          "trace" => %{}

        })

      first =

        conn

        |> put_chat_api_token("trace-owner-one")

        |> post(~p"/api/v3/traces", document)

        |> post(~p"/api/v1/traces", document)

        |> json_response(201)

      second =

        conn

        |> put_chat_api_token("trace-owner-two")

        |> post(~p"/api/v3/traces", document)

        |> post(~p"/api/v1/traces", document)

        |> json_response(201)

      refute first["id"] == second["id"]