Explicit scope and lifetime
A credential is bound to one organization, brand and project, carries explicit scopes and has a chosen expiry. Issuance requires fresh authentication and the secret is shown once.
Developers
The API your dashboard already uses.
Hostingsurge is API-first: the customer dashboard talks to the same HTTP surface described here. Credentials are scoped to an organization, a brand and a project — never to the platform as a whole.
Credentials and scopes
API and MCP credentials are issued from the account key page, hashed at rest, and checked on every use against the authority you have right now.
Revocation is immediate
Removing someone from a team permanently revokes their credentials, and a password reset invalidates credentials issued earlier.
Every use is re-checked
Each transactional use intersects current membership, role and project grants and verifies user, brand and organization status, password version, expiry and revocation.
projects:readprojects:writedeployments:readdeployments:createdeployments:productiondomains:readdomains:writebackend:readbackend:writestorage:readstorage:writeagents:readagents:writewordpress:readwordpress:writebilling:readai:generate
These are the scopes defined at the credential boundary. A production deployment is separate from generic write access on purpose.
Endpoints that exist today
Enumerated from the routes in the current build. Nothing is listed here that the platform does not actually serve.
| Route | What it does | Authentication |
|---|---|---|
| GET /api/health | Liveness of the web runtime. Reads no configuration, database or provider state. | Public |
| GET /api/auth/session | Current session state for the browser. | Session cookie |
| POST /api/auth/{signup, login, verify, resend, reset-request, reset, logout, mfa-*} | Identity actions: registration, email verification, sign in, MFA, password reset. | Exact origin + JSON body |
| GET /api/projects | List the projects of one organization with their source preparation state. | Session cookie |
| POST /api/projects | Create a managed project (kind: static, app, wordpress, agent or import). | Session + exact origin |
| POST /api/project-builds | Admit an isolated build of one completed saved version. | Session + exact origin |
| GET /api/project-build | Build state and the artifact receipt (digest, bytes, entries, recipe, duration) for one saved version. | Session cookie |
| POST /api/builder-runs | Admit one AI builder run for a project from a description. | Session + exact origin |
| GET /api/builder-runs | Latest builder run state, repair rounds and generated file count for a project. | Session cookie |
| GET /api/source-history | Saved and pending source versions for a project, with bounded pagination. | Session cookie |
| GET /api/source-content | File tree (action=tree), one file (action=file) or a comparison of two saved versions (action=compare). | Session cookie |
| POST /api/source-versions | Save an edit or restore an older saved version — always as a new version. | Session + exact origin |
| GET /api/source-export | Download one saved version as a ZIP archive. | Session cookie |
| /api/teams/{action}, /api/credentials/{action}, /api/billing/{action} | Account actions: teams and memberships, credential issuance and revocation, orders and subscriptions. | Session + exact origin |
| POST /api/webhooks/stripe | Provider to platform webhook with signature verification over the raw request bytes. Not customer-facing. | Provider signature |
These routes are session-authenticated and bound to the exact browser origin. A public REST surface that accepts customer API keys is in development, and this page will list it when it exists.
Request conventions
The same boundary rules apply to every route above.
JSON bodies, bounded
Requests use application/json, are capped at 16 KiB and have a five-second body deadline. Oversized or malformed input is refused before any work starts.
Origin-bound mutations
Browser mutations must come from the configured origin. Responses are no-store and nosniff, and session cookies are HttpOnly, SameSite=Lax and __Host-prefixed in production.
Safe errors and limits
Errors are returned as a category — unauthorized, invalid_request, invalid_origin, method_not_allowed, try_later and temporarily_unavailable — never as a database or provider message. Requests are rate limited per client.
Two honest examples
One request you can run against any Hostingsurge host, and one that illustrates the shape of a session-authenticated read.
# Public liveness — runnable as shown
curl -sS https://<your-host>/api/health
{"status":"ok"}The health route returns exactly this and reads nothing else.
# Illustrative: the dashboard sends its own session cookie
curl -sS 'https://<your-host>/api/projects?organizationId=<uuid>' \
-H 'cookie: __Host-hs_session=<session>'
{"status":"ok","projects":[{"id":"<uuid>","name":"<name>","kind":"static","sourceStatus":"ready"}]}Illustrative shape of the response, not a runnable example: sessions are issued to a browser, not handed out as a token. Field names and value bounds are enforced by the route.
Export and no lock-in
Lock-in is a design decision, and this platform makes the opposite one.
- Version history, comparison of saved versions and restore are core product features, not an upgrade.
- GET /api/source-export streams a deterministic ZIP of any saved version, with UTF-8 names and unix mode bits preserved.
- Archives are bounded at 1000 entries, 256 KB per file and 16 MB per archive — the same limits the platform enforces when it saves them.
- Your code, your data and your domain stay yours. The platform never becomes the cage.
Developer questions
Can I call the API with an API key right now?
You can issue scoped API and MCP credentials from the account key page today. The routes documented above are session-authenticated; a public key-authenticated REST surface is in development and is not claimed here.
Is there a sandbox environment?
Not as a separate public environment. Development and test work in this repository runs against disposable local PostgreSQL, Redis and provider fixtures, and the result of that work is what the pages here describe.
Do webhooks go both ways?
Only in one direction today: the platform receives signed provider events (for example payments) and verifies them before anything changes. Customer-facing outbound webhooks are not implemented.
Which provider does Hostingsurge use?
The platform is provider-abstracted, and normal workflows never send you to a vendor panel. Provider products are exposed through Hostingsurge concepts — hosting, versions, backend, storage and domains.
Where do I report a bug?
There is no public issue tracker for this preview yet. Definitive, reproducible findings are worth more than volume — the docs page describes what is implemented, and the status page describes what is live right now.
Build on the same platform we run.
Create a free account, issue a scoped credential and read the endpoints page before you write your first client.
Every route on this page exists in the current build and is covered by the platform’s own tests. Routes for modules that are still in development are deliberately absent.