createSpace() for web pages

The client for web pages, with a web key that is safe to publish, and how it runs tasks.

import { createSpace } from "digitospace/web"

The web client runs tasks from a web page with a web key, which starts with dpk_. It has one function, space.ai.run(), and reaches nothing else. See Add AI to a web page for how web keys work and what they protect.

The server client, from digitospace, holds an API key and never runs in a page. The two share nothing but the task shapes and SpaceError.

createSpace()

createSpace(options: WebSpaceOptions): WebSpace

keystringRequired: The web key, dpk_ and 26 characters, from AI, then Web keys in the console. An API key starting with dsk_ fails with validation_failed, so a secret is never sent from a page.
urlstring: Another address for AI, for testing. Leave it out to use ours.
timeoutMsnumber: How long starting a visit may take, in milliseconds, from 1,000 to 600,000. Defaults to 30,000. A run may take up to 10 minutes unless you pass timeoutMs to it.
retriesnumber: How many more times to try a call refused with 429 or 503 before any work began, 0 to 5. Defaults to 2. A refusal that asks to wait more than 30 seconds, such as a visitor’s daily cap, is not tried again.
rememberboolean: true, the default, keeps the visitor’s ID in the browser’s local storage, so a visitor keeps one daily allowance across reloads. false keeps nothing in the browser.
fetchtypeof fetch: The fetch to send requests with. Defaults to the browser’s own.

space.ai.run()

run(task: string, options: TaskOptions & { stream: true }): Promise<TaskStream>
run(task: string, options?: TaskOptions & { stream?: false }): Promise<TaskReply>

Takes the same options, and returns the same task reply or task stream, as run() on a server: input, variables, history, stream, signal, and timeoutMs.

The first run starts a visit: the client asks for a small puzzle, solves it in the page in short slices so the page stays responsive, and gets a visit that lasts an hour. Later runs reuse it, and runs made at the same time share one start. When a visit expires, the client starts a new one and tries the run once more.

A run is never sent again after a network failure, because the model may already have started.

Errors

Besides the codes every task run can give, such as validation_failed and task_not_found:

Code	When
`visitor_limit_reached`	This visitor used their runs a minute or AI units a day
`key_limit_reached`	The key, or the project, used its AI units for now
`too_many_sessions`	Too many new visits came from this network in an hour
`origin_not_allowed`	The page’s address is not on the key
`task_not_allowed`	The key may not run that task
`key_not_found`	The key does not exist or was revoked
`challenge_failed`	The puzzle’s answer was refused; the next run starts again
`aborted`	The `signal` was aborted, including while the puzzle was being solved

Example

page.ts

import { createSpace, isSpaceError } from "digitospace/web"

const space = createSpace({ key: "dpk_01m3d44nq41sec9tj8m2tbgh18" })

const form = document.querySelector("form")!
const output = document.querySelector("output")!

form.addEventListener("submit", async (event) => {
  event.preventDefault()
  const input = new FormData(form).get("question") as string
  output.textContent = ""
  try {
    const stream = await space.ai.run("support-reply", { input, stream: true })
    for await (const chunk of stream) output.textContent += chunk.text
  } catch (error) {
    output.textContent =
      isSpaceError(error) && error.code === "visitor_limit_reached"
        ? "You’ve reached today’s limit. Try again tomorrow."
        : "Something went wrong. Try again."
  }
})

Last updated 30 September 2026