# Raw API tool: `gitea_api_request`

`gitea_api_request` sends one request to any Gitea API endpoint. It exists for endpoints that are
newer than the pinned Gitea 28.1.0 swagger, so a Gitea upgrade does not have to wait for a
catalog update. Prefer the generated tools whenever one exists: they have typed arguments, hints
and validation.

It is a hand-written tool, not part of the generated catalog, and belongs to the `misc` domain.
It is annotated as not read-only and destructive.

## Arguments

| Argument | Type | Rules |
|---|---|---|
| `method` | string | `GET`, `POST`, `PUT`, `PATCH` or `DELETE`. Required. |
| `path` | string | Required. Starts with `/`, relative to `/api/v1`, at most 2048 characters. |
| `query` | object | Optional. Values are strings, numbers, booleans or arrays of them. |
| `body` | any JSON | Optional request body. |
| `sudo` | string | Optional Gitea login to act as (site-admin tokens only), as for every tool. |

Unknown arguments are rejected. The path is checked: no empty, `.` or `..` segments, and no
backslash, `?`, `#`, `%` or control characters (put parameters in `query`). A body is never
logged or returned. The `token`, `access_token` and `sudo` query parameters are refused,
because credentials belong in the identity, not in the URL.

## Behaviour

- It goes through the same executor as every generated tool: the identity's token, no redirects,
  response limits, redaction and secret masking, the result envelope and the same audit entries (`tool_call_started`, then `tool_invocation`).
- There is no allow list of paths and no write classification: with full access, the token's
  scopes and the identity's Gitea permissions are the limit.
- `READ_ONLY=true` keeps the tool listed but it accepts only `GET`.
- `TOOLSETS` without `misc`, or `DISABLED_TOOLS=gitea_api_request`, removes it.
- The audit entry records the method and the path, so it is visible which endpoint was called.

## Example

```json
{
  "method": "GET",
  "path": "/repos/acme/app/issues",
  "query": {"state": "open", "limit": 10}
}
```

The result is the usual envelope, with `request.path` set to the path that was called and the
response under `data`. Content under `data` is untrusted, as everywhere.