API reference

Contract-style reference for KilatKoding endpoints, including public routes, logged-in user routes, admin routes, AI routes, and webhooks.

The payload examples on this page are simplified for readability. Some routes also add rate-limit headers such as X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset.

Endpoint summary

Group	Main endpoints
Public	POST /api/contact, POST /api/waitlist, GET /api/health
Logged-in user	POST /api/payments, POST /api/subscription, POST /api/profile, POST /api/profile/avatar
Admin	POST /api/admin/users/role
AI	POST /api/ai/chat, POST /api/ai/generate
Provider callback	POST /api/webhooks/midtrans, POST /api/webhooks/doku

Public endpoints

POST /api/contact

Property	Value
Auth	No login required
Feature gate	Contact feature must be active
Rate limit	5 requests per hour per IP
Purpose	Send a contact-form message through Resend

Request body:

{
  "name": "Galang",
  "email": "[e-mail]",
  "message": "Hi, I want a demo."
}

Success response:

{
  "success": true
}

Common responses:

Status	When it happens
400	Required fields are missing or the email is invalid
429	Contact rate limit is exceeded
503	The contact feature is not active or env is incomplete
500	Resend fails to send the email

POST /api/waitlist

Property	Value
Auth	No login required
Feature gate	Waitlist feature must be active
Rate limit	5 requests per hour per IP
Purpose	Save a lead into the waitlist table

Request body:

{
  "email": "[e-mail]",
  "name": "Galang"
}

Success response:

{
  "success": true
}

Common responses:

Status	When it happens
400	The email is invalid
409	The email is already registered
429	The waitlist rate limit is exceeded
503	The waitlist feature is not active or env is incomplete
500	Database insert fails

GET /api/health

Property	Value
Auth	No login required
Purpose	Check feature readiness and database availability

Core response shape:

{
  "status": "ok",
  "payment_provider": "doku",
  "checks": {
    "supabase_public": true,
    "supabase_service_role": true,
    "resend": true
  },
  "database": {
    "ok": true,
    "latency_ms": 24
  }
}

Notes:

• it returns 200 when active features are healthy,
• it returns 503 when an active feature is still missing required config or the database check fails,
• the response also includes a per-feature map with enabled, missing_env, and disabled_by_flag.

Logged-in user endpoints

POST /api/payments

Property	Value
Auth	Login required
Feature gate	Payments must be active and ready
Rate limit	5 requests per 15 minutes per user
Purpose	Create a pending payment and start the provider checkout session

Request body:

{
  "plan": "PRO"
}

Midtrans success response:

{
  "provider": "midtrans",
  "token": "snap-token",
  "orderId": "KK-1742360000000-AB12CD34"
}

Doku success response:

{
  "provider": "doku",
  "payment_url": "https://sandbox.doku.com/...",
  "orderId": "KK-1742360000000-AB12CD34"
}

Common responses:

Status	When it happens
400	plan is invalid or unavailable
401	The user is not logged in
429	Payment rate limit is exceeded
503	The payments feature is not ready or the provider is not configured
500	The payment record cannot be created

POST /api/subscription

Property	Value
Auth	Login required
Purpose	Cancel or resume the active subscription

Request body:

{
  "action": "cancel"
}

Valid values:

• cancel
• resume

Success response:

{
  "success": true,
  "status": "cancel_at_period_end"
}

Or:

{
  "success": true,
  "status": "active"
}

Common responses:

Status	When it happens
400	The action value is invalid
401	The user is not logged in
503	Server-side billing configuration is not ready

POST /api/profile

Property	Value
Auth	Login required
Purpose	Save full name and avatar references for the current user

Request body:

{
  "full_name": "Galang Pratama",
  "avatar_path": "user-id/avatar",
  "avatar_url": "https://signed-url.example.com/avatar"
}

Success response:

{
  "success": true,
  "profile": {
    "full_name": "Galang Pratama",
    "avatar_path": "user-id/avatar",
    "avatar_url": "https://signed-url.example.com/avatar"
  }
}

Common responses:

Status	When it happens
400	The profile body is invalid
401	The user is not logged in
500	The profile update fails
503	Server-side write configuration is not ready

POST /api/profile/avatar

Property	Value
Auth	Login required
Feature gate	Auth must be active
Purpose	Create a signed upload URL for avatars

Request body:

{
  "fileSize": 180000,
  "fileType": "image/png"
}

Success response:

{
  "bucket": "avatars",
  "path": "user-id/avatar",
  "token": "signed-upload-token"
}

Common responses:

Status	When it happens
400	The file is larger than 2 MB or the MIME type is unsupported
401	The user is not logged in
500	The signed upload URL cannot be created
503	The auth feature is not available

Admin endpoint

POST /api/admin/users/role

Property	Value
Auth	Login required
Authorization	admin role required
Purpose	Change a user’s role to admin or member

Request body:

{
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "role": "admin"
}

Success response:

{
  "success": true,
  "user_id": "550e8400-e29b-41d4-a716-446655440000",
  "role": "admin"
}

Common responses:

Status	When it happens
400	The body is invalid or an admin tries to demote their own account
401	The user is not logged in
403	The user is logged in but is not an admin
500	The role update fails
503	The admin feature is not ready server-side

AI endpoints

POST /api/ai/chat

Property	Value
Auth	Login required
Rate limit	Based on the user’s plan, per 5 minutes
Purpose	Stream AI chat responses

Request body:

{
  "provider": "openai",
  "messages": [
    {
      "role": "user",
      "content": "Help me summarize this brief."
    }
  ]
}

Success behavior:

• returns a UI message stream rather than a plain JSON object,
• usage is tracked after the stream finishes.

Common responses:

Status	When it happens
400	messages is missing
401	The user is not logged in
429	Request rate limit or monthly usage limit is exceeded
503	The AI provider is not configured

POST /api/ai/generate

Property	Value
Auth	Login required
Rate limit	Based on the user’s plan, per 5 minutes
Purpose	Generate one-off text output

Request body:

{
  "provider": "openai",
  "prompt": "Write a short product description",
  "system": "Use a formal tone"
}

Success response:

{
  "text": "Generated output...",
  "usage": {
    "inputTokens": 20,
    "outputTokens": 120
  }
}

Common responses:

Status	When it happens
400	prompt is missing
401	The user is not logged in
429	Request rate limit or monthly usage limit is exceeded
503	The AI provider is not configured

Provider webhook endpoints

POST /api/webhooks/midtrans

Use this endpoint as a Midtrans callback, not as a browser-facing route.

Verified fields:

• order_id
• status_code
• gross_amount
• signature_key
• transaction_status

Important behavior:

• invalid signature returns 401,
• invalid payload returns 400,
• missing payment record returns 404,
• duplicate delivery can return { "received": true, "duplicate": true },
• valid events update payments, may activate subscriptions, and write into webhook_events and audit_logs.

POST /api/webhooks/doku

Use this endpoint as a Doku JOKUL callback, not as a browser-facing route.

Verified fields:

• order.invoice_number
• order.amount
• transaction.status
• transaction.original_request_id
• security.check_word

Important behavior:

• invalid signature returns 401,
• invalid payload returns 400,
• missing payment record returns 404,
• duplicate delivery is traceable through webhook_events,
• valid events update payments, may activate subscriptions, and write an audit trail.

/auth/confirm is an auth callback route, not an /api endpoint. To understand where it fits in login, OTP, and OAuth flows, read End-to-end flows.