Hyperscale API documentation

Start

Build and run a sandbox Product with the hyperscale CLI, MCP, the HTTP API or the TypeScript SDK.

  1. Install the CLI

    Node 20 or later. Without the install, bunx @hyperscale0/cli@latest <command> runs the same commands.

    npm i -g @hyperscale0/cli

  2. Sign in

    Approve the code in your browser. New here? hyperscale auth signup makes the account; /auth.md covers both, and signing in with only a browser.

    hyperscale auth login

  3. Describe your business

    Say what you sell and who pays whom. The Architect drafts and checks the Product, and --yes saves the change. The Architect is free.

    hyperscale architect chat --brief "Desks by the month: SAR 1,200, a SAR 500 deposit, SAR 50 late fee" --yes

  4. Run a test customer through it

    In an empty folder, init writes the Product's files and day.json. The scenario funds a new test customer with SAR 10,000.00 of sandbox money and walks it to its first payment. Each run adds another customer.

    hyperscale init
hyperscale scenario run day.json

  5. Change it

    Edit product.hsx, check it, save the plan, read it, then apply that plan.

    hyperscale hsx check product.hsx
hyperscale hsx plan --json > plan.json
hyperscale hsx apply --plan-file plan.json --yes

  6. Call the HTTP API

    Make a sandbox Product key, then call any route with it. /docs/api.md walks one customer through money with curl.

    hyperscale key create
curl "https://hyperscale0.ai/v1/customers?productId=$PRD" -H "Authorization: Bearer $KEY"

  7. Use the TypeScript SDK

    Call the Product from your app with the same key. /docs/sdk.md runs a customer through an action and the clock.

    npm i @hyperscale0/sdk

  8. Connect an agent

    Add the MCP server and approve it in the browser. A coding agent in a terminal gets its own sandbox login with hyperscale agent setup. /docs/mcp.md covers every client.

    claude mcp add --transport http hyperscale https://hyperscale0.ai/v1/mcp

Every client calls the same operations and reads the same state. The CLI takes money in major units, like 300.50; the HTTP API and MCP take minor-unit strings, like "30050".

CLI exit codes

  • 0 ok: Success.
  • 1 failed: The server refused the request or could not finish it, or the command failed after it started.
  • 2 usage: Usage: an unknown command or option, or an argument, flag or input the CLI refused before sending anything. An HSX check failure also exits 2.
  • 3 approval: Waiting for a person to approve the action in the browser.
  • 4 auth: Sign in: no login, or the login or key was not accepted (HTTP 401). The CLI's own check prints Code auth_required.
  • 5 notFound: The thing named does not exist (HTTP 404).
  • 6 conflict: The request conflicts with the current state (HTTP 409), such as an action that already ran or an idempotency key reused with other input.
  • 7 forbidden: Signed in, but this login, its role or the key may not do that (HTTP 403). Signing in again does not help. The Code names the missing permission, such as missing_required_scope or missing_required_permission, or live_not_enabled when the company has no live yet.

Guides

The Architect

The Architect writes, edits and repairs HSX from your brief, in the terminal or the Build portal. The compiler checks each proposal, and you review the diff before it saves.

Hyperscale is in testing. A compiler pass does not prove that a program matches every business requirement. Review the proposal and any limits the Architect reports.

Open the Build portal