> ## Documentation Index > Fetch the complete documentation index at: https://docs.gmicloud.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create and start a rebuild > Creates a new Build from the given definition and starts it immediately. A rebuild inherits the most recent Build's provider and resources, so a Template with no Build records left has nothing to inherit and returns 409. Not supported in every IDC; IDCs without rebuild support reject it with 422. ## OpenAPI ````yaml /api-spec/sandbox_api.yaml post /templates/{template_id}/builds openapi: 3.0.3 info: title: GMI Sandbox API description: >- REST API for GMI Sandbox: create isolated execution environments from templates, manage their lifecycle on the control plane, and run commands or transfer files through each sandbox's own data plane. contact: name: GMI Cloud Support email: support@gmicloud.ai version: '2.0' servers: - url: https://console.gmicloud.ai/api/v2 description: Control plane security: - bearerAuth: [] tags: - name: Sandbox description: | Sandbox instance lifecycle management (Sandbox v2, /api/v2/sandboxes) - name: SandboxTemplate description: Sandbox template management (Sandbox v2, `/api/v2/templates`) - name: Sandbox-Exec description: > Sandbox execution data plane (accessed via the sandbox host and sandbox access token). These endpoints are not under the control plane's `/api/v2` path; clients connect directly to `https://{sandbox_key}.{domain}` and authenticate with `X-Access-Token`. - name: Sandbox-Files description: > Sandbox file data plane (`/files`). **These endpoints are not under `/api/v2`** and do not use `Authorization: Bearer`: they are served by the sandbox's own data-plane entry point — clients connect directly to `https://{sandbox_key}.{domain}` and authenticate with `X-Access-Token`. `{sandbox_key}` is the `sandbox_key` returned by the create/connect endpoints, used for data-plane host addressing. `{domain}` and `X-Access-Token` are the `domain` and `sandbox_access_token` from the same responses — no extra endpoint is needed to obtain them. This split is not historical baggage but the nature of a data plane: file transfer is long-lived, high-volume, and addressed per sandbox, differing from the control plane's short requests in both capacity model and failure domain, so they do not share an entry point. **One unified abstraction.** The same contract is served by two backend kinds (an in-sandbox file service / a data-center data-plane proxy); clients need not — and cannot — tell them apart. The cost is that the contract is their intersection: `Content-Length` on download and resumable download (`Range`/`206`) are **optional capabilities** that vary by data center, and clients must work correctly when they are absent. See the per-operation notes below. paths: /templates/{template_id}/builds: parameters: - $ref: '#/components/parameters/TemplateBuildTemplateIdPathParam' post: tags: - SandboxTemplate summary: Create and start a rebuild description: > Creates a new Build from the given definition and starts it immediately. A rebuild inherits the most recent Build's provider and resources, so a Template with no Build records left has nothing to inherit and returns 409. Not supported in every IDC; IDCs without rebuild support reject it with 422. operationId: createTemplateBuild parameters: - $ref: '#/components/parameters/IdcNameQueryParam' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BuildDefinition' responses: '201': description: | The Build record is created and immediately addressable via `GET /templates/{template_id}/builds/{id}`; build progress is reported by `status`, not by the status code. content: application/json: schema: $ref: '#/components/schemas/TemplateBuildMutation' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '409': $ref: '#/components/responses/Conflict' '422': $ref: '#/components/responses/Unsupported' '429': $ref: '#/components/responses/QuotaExceeded' '500': $ref: '#/components/responses/InternalError' components: parameters: TemplateBuildTemplateIdPathParam: name: template_id in: path required: true description: Owning GMI Template identifier. schema: type: string format: uuid IdcNameQueryParam: name: idc_name in: query description: Filter by data center name, e.g. us-denver-1 schema: type: string schemas: BuildDefinition: type: object additionalProperties: false required: - source properties: source: $ref: '#/components/schemas/BuildSource' commands: type: array maxItems: 100 description: Shell command strings executed sequentially during the Build. items: type: string minLength: 1 maxLength: 8192 envs: type: object maxProperties: 256 additionalProperties: type: string maxLength: 32768 description: > Environment variables available only during the Template Build. They are visible to subsequent build commands/steps and are not persisted into the resulting template artifact as sandbox runtime environment variables. Pass runtime env when creating a Sandbox instead. Write-only: values are never returned on Template or TemplateBuild responses. Keys must be unique (JSON object); the server orders them deterministically by key. Key names must match `[A-Za-z_][A-Za-z0-9_]*`. start_cmd: type: string minLength: 1 maxLength: 8192 description: | Launch command persisted with the Build and applied when Sandboxes created from this Template start. TemplateBuildMutation: type: object additionalProperties: false required: - request_id - data properties: request_id: type: string description: HTTP request correlation identifier. data: type: object additionalProperties: false required: - id - template_id - status properties: id: type: string description: The Build this mutation created or started. template_id: type: string description: Owning GMI Template identifier. status: $ref: '#/components/schemas/BuildStatus' BuildSource: oneOf: - $ref: '#/components/schemas/ImageSource' - $ref: '#/components/schemas/TemplateSource' discriminator: propertyName: type mapping: image: $ref: '#/components/schemas/ImageSource' template: $ref: '#/components/schemas/TemplateSource' description: Manual Build source. Sandbox sources use the snapshot endpoint. BuildStatus: type: string enum: - waiting - building - ready - error description: Normalized Template Build status. ErrorResponse: type: object required: - code - message - request_id properties: code: type: string description: Machine-readable business error code example: Resource.QuotaExceeded message: type: string description: Human-readable error description example: The resource quota is not enough. request_id: type: string description: Tracing ID example: req-xxxx details: type: object description: Field-level error details additionalProperties: true ImageSource: type: object additionalProperties: false required: - type - image properties: type: type: string enum: - image image: type: string minLength: 1 description: | Debian or Ubuntu container image reference. The server validates the image against the IDC-supported base OS policy. TemplateSource: type: object additionalProperties: false required: - type - template_id properties: type: type: string enum: - template template_id: type: string description: Parent GMI Template identifier in the same IDC. build_id: type: string description: | Optional parent Build identifier. When omitted, the parent's current successful Build is used. responses: BadRequest: description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: Parameter.Invalid message: Invalid request parameters request_id: req-xxxx Unauthorized: description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: Auth.Unauthorized message: Authentication required request_id: req-xxxx Forbidden: description: The caller cannot access the organization-scoped resource. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: Resource.NotFound message: The requested resource was not found request_id: req-xxxx Conflict: description: State conflict content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: Resource.StateConflict message: Resource state conflict request_id: req-xxxx Unsupported: description: | The request is valid but the selected IDC or provider does not support the requested capability or resolved resource specification. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' QuotaExceeded: description: The configured or temporary resource quota would be exceeded. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' InternalError: description: Internal server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: code: Internal.ServerError message: An internal server error occurred request_id: req-xxxx securitySchemes: bearerAuth: type: http scheme: bearer description: > API Key or Access Token, always sent as `Authorization: Bearer `. The gateway recognizes the token type automatically. ````