ALEX STUDIO HQ / DOCUMENTATION

Connect files.
Run durable tasks.

Set up a project once, then use its scoped API key from any server or hosting platform.

1. Enable permissions in the admin dashboard

Select your project under Projects.
Enable files for storage. For AI-to-record tasks, enable all three: workflows, ai, and data.
Create a key under API keys.
Select the same permissions on the key. An existing key does not gain permissions when you enable a project feature; open API keys → Scopes, select the enabled features, and save. The existing key value stays the same; regeneration is unnecessary.
Save the project key on the calling server.
Use ALEX_STUDIO_HQ_API_KEY in your hosting platform’s secret environment settings. Never embed it in browser JavaScript, mobile bundles, URLs, or public repositories. Forward browser requests through your own authenticated backend.

2. Verify your connection

export ALEX_STUDIO_HQ_URL="https://admin.alexstudiohq.com"
# Set ALEX_STUDIO_HQ_API_KEY securely in your server environment.
# Use your project key, not your Cloudflare API token.
curl --fail-with-body "$ALEX_STUDIO_HQ_URL/v1/capabilities" \
  -H "Authorization: Bearer $ALEX_STUDIO_HQ_API_KEY"

The response’s features array contains the intersection of project features and key permissions. If files or workflows is missing, correct the project and key setup before calling that feature.

3. Use private R2 files with curl

Upload the raw file bytes. The resource name is an identifier, not a path: letters, digits, underscores, and hyphens, up to 80 characters. A PUT replaces the same project’s existing file.

printf "Hello from my project" > report.txt

# Upload
curl --fail-with-body -X PUT "$ALEX_STUDIO_HQ_URL/v1/files/report" \
  -H "Authorization: Bearer $ALEX_STUDIO_HQ_API_KEY" \
  -H "Content-Type: text/plain" --data-binary @report.txt

# List; follow nextCursor using ?cursor=VALUE when present
curl --fail-with-body "$ALEX_STUDIO_HQ_URL/v1/files" \
  -H "Authorization: Bearer $ALEX_STUDIO_HQ_API_KEY"

# Download
curl --fail-with-body "$ALEX_STUDIO_HQ_URL/v1/files/report" \
  -H "Authorization: Bearer $ALEX_STUDIO_HQ_API_KEY" --output downloaded-report.txt

# Delete when no longer needed
curl --fail-with-body -X DELETE "$ALEX_STUDIO_HQ_URL/v1/files/report" \
  -H "Authorization: Bearer $ALEX_STUDIO_HQ_API_KEY"

Limits: 1 MiB per file; 32 MiB and 1,000 files per project; 512 MiB across the ecosystem; 500 file mutations across the ecosystem per UTC day. Listing returns up to 50 items with nextCursor. Downloads are authenticated attachments with no public R2 URL. Files are isolated by project even when names match.

4. Start a durable Workflow

curl --fail-with-body -X POST "$ALEX_STUDIO_HQ_URL/v1/workflows" \
  -H "Authorization: Bearer $ALEX_STUDIO_HQ_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: greeting-v1" \
  --data '{"type":"ai-to-record","prompt":"Write a short greeting","collection":"notes","key":"greeting"}'

# Copy id from the response, then poll with bounded backoff:
curl --fail-with-body "$ALEX_STUDIO_HQ_URL/v1/workflows/REPLACE_WITH_RETURNED_ID" \
  -H "Authorization: Bearer $ALEX_STUDIO_HQ_API_KEY"

# After status is completed, read the saved record:
curl --fail-with-body "$ALEX_STUDIO_HQ_URL/v1/data/notes/greeting" \
  -H "Authorization: Bearer $ALEX_STUDIO_HQ_API_KEY"

Submission returns HTTP 202 with id and status. Poll until completed or failed; pending/running is not completion. Reuse the same idempotency key and identical input when retrying an uncertain submission. Different input with that key returns 409. Duplicate attempts are still recorded as application activity. Choose a new idempotency key only for a new intended task.

Supported type: ai-to-record. Prompt: up to 4,000 characters. Collection and record key: identifier format above. The task generates AI text, then saves a D1 value containing response, model, and workflowId. Writing the same collection/key replaces its value. Access is rechecked between steps; revoking the issuing key or pausing its project stops subsequent steps. Retries may repeat AI inference after a crash.

Limit: 100 workflow starts shared across the ecosystem per UTC day, plus shared request and AI capacity. Completed/failed Workflow results have 90-day D1 retention; native Workflow execution history has separate provider retention.

5. Use the server-side JavaScript SDK

Download alex-studio-hq.js into your project. It is a native ESM module for server runtimes with fetch; no npm package is published.

import { createClient } from "./alex-studio-hq.js";

const hq = createClient({
  apiKey: process.env.ALEX_STUDIO_HQ_API_KEY,
  baseUrl: "https://admin.alexstudiohq.com",
});

await hq.capabilities();
await hq.files.put("report", new TextEncoder().encode("Hello"), { contentType: "text/plain" });
const page = await hq.files.list();
if (page.nextCursor) await hq.files.list({ cursor: page.nextCursor });
const download = await hq.files.get("report"); // Fetch Response
console.log(await download.text());
await hq.files.delete("report");

const run = await hq.workflows.start({
  prompt: "Write a short greeting", collection: "notes", key: "greeting",
  idempotencyKey: "greeting-v1",
});
// Repeat status reads with bounded backoff until completed or failed.
const status = await hq.workflows.get(run.id);
if (status.status === "completed") console.log(await hq.data.get("notes", "greeting"));

Errors and retries

400: invalid identifier, body, or unsupported Workflow type.
401: missing, invalid, or revoked project key.
403: project paused or required permission missing.
409: conflicting idempotency input or a file operation is busy. Long-pending file operations need owner review.
413: upload exceeds the size limit.
429: an IP throttle, shared ecosystem safeguard, storage allowance, or upstream provider limit was reached. Repeated submissions are still recorded even if deduplicated.
503: dependency unavailable; use bounded retries. Keep the same idempotency key for uncertain Workflow submissions.

Owner operations and backup setup

The private Operations dashboard shows dependency checks every 15 minutes, alerts, private SQL snapshots, storage usage, and recent Workflow runs. Project keys cannot manage backups, create projects, or issue API keys. Admin setup uses Google sign-in and the owner password; Turnstile protects the password step. MCP tools depend on enabled scopes; read the current MCP guide and tools/list. Files and Workflows use REST or this SDK.

For daily SQL exports, the owner saves a Cloudflare account-scoped D1 Read API token as an encrypted secret named D1_EXPORT_TOKEN on alex-hq-operations, then saves and deploys. This token is separate from project API keys and stays on the operations Worker. Paste only its value, without Bearer or quotation marks. A configured secret does not prove authorization: run Create SQL backup once and confirm four new snapshots with current timestamps.

Manual limits are two backup starts and 24 health-check starts per UTC day. Queued means accepted, not successful. Failed starts consume the manual allowance. HTTP 401 with Cloudflare code 10000 indicates the export credential was rejected; check its value, validity, and account scope before retrying. Daily backup scheduling is 03:00 UTC (04:00 Nigeria time) when the secret is configured; verify resulting snapshots rather than assuming success from configuration.

D1 Time Travel on Free provides seven days of recovery. SQL snapshots are private, retained for 14 days, and bounded to 8 MiB per export with SHA-256 readback verification. Larger exports require another backup path. SQL snapshots do not copy R2 project-file bytes. Restore into a scratch database first and rotate restored keys/sessions before reopening production.

Cloudflare Free allowances are shared with other applications in the same account. These application limits are not a billing guarantee. See OpenAPI for machine-readable routes and the AI integration guide for agent instructions.

Connect files.Run durable tasks.