---
title: "Trigger Build"
method: POST
path: "/v2/builds/trigger-direct"
tags: ["builds"]
---

# Trigger Build

`POST /v2/builds/trigger-direct`

Trigger an environment build from a previously uploaded build context.

## Request body

- BuildTriggerRequest — Trigger a build for a registry.
  - `source` 'direct', required
  - `registry_id` string, uuid, nullable
  - `build_id` string, uuid, nullable
  - `name` string, nullable
  - `project_id` string, uuid, nullable
  - `environment_variables` object
  - `build_secrets` object
  - `runtime_provider` 'hud' | 'modal', nullable
  - `runtime_config` SubmittedRuntimeConfig — SDK ``RuntimeConfig`` accepted by hosted v6 submissions. Provider-specific support is validated by the SDK runtime implementation.
    - `image` string, nullable
    - `compose` SubmittedComposeProject — Compose document and its optional environment source artifact.
      - `document` SubmittedComposeDocument, required — Normalized Compose document transported with a hosted runtime artifact.
        - `services` object, required
      - `root` SubmittedComposeProjectRef — Build-context location inside the selected environment source artifact.
        - `compose_path` string, required
      - `service_access` boolean, nullable
    - `resources` SubmittedRuntimeResources — Wire-compatible subset of ``hud.eval.runtime.RuntimeResources``.
      - `cpu` number, nullable
      - `memory_mb` integer, nullable
      - `storage_mb` integer, nullable
      - `gpu` SubmittedRuntimeGPU — Wire-compatible subset of ``hud.eval.runtime.RuntimeGPU``.
        - `type` string, nullable
        - `count` integer
    - `limits` SubmittedRuntimeLimits — Wire-compatible subset of ``hud.eval.runtime.RuntimeLimits``.
      - `startup_timeout_s` integer, nullable
      - `run_timeout_s` integer, nullable
  - `entry_folder` string, nullable
  - `build_args` object, nullable
  - `no_cache` boolean — Bypass persistent cache inputs and whole-build reuse while still exporting fresh cache state.

## Response `200`

Successful Response

- BuildResponse
  - `id` string, uuid, required
  - `registry_id` string, uuid, required
  - `status` string, required
  - `sdk_generation` string, required
  - `version` integer, nullable
  - `uri` string, nullable
  - `image_name` string, nullable
  - `digest` string, nullable
  - `lock` McpLock
    - `tools` Tool[]
      - `name` string, required
      - `title` string, nullable
      - `description` string, nullable
      - `inputSchema` object, required
      - `outputSchema` object, nullable
      - `icons` Icon[], nullable
        - `src` string, required
        - `mimeType` string, nullable
        - `sizes` string[], nullable
      - `annotations` ToolAnnotations — Additional properties describing a Tool to clients. NOTE: all properties in ToolAnnotations are **hints**. They are not guaranteed to provide a faithful description of tool behavior (including descriptive properties like `title`). Clients should never make tool use decisions based on ToolAnnotations received from untrusted servers.
        - `title` string, nullable
        - `readOnlyHint` boolean, nullable
        - `destructiveHint` boolean, nullable
        - `idempotentHint` boolean, nullable
        - `openWorldHint` boolean, nullable
      - `_meta` object, nullable
      - `execution` ToolExecution — Execution-related properties for a tool.
        - `taskSupport` 'forbidden' | 'optional' | 'required', nullable
    - `prompts` Prompt[]
      - `name` string, required
      - `title` string, nullable
      - `description` string, nullable
      - `arguments` PromptArgument[], nullable
        - `name` string, required
        - `description` string, nullable
        - `required` boolean, nullable
      - `icons` Icon[], nullable
        - `src` string, required
        - `mimeType` string, nullable
        - `sizes` string[], nullable
      - `_meta` object, nullable
    - `resources` Resource[]
      - `name` string, required
      - `title` string, nullable
      - `uri` string, uri, required
      - `description` string, nullable
      - `mimeType` string, nullable
      - `size` integer, nullable
      - `icons` Icon[], nullable
        - `src` string, required
        - `mimeType` string, nullable
        - `sizes` string[], nullable
      - `annotations` Annotations
        - `audience` string[], nullable
        - `priority` number, nullable
      - `_meta` object, nullable
    - `transport` 'http' | 'stdio' | 'channel'
  - `manifest` EnvManifest — What build introspection captured from a v6 image's control channel.
    - `env` ManifestEnv, required — Env identity from the control channel's `hello` reply.
      - `name` string, required
      - `version` string
    - `capabilities` ManifestCapability[]
      - `name` string, required
      - `protocol` string, required
    - `tasks` ManifestTask[]
      - `id` string, required
      - `description` string, nullable
      - `args` object, nullable
      - `input` object, nullable
      - `returns` object, nullable
  - `duration_seconds` integer, nullable
  - `error_message` string, nullable
  - `runtime_config` object, nullable
  - `source_index_status` 'pending' | 'indexing' | 'ready' | 'failed' | 'unavailable', required
  - `source_index_error` string, nullable
  - `source_index_started_at` string, date-time, nullable
  - `source_indexed_at` string, date-time, nullable
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, nullable
  - `branch` string, nullable
  - `github_url` string, nullable
  - `user_name` string, nullable
  - `scenario_count` integer, nullable

## Other responses

- `400` — Invalid or malformed request
- `401` — Missing or invalid credentials
- `403` — Caller may not access this resource
- `404` — Referenced entity does not exist
- `409` — Resource already exists
- `422` — Validation Error

---

[API](https://skmtc.dev/hud/apis/hud-platform.md) · [All operations](https://skmtc.dev/hud/apis/hud-platform/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/hud/hud-platform/revisions/58558fc733d9/schema)