48 lines
2.1 KiB
Markdown
48 lines
2.1 KiB
Markdown
# 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 one audit event.
|
|
- 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 event 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.
|