Public API

Upload source in, fetch status out, keep privileged controls private

The DocuHost API is intentionally narrow. It handles ZIP source submission, Git metadata registration, AI job creation, and high-level status retrieval without exposing raw artifacts, shell access, or privileged infra controls. Treat the beta contract as static-only, npm-oriented, and GitHub-first.

API rule

Uploads in, status out, nothing privileged exposed.

Signed source intake flow

// 1) Ask DocuHost for a ZIP source upload session
const prepare = await fetch('https://docuhost.cloud/api/v1/source-sessions', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY',
  },
  body: JSON.stringify({
    siteId: 'YOUR_SITE_ID',
    filename: 'launch-site.zip',
    size: zip.size,
    contentType: 'application/zip',
  }),
}).then((res) => res.json());

// 2) Upload directly to object storage
await fetch(prepare.uploadUrl, {
  method: 'PUT',
  headers: { 'Content-Type': 'application/zip' },
  body: zip,
});

// 3) Finalize and queue validation + deployment
const queued = await fetch('https://docuhost.cloud/api/v1/sources/zip/complete', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'x-api-key': 'YOUR_API_KEY',
  },
  body: JSON.stringify({ uploadToken: prepare.uploadToken }),
}).then((res) => res.json());

// 4) Poll high-level deployment state
const deploy = await fetch('https://docuhost.cloud/api/v1/deploys/' + queued.deploymentId, {
  headers: { 'x-api-key': 'YOUR_API_KEY' },
}).then((res) => res.json());

API surface

POST /api/v1/source-sessions

Create a signed upload session for a ZIP source bundle tied to a specific site.

POST /api/v1/sources/zip/complete

Finalize an uploaded ZIP and enqueue the validation and deployment workflow.

POST /api/v1/git-links

POST /api/v1/ai/jobs

Submit a constrained AI site-generation payload, receive a credit estimate, and queue the job for status polling.

GET /api/v1/jobs/:jobId

Fetch high-level AI job state, credits, tokens, and change summary details.

GET /api/v1/deploys/:deployId

Fetch high-level deployment state, URLs, validation summary, and pipeline steps.

Required AI schema

Site type
Brand or project name
Target audience
Objective
Primary CTA
Required sections
Visual direction
Provided assets or content
SEO metadata
Legal or footer needs
Build intent

Beta operating contract

Static-only sites

DocuHost beta is for landing pages, brochure sites, docs, portfolios, waitlists, and other client-side static experiences. Backend frameworks, databases, and server runtimes are unsupported.

GitHub-only repo intake

Git import is GitHub-only in v1, and the intended beta execution path is public repositories only. Private repo automation should be treated as unsupported for this slice.

npm-oriented projects

Deployable sources are expected to resolve to npm-based static frontend projects. Alternative package managers and server-first monorepo flows are outside the supported beta contract.

AI stays bounded

AI jobs are schema-driven, static-only, and intended for small brochure-style sites rather than arbitrary full-stack app generation.

Control plane boundaries

Public clients should call only the /api/v1 endpoints. Build, deploy, and domain orchestration remain internal to the DocuHost control plane.
The public-beta completion plan reserves POST /api/internal/process-deployments, POST /api/internal/process-ai-jobs, and POST /api/internal/poll-domains for protected internal use only.
When that runner layer is enabled, the intended cadence is every minute for deployment and AI processing, and every five minutes for domain polling via Vercel Cron.

Operator envs

If you are running the DocuHost control plane itself, these env groups back the beta deployment, AI, and internal runner layers. API consumers only need a valid `x-api-key`.

AI generation

OPENAI_API_KEY / OPENAI_MODEL

Cloudflare Pages + domains

CLOUDFLARE_PAGES_API_TOKEN / CLOUDFLARE_PAGES_ACCOUNT_ID / CLOUDFLARE_ZONE_ID / DOCUHOST_ROOT_DOMAIN

Internal runner security

INTERNAL_RUNNER_SECRET / UPLOAD_SESSION_SECRET

Need auth and billing for API usage?

API keys are still managed from the signed-in workspace. Billing, plan upgrades, and credit state remain part of the DocuHost control plane rather than being delegated to public endpoints.

Compare plans Create workspace