Make your first API call

Goal: Send one test run with curl and read its receipt. A test run (the API calls it Echo, mode: "echo") checks your API key, the submit request, the status read, and the receipt read. It does not call a model, so it has no platform fee and no model cost. A live run has a platform fee when Millwork accepts it, plus model usage. Read Model access and billing before your first live run. You are done when: the run’s status is completed, the receipt’s mode is echo, and selected_arm is null. A receipt is the record of a run without its prompt or output. This diagram shows the three requests your app sends and what Millwork returns for each.

Before you begin

Your organization is approved for the private preview.
Your organization API key is configured in this terminal.
You have curl and jq.
Your organization has room in its run quota. Test runs are free, but count toward the monthly run quota and have a daily limit.

export MILLWORK_API_URL="https://api.getmillwork.dev/v1"
export MILLWORK_API_KEY="$SOLVERAPI_API_KEY"

Submit the test run

Choose one request key and keep it for this run:

export REQUEST_KEY="echo-$(date +%s)"

The Idempotency-Key header carries this request key. If the response is lost, repeat only the request below with the same key and body.

if ! curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $MILLWORK_API_KEY" \
  --header "Idempotency-Key: $REQUEST_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "mode": "echo",
    "task": { "objective": "Check the Millwork API lifecycle." },
    "policy": {
      "data_classes": ["public"],
      "budget": { "max_cost_usd": 1, "max_runtime_s": 30 }
    }
  }' \
  --output echo.json \
  "$MILLWORK_API_URL/executions"; then
  echo "The request failed. Read echo.json before retrying." >&2
  exit 1
fi

EXECUTION_ID="$(jq -er '.execution_id' echo.json)" || exit 1

Millwork answers 202 with the new run. The API calls a run an execution. A test run finishes inside the submit request, so its status is already completed. The response, shortened:

{
  "execution_id": "<run ID>",
  "status": "completed",
  "mode": "echo",
  "links": {
    "status": "/v1/executions/<run ID>",
    "events": "/v1/executions/<run ID>/events",
    "receipt": "/v1/receipts/<run ID>"
  },
  "created_at": "<ISO-8601 time>"
}

Save execution_id. The last command stores it in EXECUTION_ID; the next two steps send it.

Read the status

curl --fail-with-body \
  --header "Authorization: Bearer $MILLWORK_API_KEY" \
  "$MILLWORK_API_URL/executions/$EXECUTION_ID" | tee echo-status.json

jq '.status' echo-status.json

Expected result: "completed". For any other value, read the error code before you retry.

Read the receipt

curl --fail-with-body \
  --header "Authorization: Bearer $MILLWORK_API_KEY" \
  "$MILLWORK_API_URL/receipts/$EXECUTION_ID" | tee echo-receipt.json

Print the fields that show this was a test run:

jq '{
  status,
  mode,
  selected_arm: .slices[0].route.selected_arm
}' echo-receipt.json

jq -e '
  .status == "completed" and
  .mode == "echo" and
  ((.slices | length) == 1) and
  (.slices[0].route | has("selected_arm")) and
  (.slices[0].route.selected_arm == null)
' echo-receipt.json >/dev/null && echo "Test run check passed."

Expected result: the last command prints Test run check passed.

Field	Value	What it means
`status`	`completed`	The run finished.
`mode`	`echo`	This was a test run.
`selected_arm`	`null`	Millwork picked no saved model. The API calls a saved model an `arm`.

The receipt does not contain the prompt or any model output, and a test run has no result to fetch.

If a step fails

The submit request returns an error: read the error code in type and fix what it names before you retry. A rejected API key returns 401.
quota_exceeded: check Usage. Wait for the stated reset or for a running task to finish before trying again.
The status is not completed: read the run’s events and its receipt to see what stopped it.

Errors and retries lists each error code and the next step.

Run a model

Send a live task, get model output, and confirm which model and provider answered.

Get started

Provide models

Build

Build safely

SDK and MCP

Make your first API call

Before you begin

If a step fails

Run a model

​Before you begin

​If a step fails

Run a model

Before you begin

If a step fails