Deploy API

Most users should deploy with w7s-io/w7s-cloud@v1. The deploy action calls the W7S deploy API.

Endpoint

POST https://w7s.cloud/api/v1/deploy

The request body is a zip archive.

Headers

Authorization: Bearer <github-token>
x-github-repository: owner/repo
x-github-sha: <commit-sha>
x-github-branch: <branch-name>
content-type: application/zip

application/octet-stream is also accepted.

Optional runtime value headers are base64url-encoded JSON objects:

x-w7s-vars: <base64url-json-object>
x-w7s-secrets: <base64url-json-object>

The official GitHub Action writes these headers from w7s.json and the workflow environment.

Authentication

W7S checks the token against GitHub:

GET https://api.github.com/repos/owner/repo
Authorization: Bearer <github-token>

If GitHub returns 401, 403, or 404, W7S rejects the deploy.

Environments

By default:

• main and master deploy to production.
• Other branches deploy to a sanitized branch environment.

Environment names are DNS-safe. W7S lowercases the branch or explicit override, replaces runs of characters outside a-z, 0-9, and - with -, collapses repeated hyphens, trims leading/trailing hyphens, and caps the result at 63 characters.

Production deployments are served from the owner host:

https://<owner>.w7s.cloud/<repo>/

Non-production branch deployments are served from a branch-prefixed host:

https://<branch-environment>--<owner>.w7s.cloud/<repo>/

For example, branch feature/API.v2_test becomes environment feature-api-v2-test:

https://feature-api-v2-test--owner.w7s.cloud/repo/

You can override the environment with either:

?environment=staging
x-w7s-environment: staging

Deployable Outputs

Native backend entrypoints are JavaScript or TypeScript runtime modules only:

backend/index.js
backend/index.mjs
backend/index.ts
backend/index.mts
worker/index.js
worker/index.mjs
worker/index.ts
worker/index.mts
dist/server/index.js
dist/server/index.mjs

Static frontend roots:

frontend/dist/
frontend/build/
frontend/out/
dist/client/
dist/
build/
out/

Static roots normally need an index.html. dist/client/ may be asset-only when paired with dist/server/index.js, which is the output produced by TanStack Start and similar SSR builds.

If backend/, worker/, or dist/server/ exists but does not contain a supported JavaScript or TypeScript entrypoint, W7S still deploys a valid static frontend and returns a deploymentWarnings entry explaining that the backend was skipped. If there is no deployable frontend, the archive is rejected.

See Project Layouts for the native backend handler contract and a Hono example.

Free-tier shape caps

W7S rejects deploys that are too large or declare too many resources before anything is published:

archive zip bytes       25 MB
uncompressed bytes      100 MB
static files            1000
static total bytes      100 MB
static single file      10 MB
Key-value bindings      3
FS bindings             3
SQL bindings            2
Stateful object classes 2
queues                  2
schedules               5
workflows               5
custom domains          3
SQL migration files     50
SQL migration bytes     5 MB

Native backends are dispatched with a custom CPU limit from W7S_USER_WORKER_CPU_MS, default 50, and a subrequest limit from W7S_USER_WORKER_SUBREQUESTS, default 25.

Native backend uploads include W7S-managed log capture unless the platform operator disables it. See Observability for the logs API.

App manifest

JavaScript/TypeScript native backends can include a w7s.json manifest to declare platform resources:

{
  "bindings": {
    "kv": ["CACHE"],
    "fs": ["FILES"],
    "db": [{ "binding": "DB", "migrations": "migrations" }],
    "durableObjects": [
      {
        "binding": "COUNTER",
        "className": "Counter"
      }
    ],
    "hyperdrive": [
      {
        "binding": "DB",
        "id": "postgres-binding-id"
      }
    ]
  },
  "queues": ["jobs"],
  "schedules": [
    {
      "cron": "*/5 * * * *",
      "path": "/_w7s/schedules/sync"
    }
  ],
  "rpc": {
    "allow": ["another-owner/client"]
  },
  "queue": {
    "allow": ["another-owner/client"]
  },
  "vars": ["PUBLIC_API_KEY"],
  "secrets": ["PRIVATE_API_KEY"]
}

queues declares managed background queues for the app. A string queue declaration uses the default consumer path /_w7s/queues/<queue>. Use an object to set a custom consumer path:

{
  "queues": [
    {
      "name": "jobs",
      "consumer": "/internal/queues/jobs"
    }
  ]
}

bindings.durableObjects declares stateful object classes exported by the JavaScript/TypeScript native backend. W7S creates persistent classes when first deployed. See Stateful Objects for examples.

bindings.hyperdrive declares existing managed Postgres binding configs by ID. W7S exposes them to the backend at the configured binding name. See Postgres Bindings for examples.

See Storage Bindings, Backend AI, Backend RPC, and Backend Queues for the runtime behavior of the other declarations.

schedules declares cron-driven backend jobs. Each entry has a five-field UTC cron expression and an absolute backend path. See Backend Schedules for examples.

Usage API

W7S also exposes per-app daily usage rollups with daily limits and warning thresholds:

GET https://w7s.cloud/api/v1/usage/<owner>/<repo>?date=YYYY-MM-DD
Authorization: Bearer <github-token>

Effective limit policies are available without usage counters:

GET https://w7s.cloud/api/v1/limits/<owner>/<repo>
Authorization: Bearer <github-token>

The token must have access to the GitHub repository, just like deploys. See Usage Accounting for the response shape and current limits.