---
title: "POST /internal/ci-builds/{build_id}/claim"
method: POST
path: "/internal/ci-builds/{build_id}/claim"
tags: ["CI runner"]
---

# POST /internal/ci-builds/{build_id}/claim

`POST /internal/ci-builds/{build_id}/claim`

## Request

- Base URL: `/api` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/api/internal/ci-builds/{build_id}/claim`
- Auth: none declared

## Path parameters

- `build_id` string, required

## Request body

- RunnerClaim
  - `identity_token` string, password, required: A credential. Write-only: it is never returned, and the AI assistant supplies it through a secret slot instead of typing it into the conversation.

## Response `200`

- RunnerWork
  - `registry_credentials` RemotePullCredentials: Registry credentials to forward to the worker's `POST /agent/images/pull` call. Mirrors the wire shape of `temps_agent::RegistryCredentials` field for field; `temps-deployer` does not depend on `temps-agent` (the same reason `import_image` below builds its own request rather than sharing a DTO type), so this struct only needs to serialize to the JSON body the agent handler already deserializes.
    - `identity_token` string, password: A credential. Write-only: it is never returned, and the AI assistant supplies it through a secret slot instead of typing it into the conversation.
    - `password` string, password: A credential. Write-only: it is never returned, and the AI assistant supplies it through a secret slot instead of typing it into the conversation.
    - `server_address` string, nullable
    - `username` string, nullable
  - `registry_tag` string, required
  - `run_id` string, required
  - `spec` BuildSpec, required: Paths are relative to the root of the tar archive. Deliberately not `Debug`: [`BuildSpec::build_args`] holds variable values, and a stray `{:?}` must not be able to put them in a log.
    - `build_args` object: Values for the Dockerfile's `ARG` instructions, applied exactly as `docker build --build-arg` would be (protocol v2). The control plane decides which values may leave it -- never one marked secret or a platform credential -- and sends only names the Dockerfile declares. They travel inside this spec over the node's authenticated build channel and are held in memory on both sides; neither side writes them to disk or to a log.
    - `cache_namespace` string, nullable: BuildKit's predefined `BUILDKIT_CACHE_MOUNT_NS`: the control plane's per-project/environment/ref namespace for `RUN --mount=type=cache`. Not a project variable and not a credential, so it is the one build argument a worker receives. Without it, every project built on the same worker shares writable cache mounts. Optional on the wire: an agent that predates it ignores the field and builds as before.
    - `dockerfile` string, required
    - `image_name` string, required
    - `platform` string, nullable
    - `version` integer, required
  - `timeout_seconds` integer, required
  - `token` string, required

## Other responses

- `403`: Runner identity rejected
- `409`: Build already claimed or terminal
- `425`: Provider run has not been recorded; retry claim
- `500`: Storage failed

## Changes

> 81 revisions in range; 1 not diffed.

- **2026-10-20** `79089e9f49ee`: 5 breaking
  - the `identity_token` request property format changed from no format to `password`
  - added `#/components/schemas/SecretString, subschema #2` to the `registry_credentials/oneOf[#/components/schemas/RemotePullCredentials]/identity_token` response property `oneOf` list for the response status `200`
  - added `#/components/schemas/SecretString, subschema #2` to the `registry_credentials/oneOf[#/components/schemas/RemotePullCredentials]/password` response property `oneOf` list for the response status `200`
  - the `registry_credentials/oneOf[#/components/schemas/RemotePullCredentials]/identity_token` response's property type changed from `string, null` to no type for status `200`
  - …1 more
- **2026-10-17** `de8eaf663007`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/gotempsh/apis/temps/changes/internal/ci-builds/:build_id/claim/post.md)

---

[API](https://skmtc.dev/gotempsh/apis/temps.md) · [All operations](https://skmtc.dev/gotempsh/apis/temps/llms.txt) · [OpenAPI document](https://skmtc.dev/gotempsh/apis/temps/revisions/ab6d5d19e930?raw)