---
title: "Create a new stack"
method: POST
path: "/v1/stacks"
tags: ["Stacks"]
---

# Create a new stack

`POST /v1/stacks`

Create a new stack environment using manifest + bundle format. Upload a JSON manifest with file metadata and a tar.zst bundle containing your project files. For multi-service stacks, automatically detects and orchestrates multiple services.

## Headers

- `idempotency-key` string, required — Unique key for idempotent requests
- `content-hash` string — SHA-256 hash of the bundle for deduplication

## Response `202`

Stack creation initiated

- object — Response after creating a new stack
  - `id` string, required — Stack identifier
  - `kind` 'single' | 'stack', required — Stack kinds
  - `url` string, uri, required — Live URL for the stack
  - `phase` 'starting' | 'building' | 'deploying' | 'running' | 'failed' | 'stopped', required — Stack lifecycle phases
  - `etag` string, required — ETag for caching/optimistic updates
  - `contentHash` string, required — Content hash for deduplication
  - `idempotencyKey` string — Idempotency key echo
  - `buildStatus` object — Build status information
    - `phase` 'pending' | 'running' | 'completed' | 'failed', required — Build phase states
    - `logs` string — Build logs (truncated)
    - `error` string — Error message if failed
    - `duration` number — Build duration in milliseconds
  - `services` object[] — Services in the stack
    - `id` string, required — Service identifier
    - `name` string, required — Service name
    - `role` 'frontend' | 'backend' | 'fullstack' | 'worker' | 'database' | 'unknown', required — Service roles in a stack
    - `phase` 'starting' | 'building' | 'deploying' | 'running' | 'failed' | 'stopped', required — Stack lifecycle phases
    - `workspacePath` string, required — Workspace path relative to project root
    - `port` number — Port (if applicable)

## Other responses

- `400` — Bad request
- `409` — Duplicate content - existing stack returned
- `413` — Payload too large

## Changes

- **2025-10-29** `17a1ccb59fba` — 1 info
  - api operation id `create_stack` was added
- **2025-10-29** `1a4801fc49a1` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/benchify/apis/benchify-api/changes/v1/stacks/post.md)

---

[API](https://skmtc.dev/benchify/apis/benchify-api.md) · [All operations](https://skmtc.dev/benchify/apis/benchify-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/benchify/benchify-api/revisions/1a65aea8dd7d/schema)