API Documentation

iForge provides a RESTful API and interactive API documentation.

Swagger UI

After starting the service, visit:

http://localhost:8081/swagger/

You can view all API endpoints, parameters, response formats in Swagger UI and test them directly.

Authentication Methods

The API supports two authentication methods:

Session Cookie

The browser automatically carries the session cookie after login, suitable for Web frontend calls.

Bearer Token

curl -H "Authorization: Bearer <token>" \
  http://localhost:8081/api/v1/user

Token is obtained through Personal Access Token:

1. Go to "Settings" → "Access Tokens"
2. Create a new token to get the token string
3. Use it in API request headers

Common Endpoints

Method	Path	Description
POST	/api/v1/auth/login	Login
POST	/api/v1/auth/register	Register
GET	/api/v1/user	Get current user
GET	/api/v1/repos	Repository list
POST	/api/v1/repos	Create repository
GET	/api/v1/repos/:owner/:repo	Repository details
GET	/api/v1/repos/:owner/:repo/issues	Issue list
POST	/api/v1/repos/:owner/:repo/issues	Create Issue
GET	/api/v1/repos/:owner/:repo/merge-requests	MR list
GET	/api/v1/notifications	Notification list
GET	/api/v1/ws	WebSocket connection

External Runner API

CI/CD external Runners use independent Bearer token authentication:

Method	Path	Description
POST	/api/v1/cicd/runner/register	Register Runner
POST	/api/v1/cicd/runner/jobs/claim	Claim Job
POST	/api/v1/cicd/runner/jobs/:id/logs	Upload logs
PUT	/api/v1/cicd/runner/jobs/:id/status	Update Job status

Rate Limiting

• General API: 100 requests/minute/user
• Unauthenticated requests are rate-limited by IP
• Runner API is not subject to general rate limiting