---
title: "Bring a stack up from a stack file (briq.yaml)"
method: POST
path: "/v1/stacks/up"
tags: ["stacks"]
---

# Bring a stack up from a stack file (briq.yaml)

`POST /v1/stacks/up`

## Request

- Base URL: `https://api.briq.cloud`
- URL: `https://api.briq.cloud/v1/stacks/up`
- Auth: HTTP bearer

Creates each service of the file the stack does not have, as `POST /v1/briqs` makes it and under the same checks: all of them or none. Leaves the services the stack has as they are; never changes or deletes one. Secrets the file names come in `secrets`. Answers once the new briqs are ready, for up to `waitTimeoutMs`, unless `wait: false`.

## Request body

- StackUpBody
  - `file` string, required: The stack file's content, YAML or JSON (briq.yaml)
  - `stack` string: The stack to bring up instead of the file's `stack`: a branch's, a fork's
  - `secrets` object: Values for the secrets the file names as { secret: NAME }: an API key briq cannot generate. Never in the file. A secret without a value here is generated
  - `expose` boolean: Reach the stack from outside briq: database ports get TLS endpoints, and outputs use them and the URLs the file publishes. Waits for the briqs. The file's own `expose` still decides each URL's mode
  - `wait` boolean: Answer once the briqs are ready (healthcheck passed, or process started)
  - `waitTimeoutMs` integer: How long to wait; a briq still creating then is on its way

## Response `200`

ok

- StackUpResult
  - `stack` string, required
  - `briqs` Briq[], required: Every briq of the file's services, in file order: made now, or there already
    - `id` string, required
    - `teamId` string, required
    - `stackId` string, required
    - `name` string, required
    - `image` string, required
    - `size` 'nano' | 'small' | 'medium' | 'large', required
    - `state` 'creating' | 'running' | 'stopping' | 'stopped' | 'sleeping' | 'starting' | 'destroying' | 'destroyed' | 'error', required
    - `internalHost` string, required: Its address on the team's private network
    - `endpoints` object[], required: Its URL, once published (one at most), and its TCP endpoint, once published
      - `id` string, required
      - `port` integer, required
      - `protocol` 'http' | 'postgres' | 'mysql' | 'redis' | 'mongodb' | 'amqp' | 'bolt' | 'grpc': http: a URL; a database protocol (postgres, mysql, redis, mongodb, amqp, bolt, grpc): a TCP endpoint, reachable from outside over TLS, url is its address without the password
      - `mode` 'public' | 'private', required: public: anyone can open the URL; private: only whoever has the URL, which carries a secret checked before a request reaches the briq
      - `url` string, uri, required
    - `ports` integer[]
    - `databasePorts` object[]: Its recipe's database ports: briq_expose one with its protocol for a TCP endpoint
      - `port` integer, required
      - `protocol` 'http' | 'postgres' | 'mysql' | 'redis' | 'mongodb' | 'amqp' | 'bolt' | 'grpc', required
    - `expose` integer, nullable
    - `env` object: As declared: plain values, and { secret: NAME } for secrets, whose values never appear
    - `createdAt` string, date-time, required
    - `startedAt` string, date-time, nullable, required: When its current run started (its last run, while it is not running)
    - `sleep` string, required: When the briq goes to sleep: after this long without use (agent calls, visits to its stack's URLs). A string: "30m", "3h", "7d" or "never", never a number. A sleeping briq keeps its disk, costs nothing for compute, and the next use wakes it. "never" keeps it always on (Pro plan and above)
    - `sleepsAt` string, date-time, nullable, required: When it goes to sleep unless it is used before then: every use moves this later. Null when it is not running or never sleeps
    - `lastUsedAt` string, date-time, nullable, required
    - `costCentsSoFar` number, required: Euro cents billed so far, fractions of a cent included
    - `error` string, nullable, required
    - `destroysAt` string, date-time, nullable: When a briq in error is destroyed automatically; null in any other state
    - `stoppedReason` 'idle' | 'cap' | 'credits' | 'user' | 'provider' | 'exited', nullable: Why it is stopped or sleeping. idle and provider: asleep, the next call or visit wakes it. cap and credits: a limit, asleep again once it has cleared. user and exited: only briq_start runs it again
    - `lastExit` object, nullable: The last time its process ended on its own: exit code (128 + n for signal n), whether it ran out of memory, and when
      - `code` integer, required
      - `oomKilled` boolean, required
      - `at` string, date-time, required
    - `files` object[]: Its boot files, by path and size; their content is not returned
      - `path` string, required
      - `bytes` integer, required
    - `forkedFrom` string, nullable
  - `created` string[], required: The services this up made
  - `existing` string[], required: The services the stack had: left as they are
  - `warnings` string[]: An endpoint the file asks for that could not be opened yet; with `expose`, a briq not running whose outputs stay internal
  - `outputs` object, required: Each recipe's connection strings, the secrets briq generated, and `<briq>:URL` for each published service. A key two services both have is `<briq>:<KEY>`
  - `costLine` string, required

## Other responses

- `400`: validation
- `401`: unauthorized
- `402`: policy_violation or quota_exceeded (the key's policy), or payment_required (no credits: retrying cannot help)
- `403`: forbidden, or plan_limit (the team's plan does not allow it)
- `404`: not found
- `409`: invalid_state: not possible in the briq's current state; the message says why
- `413`: validation: the body, the command or its output is too large
- `429`: rate limited: retry after the `retry-after` header
- `502`: provider_error: the infrastructure refused the change
- `503`: provider_error: the infrastructure did not answer; retry in a moment

## Changes

- **2026-10-19** `609b424459cb`: 1 info
  - added the new optional request property `expose`

[Operation history](https://skmtc.dev/briq/apis/briq-api/changes/v1/stacks/up/post.md)

---

[API](https://skmtc.dev/briq/apis/briq-api.md) · [All operations](https://skmtc.dev/briq/apis/briq-api/llms.txt) · [OpenAPI document](https://skmtc.dev/briq/apis/briq-api/revisions/609b424459cb?raw)