Introduction
API overview
The Frontables REST API lets you create projects, read their files and run AI generations from your own scripts, CI pipelines or tools. All endpoints live under /api/v1, accept and return JSON, and act on behalf of the user who owns the API key.
Successful responses wrap the payload in {"data": …}. Errors use {"error": {"code", "message", "details", "requestId"}}.
Introduction
Authentication
Create a personal API key in API keys. Send it as a bearer token on every request:
Authorization: Bearer fbk_xxxxxxxxxxxxxxxxKeys are shown once at creation and stored only as a SHA-256 hash. Revoking a key takes effect immediately. Keys inherit your plan's limits and credit balance. Never embed keys in browser code or public repositories.
Introduction
Rate limits
- 120 requests / minute per API key across all v1 endpoints.
- 20 generations / minute per user (shared with the web workspace).
Exceeding a limit returns 429 rate_limited with details.retryAfter in seconds. Limits are enforced centrally, so they apply across all regions and instances.
Introduction
Error codes
| HTTP | code | Meaning |
|---|---|---|
| 401 | unauthorized | Missing, malformed, invalid or revoked API key. |
| 402 | insufficient_credits | Your credit balance for this period is exhausted. |
| 403 | forbidden | Account suspended or resource not yours. |
| 403 | plan_limit_reached | Plan limit (projects, premium model…) reached. |
| 404 | not_found | The project doesn't exist or you can't access it. |
| 422 | validation_error | Invalid body. details contains field errors. |
| 429 | rate_limited | Too many requests. Retry after details.retryAfter seconds. |
| 502 | ai_* | The upstream AI provider failed (e.g. ai_timeout, ai_upstream_error). You are not charged. |
| 503 | not_configured | A required integration isn't configured on this deployment. |
| 500 | internal_error | Unexpected error. Include requestId when contacting support. |
Introduction
Credits & billing
Generations through the API consume credits exactly like the workspace: roughly one credit per 2,000 tokens times the model's multiplier, minimum one. The response includes creditsCharged and your remaining creditBalance. Failed generations are never charged.
Integration guides
Node.js / TypeScript
const BASE = "https://YOUR_DEPLOYMENT/api/v1";
const headers = { Authorization: `Bearer ${process.env.FRONTABLES_API_KEY}`, "Content-Type": "application/json" };
const { data: project } = await fetch(`${BASE}/projects`, {
method: "POST", headers,
body: JSON.stringify({ name: "Launch page", category: "landing" }),
}).then((r) => r.json());
const res = await fetch(`${BASE}/projects/${project.id}/generate`, {
method: "POST", headers,
body: JSON.stringify({ prompt: "A landing page for a coffee subscription with pricing" }),
});
const body = await res.json();
if (!res.ok) throw new Error(body.error.message);
console.log(body.data.filesChanged, body.data.creditBalance);Integration guides
Python
import os, requests
BASE = "https://YOUR_DEPLOYMENT/api/v1"
H = {"Authorization": f"Bearer {os.environ['FRONTABLES_API_KEY']}"}
project = requests.post(f"{BASE}/projects", json={"name": "Docs site"}, headers=H).json()["data"]
r = requests.post(f"{BASE}/projects/{project['id']}/generate",
json={"prompt": "A documentation site with sidebar navigation"},
headers=H, timeout=300)
r.raise_for_status()
files = requests.get(f"{BASE}/projects/{project['id']}", headers=H).json()["data"]["files"]
for f in files:
print(f["path"], f["size"])Integration guides
Exporting project files
Fetch GET /api/v1/projects/{id} and write each entry in files to disk using its path. The output is static HTML/CSS/JS that can be hosted on any static host (Vercel, Netlify, S3, GitHub Pages). In the workspace you can also download a ZIP from the Deploy menu.
Roadmap
Planned
The following are planned and not yet available: streaming generation over the public API, outbound webhooks for generation events, official SDK packages, and organization-scoped API keys. They will be announced in the developer changelog.