@@ -52,6 +52,31 @@ func (err HTTPError) ScopesSuggestion() string {
 	return err.scopesSuggestion
 }
 
+// RequestOption configures a single request made through Request, RequestWithContext or GraphQL.
+type RequestOption func(*requestConfig)
+
+// requestConfig accumulates the effect of the RequestOptions applied to one request.
+type requestConfig struct {
+	endpointScopes string
+}
+
+// WithEndpointScopes adds OAuth scopes to a 4xx error as if the server endpoint had returned them.
+// This improves error messaging for endpoints that do not explicitly list the scopes they need, and
+// is the Request equivalent of calling EndpointNeedsScopes on a raw response.
+func WithEndpointScopes(scopes string) RequestOption {
+	return func(cfg *requestConfig) {
+		cfg.endpointScopes = scopes
+	}
+}
+
+func newRequestConfig(opts []RequestOption) requestConfig {
+	cfg := requestConfig{}
+	for _, opt := range opts {
+		opt(&cfg)
+	}
+	return cfg
+}
+
 // GraphQL performs a GraphQL request using the query string and parses the response into data receiver. If there are errors in the response,
 // GraphQLError will be returned, but the receiver will also be partially populated.
 func (c Client) GraphQL(hostname string, query string, variables map[string]any, data any) error {
@@ -150,8 +175,8 @@ func (c Client) RESTWithNext(hostname string, method string, p string, body io.R
 // Request performs a REST request and returns the response for the caller to consume.
 //
 // See RequestWithContext for the full semantics.
-func (c Client) Request(hostname string, method string, p string, body io.Reader) (*http.Response, error) {
-	return c.RequestWithContext(context.Background(), hostname, method, p, body)
+func (c Client) Request(hostname string, method string, p string, body io.Reader, opts ...RequestOption) (*http.Response, error) {
+	return c.RequestWithContext(context.Background(), hostname, method, p, body, opts...)
 }
 
 // RequestWithContext performs a REST request and returns the response for the caller to consume,
@@ -165,15 +190,17 @@ func (c Client) Request(hostname string, method string, p string, body io.Reader
 //
 // Responses outside the 2xx range are returned as an HTTPError and their body is closed. On success
 // the response is returned unread and the caller is responsible for closing its body.
-func (c Client) RequestWithContext(ctx context.Context, hostname string, method string, p string, body io.Reader) (*http.Response, error) {
+func (c Client) RequestWithContext(ctx context.Context, hostname string, method string, p string, body io.Reader, opts ...RequestOption) (*http.Response, error) {
+	cfg := newRequestConfig(opts)
+
 	restClient, err := ghAPI.NewRESTClient(clientOptions(hostname, c.http.Transport))
 	if err != nil {
 		return nil, err
 	}
 
 	resp, err := restClient.RequestWithContext(ctx, method, p, body)
 	if err != nil {
-		return nil, handleResponse(err)
+		return nil, handleRequestError(err, cfg.endpointScopes)
 	}
 
 	return resp, nil
@@ -199,6 +226,21 @@ func UnexpectedStatusError(resp *http.Response) error {
 	return fmt.Errorf("unexpected HTTP %d", resp.StatusCode)
 }
 
+// handleRequestError converts a request error into an HTTPError or GraphQLError, first adding any
+// endpoint scopes to the error's headers so that the scopes suggestion generated by handleResponse
+// accounts for them. This is the error-path equivalent of calling EndpointNeedsScopes on a response
+// before HandleHTTPError, which call sites can no longer do when the response never reaches them.
+func handleRequestError(err error, endpointScopes string) error {
+	if endpointScopes != "" {
+		var restErr *ghAPI.HTTPError
+		if errors.As(err, &restErr) && restErr.Headers != nil && restErr.StatusCode >= 400 && restErr.StatusCode < 500 {
+			oldScopes := restErr.Headers.Get("X-Accepted-Oauth-Scopes")
+			restErr.Headers.Set("X-Accepted-Oauth-Scopes", fmt.Sprintf("%s, %s", oldScopes, endpointScopes))
+		}
+	}
+	return handleResponse(err)
+}
+
 // handleResponse takes a ghAPI.HTTPError or ghAPI.GraphQLError and converts it into an
 // HTTPError or GraphQLError respectively.
 func handleResponse(err error) error {
 
@@ -154,8 +154,73 @@ func TestRequestErrorPreservesScopesSuggestion(t *testing.T) {
 
 // Call sites used to mutate the response with EndpointNeedsScopes before converting it to an error.
 // Request converts internally, so WithEndpointScopes has to reproduce that suggestion.
+func TestRequestWithEndpointScopes(t *testing.T) {
+	tests := []struct {
+		name           string
+		statusCode     int
+		acceptedScopes string
+		wantSuggestion string
+	}{
+		{
+			name:           "adds scopes the endpoint did not report",
+			statusCode:     403,
+			acceptedScopes: "",
+			wantSuggestion: "delete_repo",
+		},
+		{
+			name:           "appends to scopes the endpoint did report",
+			statusCode:     403,
+			acceptedScopes: "repo",
+			wantSuggestion: "delete_repo",
+		},
+		{
+			name:           "leaves 5xx errors alone",
+			statusCode:     500,
+			acceptedScopes: "",
+			wantSuggestion: "",
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			reg := &httpmock.Registry{}
+			defer reg.Verify(t)
+			client := newTestClient(reg)
+
+			reg.Register(httpmock.MatchAny, func(req *http.Request) (*http.Response, error) {
+				header := map[string][]string{
+					"Content-Type":   {"application/json; charset=utf-8"},
+					"X-Oauth-Scopes": {"repo"},
+				}
+				if tt.acceptedScopes != "" {
+					header["X-Accepted-Oauth-Scopes"] = []string{tt.acceptedScopes}
+				}
+				return &http.Response{
+					Request:    req,
+					StatusCode: tt.statusCode,
+					Body:       io.NopCloser(bytes.NewBufferString(`{"message": "Forbidden"}`)),
+					Header:     header,
+				}, nil
+			})
+
+			_, err := client.Request("github.com", http.MethodDelete, "repos/OWNER/REPO", nil,
+				WithEndpointScopes("delete_repo"))
+
+			var httpErr HTTPError
+			require.ErrorAs(t, err, &httpErr)
+			if tt.wantSuggestion == "" {
+				assert.Empty(t, httpErr.ScopesSuggestion())
+			} else {
+				assert.Contains(t, httpErr.ScopesSuggestion(), tt.wantSuggestion)
+			}
+		})
+	}
+}
+
 type ctxKey struct{}
 
+// Call sites such as release asset upload run inside a retry loop that owns a context, so the
+// context has to reach the outgoing request.
 func TestRequestWithContextPropagatesContext(t *testing.T) {
 	reg := &httpmock.Registry{}
 	defer reg.Verify(t)
 
@@ -209,36 +209,37 @@ $ curl --cacert /tmp/ca.pem --resolve gh-gateway.internal:8443:127.0.0.1 \
 
 ## Current state
 
-Phases 1, 2 and 3 pass, unchanged. That is the main thing this commit had to
-show: a dozen call sites changed how they make requests, and nothing that
-already worked stopped working.
+Phases 1, 2 and 3 pass, unchanged.
 
-10 scripts are still red, but four of them now pass their entire body and fail
-only in deferred `gh repo delete` cleanup:
+`gist-create-view-delete` is green. It is the only script whose cleanup is
+`gh gist delete` rather than `gh repo delete`, which is why it can go green on
+its own while the rest cannot.
+
+Nine scripts are still red, and the count overstates how much is broken. Five
+fail in their body, on a call site that is genuinely still unrouted. The other
+four pass their body in full and fail only in deferred cleanup:
 
 | Script | Fails at |
 |---|---|
-| `repo-read-file` | `gh repo read-file` |
-| `extension` | `gh repo edit --add-topic` |
-| `search-issues` | `gh search issues` |
-| `auth-status` | scope checking |
-| `gist-create-view-delete` | `gh gist create` |
-| `repo-delete` | `gh repo delete` |
+| `repo-delete` | `gh repo delete`, line 9 |
+| `auth-status` | scope checking, line 2 |
+| `repo-read-file` | `gh repo read-file`, line 34 |
+| `extension` | `gh repo edit --add-topic`, line 29 |
+| `search-issues` | `gh search issues`, line 21 |
 | `release-upload-download`, `repo-list-rename`, `repo-rename-transfer-ownership`, `run-download` | nothing in the body; cleanup only |
 
-`release-upload-download` joining that group is worth understanding, because it
-was not migrated by this commit. Uploads and downloads use the `upload_url` and
-asset URLs that the API itself returns, and now that the release is *created*
-through the gateway those URLs already point at the gateway. Routing propagates
-through response bodies, so fixing one call site can fix its dependents for
-free.
+Almost every script creates a repository and defers `gh repo delete`, so until
+that one call site is routed those four cannot report anything but red, however
+much of their own subject matter works. Script colour is a poor measure of
+progress on its own: read the step list above the failure, which shows how far
+the body got, and the `.txtar:NN` line, which says whether the failure is the
+script's subject or its cleanup.
 
 ## Remaining
 
-`gh repo read-file`, `gh repo edit`, `gh search issues`, `gh auth status`, `gh
-gist create` and `gh repo delete`. Each is blocked on a capability the shared
-client does not have yet: per-request headers, endpoint scopes, or control over
-redirects.
+`gh repo delete`, which needs control over redirects, and `gh auth status`,
+`gh repo read-file`, `gh repo edit` and `gh search issues`, which need
+per-request headers.
 
 ## Transcript
 
@@ -276,8 +277,8 @@ PHASE  RESULT   NAME
 4      FAIL     extension.txtar
 4      FAIL     search-issues.txtar
 4      FAIL     auth-status.txtar
-5      FAIL     gist-create-view-delete.txtar
+5      PASS     gist-create-view-delete.txtar
 
 == Summary
-10 subset script(s) red: release-upload-download.txtar repo-delete.txtar repo-list-rename.txtar repo-read-file.txtar repo-rename-transfer-ownership.txtar run-download.txtar extension.txtar search-issues.txtar auth-status.txtar gist-create-view-delete.txtar
+9 subset script(s) red: release-upload-download.txtar repo-delete.txtar repo-list-rename.txtar repo-read-file.txtar repo-rename-transfer-ownership.txtar run-download.txtar extension.txtar search-issues.txtar auth-status.txtar
 ```
@@ -73,9 +73,14 @@ report an error.
 ## Known gaps
 
 `api_host` is not yet honoured centrally. It works for requests that go through
-go-gh's client, and for `gh api`, but many call sites still build absolute
+go-gh's client, and for `gh api`, but some call sites still build absolute
 `api.github.com` URLs and never reach the gateway at all.
 
+Those call sites are being migrated a capability at a time, because each one
+built its own request for a reason. Endpoint scopes were one such reason and
+are now expressible; per-request headers and control over redirects are not
+yet.
+
 `gh api` is a wart worth naming. It does not use go-gh's client, so it resolves
 `api_host` itself with a second implementation of the same rule. Two
 implementations of "where does this request go" is exactly the shape of problem
 
@@ -17,7 +17,6 @@ import (
 	"github.com/cli/cli/v2/api"
 	"github.com/cli/cli/v2/internal/browser"
 	"github.com/cli/cli/v2/internal/gh"
-	"github.com/cli/cli/v2/internal/ghinstance"
 	"github.com/cli/cli/v2/internal/safeurl"
 	"github.com/cli/cli/v2/internal/text"
 	"github.com/cli/cli/v2/pkg/cmd/gist/shared"
@@ -273,27 +272,23 @@ func createGist(client *http.Client, hostname, description string, public bool,
 		return nil, err
 	}
 
-	u, err := safeurl.JoinPathWithHostPrefix(ghinstance.RESTPrefix(hostname), "gists")
+	path, err := safeurl.JoinPath("gists")
 	if err != nil {
 		return nil, err
 	}
-	req, err := http.NewRequest(http.MethodPost, u.String(), requestBody)
-	if err != nil {
-		return nil, err
-	}
-	req.Header.Set("Content-Type", "application/json; charset=utf-8")
 
-	resp, err := client.Do(req)
+	// The Content-Type this site used to set explicitly is the one the client already sends,
+	// so it is no longer stated here.
+	// TODO(api-client-rollout)
+	// This line of code is part of a mechanical roll out of the api client.
+	// As a follow up, consider whether the api client can be injected to this call site, rather than constructed
+	resp, err := api.NewClientFromHTTP(client).Request(hostname, http.MethodPost, path.String(), requestBody,
+		api.WithEndpointScopes("gist"))
 	if err != nil {
 		return nil, err
 	}
 	defer resp.Body.Close()
 
-	if resp.StatusCode > 299 {
-		api.EndpointNeedsScopes(resp, "gist")
-		return nil, api.HandleHTTPError(resp)
-	}
-
 	result := &shared.Gist{}
 	dec := json.NewDecoder(resp.Body)
 	if err := dec.Decode(result); err != nil {
 
@@ -11,6 +11,7 @@ import (
 	"testing"
 
 	"github.com/MakeNowJust/heredoc"
+	"github.com/cli/cli/v2/api"
 	"github.com/cli/cli/v2/internal/browser"
 	"github.com/cli/cli/v2/internal/config"
 	"github.com/cli/cli/v2/internal/gh"
@@ -21,6 +22,7 @@ import (
 	"github.com/cli/cli/v2/pkg/iostreams"
 	"github.com/google/shlex"
 	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
 )
 
 func Test_processFiles(t *testing.T) {
@@ -415,3 +417,32 @@ func Test_detectEmptyFiles(t *testing.T) {
 		assert.Equal(t, tt.isEmptyFile, isEmptyFile)
 	}
 }
+
+// Test_createGist_missingScope pins the scopes suggestion, which is the reason this call site
+// declares the gist scope rather than relying on what the API reports.
+func Test_createGist_missingScope(t *testing.T) {
+	reg := &httpmock.Registry{}
+	defer reg.Verify(t)
+
+	reg.Register(
+		httpmock.REST("POST", "gists"),
+		func(req *http.Request) (*http.Response, error) {
+			resp, err := httpmock.StatusJSONResponse(404, map[string]string{"message": "Not Found"})(req)
+			if err != nil {
+				return nil, err
+			}
+			resp.Header.Set("X-Oauth-Scopes", "repo")
+			resp.Header.Set("X-Accepted-Oauth-Scopes", "")
+			return resp, nil
+		},
+	)
+
+	_, err := createGist(&http.Client{Transport: reg}, "github.com", "", true, map[string]*shared.GistFile{
+		"file.txt": {Filename: "file.txt", Content: "hello"},
+	})
+	require.Error(t, err)
+
+	var httpErr api.HTTPError
+	require.ErrorAs(t, err, &httpErr)
+	assert.Contains(t, httpErr.ScopesSuggestion(), "gist")
+}