Build an image

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

Authorization

AuthorizationBearer token (ibk_<public id>_<secret>) · headerrequired

A lane's API key. The lane is taken from the key, never from the request.

Header parameters

Idempotency-Keystring

Makes a retry safe. A retry with the same key and body gets the answer described for this operation; the same key with a different body gets 409 idempotency_mismatch. Keys are kept for 24 hours. The SDKs send a fresh key on every call they may retry.

min length 1 · max length 255

Request body

requiredapplication/json

baseImageBaserequired

The image the build starts from, pinned by digest.

Show properties

digeststringrequired

The digest the base image is pinned to. The build uses exactly this image, whatever reference later points at.

matches ^sha256:[0-9a-f]{64}$

referencestringrequired

The base image's name and tag in a public registry, for people to read. The digest decides what is built.

min length 1 · max length 255 · matches ^[a-z0-9][a-z0-9._/:-]*$

import_checkstring[]

Modules to import once the packages are installed, as a check that the build works. At most 50. A failed import fails the build.

max items 50

packagesRecipePackage[]required

The packages to install, each once, at most 500. Nothing is installed that is not listed with its hash.

max items 500

Show properties

Array of RecipePackage

hashesstring[]required

Every hash this exact version may have, one per file it is published as. A downloaded file whose hash is not listed fails the build.

min items 1 · max items 64

namestringrequired

min length 1 · max length 128 · matches ^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$

versionstringrequired

One exact version. Ranges are not allowed.

min length 1 · max length 64 · matches ^[A-Za-z0-9][A-Za-z0-9.+!_-]*$

Responses

202

The build job.

created_atstring<date-time>required

A UTC time in RFC 3339 form.

errorJobError | nullrequired

Set when status is failed.

Show properties

Any of:

JobError

codestringrequired

A stable code for why the job failed. New codes may be added, so treat an unknown one as a failure. Known codes for kind image_build: 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.).

messagestringrequired

null

null

idstringrequired

The job id, job_....

kindstringrequired

What the job does. Each kind documents its own result.

resultobject | nullrequired

Set when status is done. Its shape depends on kind.

Show properties

Any of:

object

object

null

null

statusJobStatusrequired

Moves forward only. done, failed and cancelled are final.

Allowed:acceptedrunningdonefailedcancelled

updated_atstring<date-time>required

A UTC time in RFC 3339 form.

400

invalid_request: The request does not match the contract.

errorErrorDetailrequired

Show properties

codestringrequired

A stable, machine-readable code. Known codes: env_name_refused, file_not_found, file_too_large, idempotency_mismatch, image_not_built, in_progress, internal_error, invalid_request, lane_limit, name_in_use, not_found, payload_too_large, resources_over_cap, region_mismatch, sandbox_stopped, unavailable, store_prefix_refused, store_unavailable, unauthorized. New codes may be added, so treat an unknown one by its HTTP status.

messagestringrequired

A sentence for a person. Do not parse it.

request_idstringrequired

The same value as the X-Request-Id header.

401

unauthorized: The API key is missing, unknown or revoked.

errorErrorDetailrequired

Show properties

codestringrequired

messagestringrequired

A sentence for a person. Do not parse it.

request_idstringrequired

The same value as the X-Request-Id header.

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.

errorErrorDetailrequired

Show properties

codestringrequired

messagestringrequired

A sentence for a person. Do not parse it.

request_idstringrequired

The same value as the X-Request-Id header.

500

internal_error: The platform failed. A retry may succeed; for a call that creates or writes, retry with the same Idempotency-Key.

errorErrorDetailrequired

Show properties

codestringrequired

messagestringrequired

A sentence for a person. Do not parse it.

request_idstringrequired

The same value as the X-Request-Id header.

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.

errorErrorDetailrequired

Show properties

codestringrequired

messagestringrequired

A sentence for a person. Do not parse it.

request_idstringrequired

The same value as the X-Request-Id header.

Request

curl -X POST 'https://api.ibby.ai/v1/images' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "base": {
    "digest": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
    "reference": "python:3.13-slim"
  },
  "import_check": [
    "numpy"
  ],
  "packages": [
    {
      "hashes": [
        "sha256:0000000000000000000000000000000000000000000000000000000000000000"
      ],
      "name": "numpy",
      "version": "2.3.1"
    }
  ]
}'

const response = await fetch("https://api.ibby.ai/v1/images", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Accept": "application/json",
    "Content-Type": "application/json"
  },
  body: "{\n  \"base\": {\n    \"digest\": \"sha256:0000000000000000000000000000000000000000000000000000000000000000\",\n    \"reference\": \"python:3.13-slim\"\n  },\n  \"import_check\": [\n    \"numpy\"\n  ],\n  \"packages\": [\n    {\n      \"hashes\": [\n        \"sha256:0000000000000000000000000000000000000000000000000000000000000000\"\n      ],\n      \"name\": \"numpy\",\n      \"version\": \"2.3.1\"\n    }\n  ]\n}"
});

import requests

response = requests.post(
    "https://api.ibby.ai/v1/images",
    headers={
        "Authorization": "Bearer YOUR_TOKEN",
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    data="{\n  \"base\": {\n    \"digest\": \"sha256:0000000000000000000000000000000000000000000000000000000000000000\",\n    \"reference\": \"python:3.13-slim\"\n  },\n  \"import_check\": [\n    \"numpy\"\n  ],\n  \"packages\": [\n    {\n      \"hashes\": [\n        \"sha256:0000000000000000000000000000000000000000000000000000000000000000\"\n      ],\n      \"name\": \"numpy\",\n      \"version\": \"2.3.1\"\n    }\n  ]\n}",
)

Response

{
  "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"
}

{
  "error": {
    "code": "sandbox_stopped",
    "message": "string",
    "request_id": "string"
  }
}

{
  "error": {
    "code": "sandbox_stopped",
    "message": "string",
    "request_id": "string"
  }
}

{
  "error": {
    "code": "sandbox_stopped",
    "message": "string",
    "request_id": "string"
  }
}

{
  "error": {
    "code": "sandbox_stopped",
    "message": "string",
    "request_id": "string"
  }
}

{
  "error": {
    "code": "sandbox_stopped",
    "message": "string",
    "request_id": "string"
  }
}