API Overview

API Overview

All browser API traffic flows through the Edge service at localhost:3000 (dev) or your domain in production. No backend service is directly accessible from the browser.

Authentication

Every authenticated request must include:

Authorization: Bearer <jwt>

Obtain the JWT from the auth flow (OAuth or passkey). The token is stored in the browser session. All service wrappers in the frontend inject it automatically via apiFetch.

For server-to-server calls inside the Docker network:

Authorization: Bearer <INTERNAL_SERVICE_SECRET>

Request format

All API calls use JSON:

POST /api/doc/api/data
Content-Type: application/json
Authorization: Bearer <jwt>
x-env-id: <environment-id>
x-tenant-id: <tenant-id>

{
  "action": "get",
  "collection": "files",
  "id": "file-01j8abc...",
  "data": null
}

x-env-id and x-tenant-id are mandatory on every request to the Doc Gateway and SQL Gateway. Missing them causes the request to fail or write to the wrong namespace.

Response format

All responses return ApiResponse:

type ApiResponse = {
  success: boolean;
  status:  number;
  parsedData: unknown | null;
  headers: Record<string, string>;
};

apiFetch never throws — network failures return { success: false, status: 0 }. Always check response.success before using response.parsedData.

Key endpoints

Path	Method	Service	Purpose
/api/doc/api/data	POST	Doc Gateway	Read/write Firestore documents
/api/doc/api/storage/upload	POST	Doc Gateway	Upload blobs to GCS
/api/sql/api/query	POST	SQL Gateway	Execute SQL queries
/api/sql/api/transaction	POST	SQL Gateway	Execute SQL transactions
/api/ai/api/generate	POST	AI Gateway	LLM generation
/api/jobs	POST	Worker (via Edge)	Submit a background job
/api/jobs/:id	GET	Worker (via Edge)	Get job status
/api/jobs/:id/stream	GET	Worker (via Edge)	SSE job progress stream
/auth/login	POST	Auth	Initiate OAuth flow
/auth/refresh	POST	Auth	Refresh JWT

See the Worker Job Types reference for all supported job types.