---
title: "Deploy a Site"
method: POST
path: "/v1/sites/deployments"
tags: ["Sites"]
---

# Deploy a Site

`POST /v1/sites/deployments`

## Request

- Base URL: `https://api.dexto.ai`
- URL: `https://api.dexto.ai/v1/sites/deployments`
- Auth: HTTP bearer

Deploy a Site package, the deploy-request.json `pnpm run pack` writes, into the Cloud project. It creates the Site the first time its slug is deployed, provisions its data collections, deploys any Function it mounts and, unless promote is false, makes it the production release. Needs sites:write. The body is at most 80 MiB; a larger one gets 413, and an invalid package gets 400 naming every problem.

## Query parameters

- `promote` 'true' | 'false': false leaves a preview deployment to promote later.
- `provider` 'aws-lambda' | 'cloudflare-workers' | 'local': Where the Site's Function should run. Omit to use host policy; an unavailable choice is refused.

## Request body

- object
  - `resources` object
    - `auth` object
      - `visitors` object
        - `enabled` true, required
        - `methods` string[], required
    - `data` object
    - `version` union, required
      - 2
      - 3
  - `runtime` union, required
    - object
      - `kind` 'static', required
    - object
      - `kind` 'worker', required
      - `worker` object, required
        - `dexto` object
          - `apiKeyScopes` string[], required
        - `dextoApiKey` true: Give the Function its own DEXTO_API_KEY, which acts as its Cloud project with the permissions a project's deployed code needs.
        - `environment` object, required
          - `secrets` object[], required
            - `description` string, required
            - `name` string, required
            - `required` boolean, required
          - `variables` object[], required
            - `name` string, required
            - `value` string, required
        - `healthcheck` object
          - `expectedStatus` integer, required
          - `path` string, required
        - `kind` 'http-api' | 'mcp-server'
        - `modules` object[], required
          - `contentBase64` string, required
          - `mediaType` 'application/javascript+module'
          - `path` string, required
        - `publication` object, nullable, required
          - `interfaces` string[], required
          - `operations` string[], required
        - `routes` object[], required
          - `access` 'public', required
          - `pathPrefix` string, required
        - `runtime` object, required
          - `entrypoint` string, required
          - `target` 'dexto-fetch-v1', required
        - `schemaVersion` 1, required
        - `slug` string, required
        - `title` string, required
  - `schemaVersion` 1, required
  - `slug` string, required
  - `title` string, required
  - `visibility` 'private' | 'unlisted' | 'public'
  - `assets` object[], required
    - `contentBase64` string, required
    - `mediaType` string
    - `path` string, required
  - `entrypoint` string
  - `spaFallback` boolean

## Response `201`

Created.

- object
  - `backend` object, nullable, required: The Function a Site with server routes mounts; null for a static Site.
    - `deployment_id` string, uuid, required
    - `dexto` object, nullable, required: The Function's own DEXTO_API_KEY, when its package sets dextoApiKey (or, in an older package, declares Dexto API scopes), with the scopes it gets. It is bound only when the caller's key or token holds every one; otherwise configured is false.
      - `configured` boolean, required
      - `scopes` string[], required
    - `function_id` string, uuid, required
    - `provider` 'aws-lambda' | 'cloudflare-workers' | 'local', required
    - `secrets` object[], required
      - `configured` boolean, required
      - `description` string, required
      - `name` string, required
      - `required` boolean, required
  - `created_site` boolean, required: Whether this deploy created the Site.
  - `data_collections` object[], required: The managed data collections the package declares.
    - `id` string, uuid, required
    - `name` string, required
    - `seeded_records` integer, required
  - `deployment` object, required
    - `backend_deployment_id` string, uuid, nullable, required: The deployment of the Site's Function this release serves; null for none.
    - `channel` 'preview' | 'production', required: production for the Site's live release; preview for any other.
    - `created_at` string, date-time, required
    - `id` string, uuid, required
    - `object` 'site.deployment', required
    - `preview_url` string, uri, required: This deployment's own URL.
    - `site_id` string, uuid, required
    - `status` 'failed' | 'ready' | 'retired', required
    - `updated_at` string, date-time, required
  - `first_deployment` boolean, required: Whether this is the Site's first deployment.
  - `object` 'site.deploy', required
  - `promoted` boolean, required
  - `site` object, required
    - `backend_function_id` string, uuid, nullable, required: The Function the Site mounts to serve its server routes; null for none.
    - `created_at` string, date-time, required
    - `id` string, uuid, required
    - `object` 'site', required
    - `slug` string, required
    - `title` string, required
    - `updated_at` string, date-time, required
    - `url` string, uri, required: The Site's production URL.
    - `visibility` 'private' | 'unlisted' | 'public', required
  - `url` string, uri, required: The production URL when promoted; otherwise the deployment's preview URL.

## Other responses

- `400`: Invalid JSON or request fields.
- `401`: Missing or invalid API key.
- `402`: The account has insufficient credits.
- `403`: The account cannot perform this operation.
- `404`: The requested resource was not found.
- `409`: The request conflicts with existing resource state.
- `429`: The account exceeded this operation's request rate.
- `500`: Unexpected Dexto failure.
- `502`: The upstream model provider failed.
- `503`: A required Dexto service is temporarily unavailable.

---

[API](https://skmtc.dev/dexto/apis/dexto-api.md) - [All operations](https://skmtc.dev/dexto/apis/dexto-api/llms.txt) - [OpenAPI document](https://skmtc.dev/dexto/apis/dexto-api/revisions/47eb880cffa5?raw)