API reference
The REST API at https://api.microsaas.app creates, lists, stops and deletes disposable services. This page is the read-only reference, generated from the API's own OpenAPI document, version 0.1.0.
Sign in to try it in the sandbox
The reference below cannot send requests. The sandbox needs a login. Command line tool and MCP server | OpenAPI JSON
Which endpoints exist?
37 operations. Authenticated calls send a bearer API key.
| Method | Path | Summary |
|---|---|---|
| GET | /healthz | Liveness plus reconciler freshness (for the status page) |
| GET | /openapi.json | This document |
| GET | /v1/account | Tenant and caller scope |
| GET | /v1/audit | Audit trail for the tenant (operators: all entries, including reconciler actions) |
| GET | /v1/auth/github/callback | Verify state, exchange the code, upsert user and personal tenant, set the session cookie, 302 to the console /profile (or /login?error=...) |
| GET | /v1/auth/github/start | 302 to the GitHub authorize page (PKCE, 10 minute state); optional return_to on the console origin |
| POST | /v1/auth/logout | End the session and clear the cookie (needs X-MSAAS-CSRF) |
| POST | /v1/auth/oidc/github | Exchange a GitHub Actions OIDC JWT (audience microsaas) for a 15-minute deploy-scope token for the tenant a trust rule maps the repository/ref/environment to; never admin. Every failure is the same 403 oidc_denied; 404 unless OIDC trust is configured |
| GET | /v1/auth/session | Is the cookie session valid; returns expires_at and the per-session CSRF token |
| POST | /v1/billing/checkout | Start a subscription checkout for a plan and interval; returns the hosted checkout URL. 501 unless configured |
| POST | /v1/billing/topup | x402 prepaid top-up. Without X-PAYMENT: 402 with the payment requirements (x402Version, accepts[]). With X-PAYMENT: settles through the facilitator and credits once. 501 unless configured |
| POST | /v1/billing/x402 | Same settlement as /v1/billing/topup for a client that already holds an X-PAYMENT header (400 payment_missing without it) |
| GET | /v1/catalogue | List deployable services |
| GET | /v1/catalogue/{id} | Full contract of one service: resources, ports, generated secrets, config keys (env, type, default, range, settable), config files and the service's own API |
| GET | /v1/keys | List this tenant's active API keys (id, scope, label, created); the secret is never returned after creation |
| POST | /v1/keys | Create an API key for this tenant |
| DELETE | /v1/keys/{id} | Revoke an API key |
| DELETE | /v1/me | Start account deletion: revoke tokens and sessions, schedule service deletion (session only) |
| GET | /v1/me | Profile and personal tenant |
| PATCH | /v1/me | Update display_name and notification_email (null clears) |
| POST | /v1/sandbox/token | Mint a one-hour token for the docs sandbox (session + CSRF, or a user access token); 10 per minute |
| GET | /v1/services | List the tenant's services |
| POST | /v1/services | Provision a service (async, 202); budget and quota checked |
| GET | /v1/services/metrics | Runtime counters of the tenant's running services in one call (at most 20, oldest first; truncated is true beyond that). Each item carries metrics (same fields as one service) or, when the platform call failed, error {error, code} while the others still answer |
| DELETE | /v1/services/{id} | Delete a service and its volume (async) |
| GET | /v1/services/{id} | Get one service |
| POST | /v1/services/{id}/extend | Lengthen a service's lifetime by whole hours, up to the plan's maximum TTL |
| GET | /v1/services/{id}/logs | Newest log lines of one service (query tail, 1..=1000, default 100); bearer tokens, platform token formats and the service's own secrets are redacted |
| GET | /v1/services/{id}/metrics | Runtime counters of one service: state, cpu_time_ms, rss_bytes, rx_bytes, tx_bytes and uptime_ms (since the last boot, null when not reported) |
| POST | /v1/services/{id}/start | Start a stopped service |
| POST | /v1/services/{id}/stop | Stop a running service (volume kept, still billed) |
| GET | /v1/tokens | List access tokens (never the secret) |
| POST | /v1/tokens | Create an access token; the secret is returned once |
| DELETE | /v1/tokens/{id} | Revoke a token immediately |
| POST | /v1/tokens/{id}/rotate | New secret with the same name, scopes and lifetime; the old token is revoked |
| GET | /v1/usage | Usage ledger and balance; query from, to (unix seconds) |
| POST | /v1/webhooks/paddle | Payment provider webhook (raw body, Paddle-Signature header; the signature is the only credential). 404 unless Paddle is configured; 400 bad signature or event; replays answer duplicate |
Full reference
Request and response schemas, parameters and status codes. This section needs JavaScript; the table above and the OpenAPI JSON do not.
Which services use a standard protocol?
Services that speak an existing standard are used with that standard's own clients and documentation, so they have no separate API reference here.
- Object storage (S3): Amazon S3 API reference
- Messaging (NATS): NATS documentation
- SurrealDB: SurrealDB documentation
Last updated