Run a model

Goal: Submit one public test task using a model available to your organization. You are done when: the run completes, the result contains model output, and the receipt names the model and provider that answered. At the end, you will have three records:

a run showing final status;
a result containing model output; and
a receipt showing what ran.

Millwork is not a drop-in chat endpoint. You send a task and limits. Millwork selects from the registered models that match them.

Before you begin

Your Millwork organization is approved.
You created an organization API key in the dashboard.
You have curl and jq.
Your account has enough credit and quota for a live run.

Not ready for a provider call? Complete the first API call first.

export MILLWORK_API_URL="https://api.getmillwork.dev/v1"
export MILLWORK_API_KEY="<organization API key>"
export RUN_SUFFIX="$(date +%s)"

Use only public information or test data created for this run. Read Data and credentials before sending a live task.

Never paste a provider key into a model registration, run request, support message, or documentation playground. Provider credentials use a separate secure connection flow.

1. Choose an available model

curl --fail-with-body \
  --header "Authorization: Bearer $MILLWORK_API_KEY" \
  "$MILLWORK_API_URL/model-catalog" > catalog.json

jq -r '.models | to_entries[] |
  "\(.key): \(.value.model.display_name // .value.model.model_key) | provider: \(.value.source.source_id) | access: \(.value.connection.access_lane)"' \
  catalog.json

Expected result: models contains the models your organization can use now. Choose the number shown at the start of one row:

export MODEL_INDEX=0
jq --argjson i "$MODEL_INDEX" -e '.models[$i]' catalog.json

If the catalog is empty, connect a provider or email support to ask whether a model provided by Millwork is available.

2. Add the model to Millwork

Add the selected catalog model to your organization before running it. The /arms endpoint performs this step; arm is the API field name for the saved model. Send the selected model’s registration template without changing it.

jq --argjson i "$MODEL_INDEX" \
  '.models[$i].arm_registration_template' \
  catalog.json > arm-request.json

curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $MILLWORK_API_KEY" \
  --header "Idempotency-Key: arm-$RUN_SUFFIX" \
  --header "Content-Type: application/json" \
  --data @arm-request.json \
  "$MILLWORK_API_URL/arms" | tee arm-response.json

Expected result: the response contains an arm_id and a ready registered model. If it does not, read status_reason and choose another catalog row. Registering a model makes it available to routing. It does not force Millwork to choose it when other registered models also match the task. The receipt confirms what answered.

3. Submit a live task

curl --fail-with-body \
  --request POST \
  --header "Authorization: Bearer $MILLWORK_API_KEY" \
  --header "Idempotency-Key: run-$RUN_SUFFIX" \
  --header "Content-Type: application/json" \
  --data '{
    "mode": "live",
    "task": {
      "objective": "Explain idempotency keys in one short sentence.",
      "inputs_ref": {
        "kind": "inline_json",
        "json": { "audience": "API developers" }
      }
    },
    "policy": {
      "data_classes": ["public"],
      "budget": { "max_cost_usd": 1, "max_runtime_s": 60 },
      "cost_coefficient": 0.5,
      "on_eval": []
    }
  }' \
  "$MILLWORK_API_URL/executions" | tee execution.json

EXECUTION_ID="$(jq -r '.execution_id' execution.json)"

If you do not provide verifier_id, Millwork uses its built-in basic output check. A live run also needs available credit and quota. If the API returns insufficient_credit, add credit in Usage & spend before retrying.

max_cost_usd can stop Millwork from starting another provider call after recorded spend reaches the limit. It cannot cancel a call already in progress or reverse its cost.

4. Wait for a final status

STATUS="unknown"
DEADLINE=$((SECONDS + 90))

while [ "$SECONDS" -lt "$DEADLINE" ]; do
  if ! curl --fail-with-body \
    --header "Authorization: Bearer $MILLWORK_API_KEY" \
    --output execution-status.json \
    "$MILLWORK_API_URL/executions/$EXECUTION_ID"; then
    echo "The status request failed. Read execution-status.json before retrying." >&2
    exit 1
  fi

  STATUS="$(jq -r '.status' execution-status.json)"

  case "$STATUS" in
    completed|failed|cancelled|expired) break ;;
    *) sleep 2 ;;
  esac
done

if [ "$STATUS" != "completed" ] &&
   [ "$STATUS" != "failed" ] &&
   [ "$STATUS" != "cancelled" ] &&
   [ "$STATUS" != "expired" ]; then
  echo "The run did not finish within 90 seconds. Keep the run ID and check it again later." >&2
  exit 1
fi

echo "$STATUS"

Final statuses are completed, failed, cancelled, and expired.

5. Read the result and receipt

Fetch the result only when the status is completed:

if [ "$STATUS" = "completed" ]; then
  curl --fail-with-body \
    --header "Authorization: Bearer $MILLWORK_API_KEY" \
    --output result.json \
    "$MILLWORK_API_URL/executions/$EXECUTION_ID/result"
fi

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

If the run failed, read the events before retrying:

curl --fail-with-body \
  --header "Authorization: Bearer $MILLWORK_API_KEY" \
  "$MILLWORK_API_URL/executions/$EXECUTION_ID/events"

Check your work

the registered model is ready;
the run reaches completed;
the result contains model output and may include an expiry time; and
the receipt records provider, route, attempts, usage, and checks without the prompt or output.

Compare the requested and provider-reported model:

jq '{
  requested: .model_provenance.requested.upstream_ref,
  provider_reported: .model_provenance.resolved.upstream_ref,
  provider: .model_provenance.source.source_id
}' result.json

What this confirmed

Your application submitted one task format without a provider credential. Millwork selected an eligible registered model. The result contains the useful output. The receipt records the model, provider, attempts, usage, and checks without copying the task or output.

Next steps

Connect a provider

Use an account your organization owns.

Retry safely

Recover from a network failure without creating duplicate work.

Read the run record

Store the output and receipt separately.

Review data limits

Confirm what the private preview may process.

Common fixes

What happened	What to do
Catalog is empty	Connect a provider, or ask support whether a model provided by Millwork is available.
`insufficient_credit`	Add credit before submitting another live run.
Run failed	Read its events and receipt before retrying.
No result	Check the final status. Only completed live work can have a result.

For retry rules and common errors, read Errors and retries.

Get started

Build

Build safely

Before you begin

1. Choose an available model

2. Add the model to Millwork

3. Submit a live task

4. Wait for a final status

5. Read the result and receipt

Check your work

What this confirmed

Next steps

Connect a provider

Retry safely

Read the run record

Review data limits

Common fixes

​Before you begin

​1. Choose an available model

​2. Add the model to Millwork

​3. Submit a live task

​4. Wait for a final status

​5. Read the result and receipt

​Check your work

​What this confirmed

​Next steps

Connect a provider

Retry safely

Read the run record

Review data limits

​Common fixes

Before you begin

1. Choose an available model

2. Add the model to Millwork

3. Submit a live task

4. Wait for a final status

5. Read the result and receipt

Check your work

What this confirmed

Next steps

Common fixes