API reference
Vembase API
Build, publish and operate AI-generated Astro websites.
Private beta
This reference is generated from the API server's actual routes, but
https://api.vembase.com is not yet
publicly routable. Treat it as the contract to build against rather than an endpoint you
can call today. Ask for beta access if you want
in early.
Base URL
https://api.vembase.com/v1
Authentication
Bearer JWT in the Authorization header. Every
/v1 route requires one.
Machine-readable
Endpoints
57 operations
Service
Liveness.
/health
no auth
Liveness check
Always returns `{ "ok": true }` when the process is serving.
→ 200
Account
The signed-in profile.
/v1/me Get the signed-in profile
→ 200 · 400 · 401 · 404 · 429
/v1/me Update the profile
→ 200 · 400 · 401 · 404 · 429
Websites
Projects owned by the account.
/v1/websites List websites
→ 200 · 400 · 401 · 404 · 429
/v1/websites Create a website
Allocates a subdomain and an empty draft.
→ 201 · 400 · 401 · 404 · 429
/v1/websites/{id} Get a website
→ 200 · 400 · 401 · 404 · 429
/v1/websites/{id} Update a website
→ 200 · 400 · 401 · 404 · 429
/v1/websites/{id} Delete a website
Removes the project, its versions, and its build output.
→ 204 · 400 · 401 · 404 · 429
Builder
Draft files, AI chat, versions, publishing.
/v1/websites/{id}/draft Get the draft
The builder's working copy of the Astro project.
→ 200 · 400 · 401 · 404 · 429
/v1/websites/{id}/draft Replace the draft files
The complete project on every write — paths, extensions and total size are validated, then the draft is rebuilt.
→ 200 · 400 · 401 · 404 · 429
/v1/websites/{id}/versions List published versions
→ 200 · 400 · 401 · 404 · 429
/v1/websites/{id}/versions/{version}/restore Restore a version into the draft
→ 200 · 400 · 401 · 404 · 429
/v1/websites/{id}/publish Publish the draft
Builds the draft, stores it as the next version and makes it live — on the Vembase subdomain, or to the connected Cloudflare account.
→ 201 · 400 · 401 · 404 · 429
/v1/websites/{id}/deployments List deployments
→ 200 · 400 · 401 · 404 · 429
/v1/websites/{id}/share Create or fetch the draft share link
An unguessable token that serves the unpublished draft at /p/{token}.
→ 200 · 400 · 401 · 404 · 429
/v1/websites/{id}/share Revoke the share link
→ 204 · 400 · 401 · 404 · 429
/v1/websites/{id}/chat List chat messages
→ 200 · 400 · 401 · 404 · 429
/v1/websites/{id}/chat Send a builder message (SSE)
Ownership, credit and draft checks fail as normal JSON errors. Past that point the response is a `text/event-stream`: progress events, then the rebuilt project. Rate limited to 10 requests per minute.
→ 200 · 400 · 401 · 404 · 429 · 503
/v1/websites/{id}/research Research competitors, then build (SSE)
Three model calls and five outbound fetches, then a full build — minutes, streamed as SSE. Rate limited to 3 requests per minute.
→ 200 · 400 · 401 · 404 · 429
Blog
Posts belonging to a website.
/v1/websites/{id}/posts List posts
→ 200 · 400 · 401 · 404 · 429
/v1/websites/{id}/posts Create a post
→ 201 · 400 · 401 · 404 · 429
/v1/websites/{id}/posts/generate Generate a post from a topic
Writes and stores a draft post. Rate limited to 10 requests per minute.
→ 201 · 400 · 401 · 404 · 429
/v1/websites/{id}/posts/{postId} Get a post
→ 200 · 400 · 401 · 404 · 429
/v1/websites/{id}/posts/{postId} Update a post
→ 200 · 400 · 401 · 404 · 429
/v1/websites/{id}/posts/{postId} Delete a post
→ 204 · 400 · 401 · 404 · 429
Forms
Form definitions and captured submissions.
/v1/websites/{id}/forms List forms
→ 200 · 400 · 401 · 404 · 429
/v1/websites/{id}/forms Create a form
→ 201 · 400 · 401 · 404 · 429
/v1/websites/{id}/forms/{formId} Get a form
→ 200 · 400 · 401 · 404 · 429
/v1/websites/{id}/forms/{formId} Update a form
→ 200 · 400 · 401 · 404 · 429
/v1/websites/{id}/forms/{formId} Delete a form
→ 204 · 400 · 401 · 404 · 429
/v1/websites/{id}/forms/{formId}/submissions List submissions for one form
→ 200 · 400 · 401 · 404 · 429
/v1/websites/{id}/submissions List every submission across the website
→ 200 · 400 · 401 · 404 · 429
/v1/websites/{id}/submissions/{submissionId} Set submission status
→ 200 · 400 · 401 · 404 · 429
/v1/websites/{id}/submissions/{submissionId} Delete a submission
→ 204 · 400 · 401 · 404 · 429
Products
Catalog items belonging to a website.
/v1/websites/{id}/products List products
→ 200 · 400 · 401 · 404 · 429
/v1/websites/{id}/products Create a product
→ 201 · 400 · 401 · 404 · 429
/v1/websites/{id}/products/{productId} Get a product
→ 200 · 400 · 401 · 404 · 429
/v1/websites/{id}/products/{productId} Update a product
→ 200 · 400 · 401 · 404 · 429
/v1/websites/{id}/products/{productId} Delete a product
→ 204 · 400 · 401 · 404 · 429
Connectors
Analytics and search-console integrations.
/v1/websites/{id}/connectors List connectors
→ 200 · 400 · 401 · 404 · 429
/v1/websites/{id}/connectors/{provider} Create or update a connector
→ 200 · 400 · 401 · 404 · 429
/v1/websites/{id}/connectors/{provider} Remove a connector
→ 204 · 400 · 401 · 404 · 429
/v1/websites/{id}/connectors/{provider}/sync Trigger a connector sync
→ 200 · 400 · 401 · 404 · 429
Media
Owner-uploaded photography for image slots.
/v1/websites/{id}/media List image slots
→ 200 · 400 · 401 · 404 · 429
/v1/websites/{id}/media/{slot} Upload into a slot
Base64 in a JSON body — no multipart. About 2.6 MB decoded. Rebuilds the draft. Rate limited to 20 requests per minute.
→ 200 · 400 · 401 · 404 · 429
/v1/websites/{id}/media/{slot} Clear a slot
→ 200 · 400 · 401 · 404 · 429
Speed
PageSpeed Insights runs.
/v1/websites/{id}/speed List speed tests
→ 200 · 400 · 401 · 404 · 429
/v1/websites/{id}/speed Run a speed test
A full four-category run takes 20–60 seconds. Rate limited to 6 requests per minute.
→ 201 · 400 · 401 · 404 · 429
/v1/websites/{id}/speed/{testId} Delete a speed test
→ 204 · 400 · 401 · 404 · 429
Integrations
Cloudflare account connection.
/v1/integrations/cloudflare Cloudflare connection status
→ 200 · 400 · 401 · 404 · 429
/v1/integrations/cloudflare Connect with an API token
→ 200 · 400 · 401 · 404 · 429
/v1/integrations/cloudflare Disconnect Cloudflare
→ 204 · 400 · 401 · 404 · 429
/v1/integrations/cloudflare/oauth/start Begin the Cloudflare OAuth flow
Returns the URL to open in a popup. Identity travels in a signed state param.
→ 200 · 400 · 401 · 404 · 429
Public
Unauthenticated: published sites and form capture.
/f/{formId}
no auth
Get a public form definition
What a published site needs to render the form. No session.
→ 200 · 404
/f/{formId}
no auth
Submit a form
Accepts JSON or `application/x-www-form-urlencoded`, from any origin, with no session — published sites post here directly. `_redirect` takes a path and gets a 303 back to the site, so a scriptless HTML form never lands the visitor on raw JSON. `_honey` is a honeypot: filled means accepted-and-discarded. Rate limited to 8 submissions per minute.
→ 200 · 202 · 303 · 400 · 429
/sites/{host}/_api/posts
no auth
List published posts for a live site
`/_api/*` is reserved so it can never collide with a page of the site.
→ 200 · 404
/sites/{host}/_api/posts/{slug}
no auth
Get one published post
→ 200 · 404
Errors
One shape, every failure
Failures return a JSON object with an error string.
Validation failures (400) add an issues tree naming
the fields that failed. A 401 means the bearer token is missing, expired or invalid; a 404
means the resource does not exist or belongs to another account — the API does not
distinguish, so ownership cannot be probed.
{
"error": "Invalid request",
"issues": { "properties": { "slug": { "errors": ["lowercase letters, numbers, dashes"] } } }
}Rate limits
Per minute, per client
| Scope | Limit |
|---|---|
| Everything | 300 / min |
| AI chat and post generation | 10 / min |
| Media uploads | 20 / min |
| Speed tests | 6 / min |
| Public form submissions | 8 / min |
| Competitor research | 3 / min |
Over the limit returns 429 with the standard error
shape.