Commercial and advanced API additions
Authenticated routes below are relative to /v1. Use the existing opaque-session authentication boundary; browser requests use the same-origin dashboard BFF. Organization membership is always checked. JSON uses snake_case. Errors use the existing API error response. Unknown fields are rejected. UUIDs and application ownership are validated server-side.
| Method and route | Access / request |
|---|---|
GET /billing/plans | Authenticated; public catalog metadata and configured checkout providers only |
GET /admin/billing/plans | Platform super_admin; includes editable native plan configuration |
POST /admin/billing/plans | Platform super_admin; {id,amount,currency,paystack_plan,paypal_plan,enabled,server_limit}; amount is integer minor units, native plans validated before enabling |
GET /organizations/{id}/billing | Owner/admin; current subscription, ten recent checkouts, fifty recent payments |
POST /organizations/{id}/billing/checkout | Owner/admin; {plan:"pro" or "business",provider:"paystack" or "paypal",consent_recurring:true}; returns approved hosted checkout URL |
POST /organizations/{id}/billing/verify | Owner/admin; {checkout_id:UUID}; reads native provider state |
POST /organizations/{id}/billing/cancel | Owner/admin; {confirm:true}; cancels future native recurrence |
GET /organizations/{id}/invoices | Owner/admin; up to 100 immutable payment receipts |
GET /organizations/{id}/domains | Owner/admin; domains, recent orders, configuration readiness; excludes registrant data and transfer secrets |
POST /organizations/{id}/domain-quotes | Owner/admin; {name,operation:"register" or "renew" or "transfer"}; provider quote with ten-minute validity |
POST /organizations/{id}/domains | Owner/admin; {name}; returns one-time TXT ownership challenge |
POST /organizations/{id}/domain-orders | Owner/admin; {quote_id,domain_id?,nameservers:[...],auth_code?,confirm:true}; requires verified registry profile |
POST /organizations/{id}/domain-actions | Owner/admin; action and IDs as below |
GET /catalog/applications | Authenticated; compiled recipes and operator-approved image availability |
GET /catalog/models | Authenticated; bounded private model catalog |
POST /organizations/{id}/template-applications | Owner/admin/developer; {name,server_id,template,env:{KEY:"value"},memory_mb?}; dispatches real deployment |
GET /organizations/{id}/models | Member; catalog runtime inventory and observation state |
POST /organizations/{id}/model-jobs | Owner/admin/developer; {application_id,model,action:"pull" or "start" or "stop" or "remove",confirm:true} |
GET /organizations/{id}/backups | Member; verified immutable snapshots |
POST /organizations/{id}/backup-jobs | Owner/admin/developer; {application_id,slot,action:"backup" or "restore",backup_id?,confirm:true}; paid feature when limits enforced |
GET /organizations/{id}/advanced-jobs | Member; bounded job/result history |
GET /organizations/{id}/metrics | Member; current snapshot and historical samples; paid feature when limits enforced |
Domain actions: verify_ownership, rotate_challenge, bind, refresh, nameservers, auto_renew use domain_id; checkout, verify_payment, execute use operation_id. bind also needs application_id; nameserver changes use nameservers; auto-renew uses enabled; checkout uses provider. Binding, mutating registrar actions and execute require confirm:true. Consult services/api/domains.go for the exact bounded input struct. Execution is separate from payment verification so a paid request cannot silently purchase a domain.
The tunnel creation contract additionally accepts fallback_gateway_ids:[UUID,UUID] (optional, at most two distinct enabled gateways) alongside application_id, gateway_id and confirm_public:true. Revocation removes the whole hostname routing group.
Public API-ingress routes outside /v1: POST /webhooks/paystack, POST /webhooks/paypal require verified provider signatures; GET /metrics requires the dedicated operator bearer token. GET/POST /edge/v1/probes require a gateway's own bearer key and limit observations to assigned hosts/releases. Agent advanced claim/progress/result and model telemetry use signed server credentials under /agent/v1, not user sessions; see the typed protocol and router for the wire contract.
Provider success is never inferred from a browser redirect. Queued/running/succeeded/failed/unknown/expired jobs distinguish dispatch, verified completion and uncertain results. unknown is a reconciliation state, not a retry instruction. Restore success names a new recovery volume; it does not imply live application activation.