API Reference

Base URL: https://universalforge-api.fly.dev

Auth

POST
/api/v1/auth/register

Create a new account

Body: { email, password, full_name? }

Public
POST
/api/v1/auth/login

Sign in with email and password

Body: { email, password }

Public
POST
/api/v1/auth/oauth

Sign in with OAuth provider

Body: { provider, code }

Public
POST
/api/v1/auth/refresh

Refresh access token

Body: { refresh_token }

Public
DELETE
/api/v1/auth/logout

Invalidate session

Body: { refresh_token }

POST
/api/v1/auth/forgot-password

Send password reset email

Body: { email }

Public
POST
/api/v1/auth/reset-password

Reset password with token

Body: { token, password }

Public
POST
/api/v1/auth/verify-email

Verify email address

Body: { token }

Public

Jobs

GET
/api/v1/jobs

List your conversion jobs

Query: status?, page?, limit?

POST
/api/v1/jobs

Create a new conversion job

Body: { source_type, target_type, file_id? }

GET
/api/v1/jobs/:id

Get job details and status

DELETE
/api/v1/jobs/:id

Cancel a pending job

POST
/api/v1/jobs/:id/retry

Retry a failed job

GET
/api/v1/jobs/:id/download

Download converted artifact

User

GET
/api/v1/user/profile

Get your profile

PATCH
/api/v1/user/profile

Update profile

Body: { full_name?, avatar_url? }

GET
/api/v1/user/credits

Get credit balance

PATCH
/api/v1/user/notification-preferences

Update notification settings

Body: { email_notifications?, ... }

DELETE
/api/v1/user/account

Delete your account

POST
/api/v1/auth/resend-verification

Resend verification email

Body: { email }

Public
POST
/api/v1/user/change-password

Change password

Body: { current_password, new_password }

Billing

GET
/api/v1/billing/gateways

List available payment gateways

Public
GET
/api/v1/billing/plans

List subscription plans

Public
POST
/api/v1/billing/webhook

Payment webhook receiver

Query: gateway=(stripe|paystack|flutterwave)

Public
POST
/api/v1/billing/checkout

Create subscription checkout

Body: { plan_id, gateway, success_url, cancel_url }

POST
/api/v1/billing/credit-packs/checkout

Purchase credit pack

Body: { credits, gateway, success_url, cancel_url }

GET
/api/v1/billing/portal

Get Stripe customer portal URL

GET
/api/v1/billing/verify

Verify payment status

Query: session_id?

Storage & Tools

POST
/api/v1/storage/upload

Upload a file for conversion

Body: multipart/form-data

POST
/api/v1/tools/scrape/start

Start async scrape, returns session_id to poll

Body: { url, ownership_confirmed }

GET
/api/v1/tools/scrape/progress/:sessionId

Poll scrape progress (% , stage, done, file_path)

Realtime

WS
/api/v1/jobs/:id/ws

WebSocket for live job updates

Query: token=

Public

Authentication

Most endpoints require a Bearer token sent via the Authorization header. Tokens are obtained from POST /api/v1/auth/login or POST /api/v1/auth/register. Include rate limiting headers: X-RateLimit-Remaining and X-RateLimit-Reset.

Webhooks

Payment webhooks from Stripe, Paystack, and Flutterwave are received at POST /api/v1/billing/webhook?gateway=stripe|paystack|flutterwave. Each gateway's signature is verified using the configured secret before processing.

Rate Limiting

Auth endpoints are rate-limited to 10 requests per 15 minutes per IP. General API rate limits are enforced via Redis. Exceeded limits return 429 Too Many Requests.