API Overview

Forgexa provides a RESTful API built with FastAPI.

Base URL

Environment	URL
Production (Forgexa Cloud)	https://api.forgexa.net/api/v1
Self-hosted	http://<your-server>:8000/api/v1
Local development	http://localhost:8000/api/v1

Authentication

All API endpoints (except /auth/login and /auth/register) require authentication via one of:

• JWT Bearer Token — obtained from /auth/login, expires after 24 hours
• Personal Access Token (PAT) — created via /users/me/api-tokens, suitable for CI/CD and scripts

# Login (JWT)
curl -X POST https://api.forgexa.net/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "admin@example.com", "password": "admin123"}'

# Response: { "access_token": "eyJ...", "token_type": "bearer" }

# Use JWT token
curl https://api.forgexa.net/api/v1/workspaces \
  -H "Authorization: Bearer eyJ..."

# Or use PAT
curl https://api.forgexa.net/api/v1/workspaces \
  -H "Authorization: Bearer pat_a1b2c3..."

Interactive Docs

FastAPI provides interactive documentation on self-hosted instances:

• Swagger UI: http://<your-server>:8000/docs
• ReDoc: http://<your-server>:8000/redoc

For local development, use http://localhost:8000/docs.

API Sections

• Authentication — Login, register, token management
• Organizations — Organization CRUD, members, budgets, audit logs
• Organization Invitations — Invite users to organizations
• Organization Integrations — Org-level integration configs
• Workspaces — Workspace CRUD, members, settings
• Projects — Project CRUD
• Requirements — Requirement management + AI analysis
• Executions — Execution lifecycle management
• Roles & Permissions — RBAC and custom roles
• API Tokens — Personal access token management
• Admin Dashboard — Platform admin statistics and audit logs

Common Response Patterns

Success

{
  "id": "uuid",
  "name": "...",
  "status": "...",
  "created_at": "2026-01-01T00:00:00Z"
}

Error

{
  "detail": "Error message"
}

Pagination

Most list endpoints return arrays directly. Audit logs and other large datasets use paginated responses:

{
  "total": 150,
  "page": 1,
  "page_size": 20,
  "items": [...]
}

Filtering is done via query parameters (page, page_size, action, start_date, etc.).