---
title: "Prove which build the running process loaded"
method: POST
path: "/v1/diagnostics/build-receipt"
tags: ["System"]
---

# Prove which build the running process loaded

`POST /v1/diagnostics/build-receipt`

## Request

- Base URL: `http://localhost:9998`
- URL: `http://localhost:9998/v1/diagnostics/build-receipt`
- Auth: HTTP bearer

Binds the running ToolPiper process to a declared build. Send either
`{"discover": true}`, which lists the bundle's loaded Mach-O images and
their UUIDs, or a build declaration (`buildId`, `outputs`, `images`),
which is checked against the process: every declared output's SHA-256
digest is re-read, every declared image must be loaded with its declared
UUID, and the process must not change while it is read. The body is
limited to 64 KiB. Only one receipt is collected at a time.

## Request body

- union
  - object
    - `discover` true, required
  - BuildDeclaration: A declared build. `outputs` holds 2 to 16 entries and must include `bundle` (path `.`) and `executable`; `images` holds 1 to 256 entries with unique paths and UUIDs.
    - `buildId` string, required
    - `outputs` object, required
    - `images` BuildImage[], required
      - `path` string, required: Bundle-relative path of a Mach-O image.
      - `uuid` string, uuid, required: Lowercase LC_UUID of the image.

## Response `200`

A process receipt for a declaration, or the discovered image list

- union
  - BuildProcessReceipt: Proof that the running process loaded the declared build.
    - `outputs` object, required: Output name to the SHA-256 digest observed on disk.
    - `loadedImageUUIDs` string[], required
    - `buildId` string, required
    - `loadedOutputsVerified` boolean, required
    - `generationVerified` boolean, required
    - `pid` integer, required
    - `generation` string, required: `<pid>-<start seconds>-<start microseconds>`; identifies this process instance.
    - `startedAt` string, date-time, required: Process start time with microsecond precision.
  - object
    - `images` BuildImage[], required
      - `path` string, required: Bundle-relative path of a Mach-O image.
      - `uuid` string, uuid, required: Lowercase LC_UUID of the image.

## Other responses

- `400`: Invalid request
- `409`: A receipt is already being collected (`receipt_in_progress`), or the loaded process could not be verified against the declaration (`receipt_unavailable`)

---

[API](https://skmtc.dev/modelpiper/apis/toolpiper-api.md) · [All operations](https://skmtc.dev/modelpiper/apis/toolpiper-api/llms.txt) · [OpenAPI document](https://skmtc.dev/modelpiper/apis/toolpiper-api/revisions/6722bf56385c?raw)