# Gitea API quick reference (v1.26.x)

Base URL: `$GITEA_URL/api/v1` (default `https://gitea-hjwh0svsoo9p5w5kj2j6b1bd.urieljareth.org/api/v1`).
Auth header: `Authorization: token <GITEA_TOKEN>` (also accepts `Bearer` on 1.16+).
Docs (Swagger): `$GITEA_URL/api/swagger` (browsable in a browser).

## Verified 2026-07-19 on this instance

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/version` | GET | Server version (anonymous). Returns `{"version":"1.26.2"}`. |
| `/user` | GET | Authenticated user. Proves token. |
| `/settings/api` | GET | Pagination/limits config. |
| `/repos/search?limit=50` | GET | All repos visible to the token. |
| `/repos/{owner}/{name}` | GET | Single repo (404 if missing or no access). |
| `/user/repos` | POST | Create repo under auth user. |
| `/orgs/{org}/repos` | POST | Create repo under an org. |
| `/repos/{owner}/{name}` | PATCH | Update description, visibility, default branch. |
| `/repos/{owner}/{name}` | DELETE | Delete repo. |
| `/repos/{owner}/{name}/branches` | GET | List branches. |
| `/repos/{owner}/{name}/branch protections` | POST | Branch protection rules. |
| `/repos/{owner}/{name}/releases` | GET/POST | List / create releases. |
| `/repos/{owner}/{name}/tags` | GET | List tags. |
| `/repos/{owner}/{name}/hooks` | GET/POST | Webhooks (e.g. Coolify pull). |
| `/repos/{owner}/{name}/mirror-sync` | POST | Sync a mirror repo. |
| `/repos/migrate` | POST | Migrate/mirror from GitHub/GitLab/etc. |
| `/users/{username}/tokens` | POST | Create a new app token (needs username+password or admin). |
| `/orgs` | GET | List orgs. |
| `/admin/users` | GET | List users (admin only). |

## Token scopes (Gitea 1.20+ fine-grained)

Tokens carry scopes. The current skill token (`GITEA_TOKEN` in `.env.local.ps1`)
needs at minimum: `read:repository`, `write:repository`, `read:user`. Create at
`$GITEA_URL/user/settings/applications` (or via API `/users/{user}/tokens` with
basic auth). Verify scopes with:

```powershell
.\gitea_skill\scripts\Test-GiteaConnection.ps1
```

## Auth header convention

Gitea's canonical header is `Authorization: token <T>` (note: literal `token`,
not `Bearer`). This differs from GitHub/Coolify. `Invoke-GiteaApi.ps1` uses the
canonical form. `Bearer` also works on 1.16+ but stick to `token` for max
compat.

## Git push with token (headless, no wincred)

The token is NOT persisted into `.git/config` by `Sync-GiteaRemote.ps1`. It is
sent via a one-shot `http.extraHeader`:

```powershell
git -c "http.extraHeader=Authorization: token $env:GITEA_TOKEN" `
    -c "credential.helper=" `
    push -u gitea main
```

If you prefer wincred (so plain `git push` works afterwards), seed it once:

```powershell
cmdkey /generic:"git:$env:GITEA_URL" /user:"$env:GITEA_USER" /pass:"$env:GITEA_TOKEN"
```

But note: the skill scripts do not require this. They work headlessly.