---
search:
  tags:
    - Images
    - POST
seo:
  description: >-
    Starts building an image from a recipe, as a job of kind image_build. When
    the job is done, its… Reference for the POST /v1/images endpoint in the Ibby
    API.
sidebar:
  label: Build an image
  badge: POST
title: Build an image
type: openapi-operation
---
Starts building an image from a recipe, as a job of kind `image_build`. When the job is `done`, its `result` is `{ "image_id": "img_..." }`. When it is `failed`, its `error.code` is one of: `build_failed` (The build itself failed, for example a package would not install.), `build_lost` (The platform lost track of the build. Build the recipe again.), `import_check_failed` (The image built, but a module in `import_check` would not import.), `unavailable` (A service behind the API failed. Build the recipe again after a short wait.). New codes may be added. A retry with the same `Idempotency-Key` and body returns the same job, also with 202.

`POST /v1/images`

**Request body** (`application/json`, required)

- `base` (ImageBase, required) — The image the build starts from, pinned by digest.
- `import_check` (string[]) — Modules to import once the packages are installed, as a check that the build works. At most 50. A failed import fails the build.
- `packages` (RecipePackage[], required) — The packages to install, each once, at most 500. Nothing is installed that is not listed with its hash.

Request body example:

```json
{
  "base": {
    "digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
    "reference": "python:3.13-slim"
  },
  "import_check": [
    "numpy"
  ],
  "packages": [
    {
      "hashes": [
        "sha256:0000000000000000000000000000000000000000000000000000000000000000"
      ],
      "name": "numpy",
      "version": "2.3.1"
    }
  ]
}
```

**Responses**

- `202` — The build job.
- `400` — \`invalid\_request\`: The request does not match the contract.
- `401` — \`unauthorized\`: The API key is missing, unknown or revoked.
- `409` — \`in\_progress\`: A call with this \`Idempotency-Key\` is still running, or the sandbox is still being created. Retry later. \`idempotency\_mismatch\`: The \`Idempotency-Key\` was used before with a different body.
- `500` — \`internal\_error\`: The platform failed. A retry may succeed; for a call that creates or writes, retry with the same Idempotency-Key.
- `503` — \`unavailable\`: A service behind the API could not be reached. Retry after a short wait; for a call that creates or writes, with the same Idempotency-Key.

Response example, 202:

```json
{
  "created_at": "2019-08-24T14:15:22Z",
  "error": {
    "code": "build_failed",
    "message": "string"
  },
  "id": "job_9xQ1",
  "kind": "image_build",
  "result": {},
  "status": "accepted",
  "updated_at": "2019-08-24T14:15:22Z"
}
```