2.8 KiB
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:
.\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:
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:
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.