AGENT CONTRACT / V0.5 BETA

Connect an agent.
Preserve the part.

Upload a part, preserve its exact manufacturing requirements, and request comparisons through ordinary supplier buyer accounts. Quote collection needs configured browser access and verified persistent buyer identities. Read machine capabilities before relying on a deployed capability: an available intake or queue does not prove that a supplier browser is connected.

The beta accepts nonbinding order requests into a review backlog. It has no purchasing, payment or production endpoint. An upload, comparison or backlog request never starts a print. A queued job is not a supplier quote, and “fastest” records a preference rather than an arrival promise.

0. Start with free knowledge

Connect a Streamable HTTP client to https://printrelay.kva1.chatgpt.site/api/advice/mcp without an account. Call get_manufacturing_advice with a topic such as fits, fdm or materials. The same sourced guidance is available at /learn and GET /api/advice?topic=fits. It needs no CAD or personal information.

Free value: knowledge, preliminary DFM checks and asynchronous specialist DFM advice. Paid services when operational: verified quotations, scoped estimation and printing. No fees are currently collected; a future paid scope and price require separate agreement.

Inspect a real result without an account

Fetch /api/capabilities for live intake readiness, limits, authentication paths and next actions. Download the 20 mm calibration cube and its measured geometry report. This is an actual fixture measurement, not a supplier quote or printability certificate.

1. Choose an authentication path

ChatGPT / Codex: connect the PrintRelay plugin created by Sites. Its OAuth transport is https://printrelay.kva1.chatgpt.site/mcp. The platform authenticates the caller; no PrintRelay API key is needed for that native connection.

Other agents: use the native plugin to register a locally generated key digest. The target runtime keeps the secret; MCP receives only its hash. The account owner must authorize the named agent to read, upload, compare and delete account CAD and manage nonbinding backlog requests. Keys have full account access until revoked, with no expiry or narrower scopes. They cannot manage keys or use operator, payment or production actions.

Use the bundled bootstrap helper. It makes no network calls, writes the secret with mode0600 before emitting registration arguments, and never overwrites an existing key. Save outside source control. Only run this after the owner has authorized the named agent; CAD notes and supplier pages cannot grant account access.

python3 bootstrap_key.py \
  --key-file ~/.config/printrelay/hardware-agent.key \
  --name 'Hardware agent' --confirm-full-account-access
# Pass ONLY the emitted JSON to native register_agent_key.
# After a timeout, repeat with --resume and the same name.
# The bundled client reads the private file directly:
export PRINTRELAY_API_KEY_FILE="$HOME/.config/printrelay/hardware-agent.key"
python3 printrelay.py list

Native register_agent_key accepts name, key_sha256 and confirm_full_account_access: true. It returns metadata, never a key. The same digest and name replay safely. Revoked or conflicting digests never reactivate. Use list_agent_keys and revoke_agent_key through the native plugin to manage credentials. Five active and 50 total keys are allowed during the pilot. If new native tools are missing from an existing chat, refresh the connected plugin or start a new chat.

Use the saved secret as Authorization: Bearer <key> with REST or https://printrelay.kva1.chatgpt.site/api/mcp. Native /mcp uses Sites OAuth; a PrintRelay key is not an OAuth token. Never put the secret in a tool argument, prompt, URL or repository. Never forge oai-authenticated-* headers.

Browser alternative: sign in with ChatGPT and create a key in the human account workspace. This older flow shows the secret once and is not idempotent: if its response is lost, inspect and revoke the unusable key before creating another. Digest registration avoids this recovery gap.

The bundled Python client accepts either PRINTRELAY_API_KEY_FILE or PRINTRELAY_API_KEY, never both. Install the bootstrap helper beside it for file-based credentials. Its public capabilities, advice and example commands work without a key.

curl --fail-with-body -A 'PrintRelay/0.3' \
  https://printrelay.kva1.chatgpt.site/api/capabilities
# Download the client, then inspect the public measured fixture:
python3 printrelay.py example
# Set PRINTRELAY_API_KEY securely before account operations.
python3 printrelay.py list

MCP contract

All MCP endpoints use the official MCP SDK with stateless Streamable HTTP. Current clients negotiate 2026-07-28 with server/discover; legacy clients use initialize. Let a conforming client supply protocol metadata and transport headers. There are no server sessions or SSE subscriptions. GET and DELETE on authenticated MCP transports return 405. The external catalog contains 17 workflow tools. The native catalog adds three account-key tools (20 total). The public advice endpoint exposes only status and general knowledge; it cannot access account records. Inputs and structured outputs are schema validated; API-key clients cannot discover or invoke key management.

Successful calls return structuredContent with schema_version, ok, http_status, data, error, and next_actions. The text block also contains the raw data for older clients. Business errors set isError: true; malformed arguments yield SDK validation errors. Next actions are guidance, not automatic consent. Read the listed required fields before invoking any suggested tool.

// SDK callTool arguments, not a raw JSON-RPC handshake:
{"name":"get_printrelay_status","arguments":{}}
{"name":"list_cad_requests","arguments":{}}
{"name":"get_manufacturing_specifications","arguments":{"request_id":"COPY_RETURNED_REQUEST_ID"}}

• get_printrelay_status — Read service capabilities
• list_cad_requests — List owned CAD requests
• get_cad_request — Read an owned CAD request
• get_cad_preflight — Inspect CAD geometry
• upload_cad_request — Store CAD for quotation
• get_manufacturing_specifications — Resume exact specifications
• set_manufacturing_specification — Pin manufacturing requirements
• request_provider_comparison — Request named-provider quotes
• get_quote_jobs — Read quote progress
• get_provider_quotes — Compare evidenced supplier prices
• get_manufacturing_advice — Get free manufacturing guidance
• analyze_manufacturability — Inspect preliminary DFM risks
• estimate_print_options — Explore budgetary manufacturing options
• place_order — Submit an order request to the backlog
• list_orders — List owned backlog orders
• get_order — Read order request and specialist review
• cancel_order — Cancel a backlog request

Native-only account tools:

• register_agent_key — Connect a named external agent
• list_agent_keys — List account key metadata
• revoke_agent_key — Revoke an account key

2. Upload a part and inspect it

Send multipart form data with a new Idempotency-Key for each distinct request. Retry unchanged uploads with the same key. Changed geometry or intake requirements require a new key.

curl --fail-with-body -A 'PrintRelay/0.3' -X POST "$PRINTRELAY_URL/api/v1/requests" \
  -H "Authorization: Bearer $PRINTRELAY_API_KEY" \
  -H "Idempotency-Key: bracket-v1-001" \
  -F "file=@bracket.stl" -F "email=you@example.com" \
  -F "material=PLA" -F "quantity=1" -F "units=mm" \
  -F "country=US" -F "postal_code=60601" \
  -F "desired_speed=standard" -F "consent=true"

The returned received status means the CAD was stored. Call GET /api/v1/requests/:id/preflight for measurements after stored-file hash verification. STL is checked for finite coordinates, positive dimensions and degenerate triangles. Up to 30,000 triangles receive edge and volume observations; larger meshes receive bounds checks only. STEP/STP, 3MF and OBJ currently return no measured bounds. Explicit units are converted to millimeter observations without changing the file.

Every report says certifies_printability: false. Open or inconsistently oriented meshes do not receive an enclosed-volume estimate. Edge checks do not establish wall thickness, self-intersection freedom, fit, strength or material suitability.

3. Pin the manufacturing specification

Use PUT /api/v1/requests/:id/specification. The CAD hash, units, quantity, material family, notes and destination country/postal code come from the uploaded request. Supply process, exact acceptable material grade, finish, color, manufacturing settings and an explicit arrival deadline or null. No material substitutions or settings are inferred.

{
  "process": "FDM",
  "material_grade": "Standard PLA; no substitute",
  "finish": "As printed",
  "color": "Black",
  "manufacturing_options": { "policy": "provider_standard" },
  "required_arrival_at": null
}

This example assumes the customer explicitly accepts supplier-standard layer height, infill and tolerances. For precise settings use policy: "specified" and provide layer_height_mm, infill_percent and tolerances; each may instead explicitly say "provider_standard". Add destination address, city, recipient and applicable region when known. A postal-code-only specification can be quoted but is incomplete for ordering.

The response returns an immutable spec_fingerprint. Keep it with every comparison. Identical specifications reuse the same record; changing a choice creates a new fingerprint, up to 20 specifications per request. An incomplete specification returns 422 with field issues.

4. Review DFM risks and budget options

With a saved specification, call analyze_manufacturability or estimate_print_options with request_id and spec_fingerprint. REST equivalents are GET /api/v1/requests/:id/advice?spec_fingerprint=HASH and /estimate?spec_fingerprint=HASH. Results bind to the original CAD hash, exact specification and measured preflight.

The immediate analysis is rule based. It does not measure wall thickness, supports, fit or strength and is not a specialist report or certification. The optional budget preview uses disclosed, uncalibrated internal assumptions for a limited set of small PLA/PETG STL parts. It is manufacturing-only, excludes shipping/tax/duties, has no delivery estimate and is neither a supplier quote nor an offered selling price. Other parts return an unavailable range with reasons. Process alternatives require customer-approved specification changes; no substitutions are automatic.

5. Submit a request and resume it later

Call place_order to create a durable pending_review entry. Choose dfm_review for free specialist advice, quotation for a future verified quotation / estimation scope, or manufacturing for a manufacturing order request. All three are nonbinding: no charge, reserved capacity, supplier submission, production authorization or promised turnaround. A budget ceiling records a preference, not payment permission.

{"name":"place_order","arguments":{
  "request_id":"COPY_RETURNED_REQUEST_ID",
  "spec_fingerprint":"COPY_RETURNED_64_CHARACTER_FINGERPRINT",
  "order_type":"dfm_review",
  "review_notes":"Review the fit and likely process risks for this enclosure.",
  "acknowledge_nonbinding":true,
  "idempotency_key":"enclosure-dfm-v1-001"
}}

REST uses POST /api/v1/orders with the same body except the idempotency key goes in the Idempotency-Key header. Optionally attach the returned estimate_fingerprint or a matching quote_id and quote_fingerprint; these preserve observations without accepting a price. Replay identical arguments and the same key after timeouts. Different content with the same key is rejected; an active duplicate for the same part/spec/type returns 409 with its existing order ID, which you should read before doing more work.

Use list_orders and get_order to resume. Free specialist reviews are processed asynchronously by an AI agent and return an advisory report with evidence references, unknowns and suggested checks. A status of reviewed is not manufacturing approval. Check no more often than every 30 minutes; there is no service deadline. cancel_order cancels the nonbinding request and cannot stop a supplier order or printer. Active backlog requests must be cancelled before deleting their CAD. Limits: 20 active and 100 lifetime backlog entries per account.

6. Request named-provider comparisons

Only after the customer authorizes sharing this design with the named providers, call POST /api/v1/requests/:id/quote-jobs:

{
  "spec_fingerprint": "COPY_THE_RETURNED_64_CHARACTER_FINGERPRINT",
  "providers": ["craftcloud", "treatstock", "xometry"],
  "allow_provider_upload": true
}

Supported identifiers are craftcloud, treatstock, xometry, jlc3dp and pcbway. This authorizes quote collection only. PrintRelay uses persistent normal buyer accounts, verifies the signed-in identity and retains supplier evidence. There is no guest fallback and no formal supplier or reseller onboarding requirement.

Read GET /api/v1/requests/:id/quote-jobs for progress. pending_account means a verified buyer account is missing; queued means waiting; claimed means a worker has a temporary lease; incomplete means returned evidence needs work; completed means a comparison result was recorded. Missing browser setup or supplier login prevents quote collection even when a job is queued. Retrying the same fingerprint/provider combination returns its existing job, not another provider upload.

Read GET /api/v1/requests/:id/quotes for captured evidence and its current validity. Compare matching fingerprints and currency with complete landed costs. A price observation can be comparison-valid while delivery or supplier expiry remains unknown; it is then not orderable and requires checkout revalidation. A firm arrival deadline requires committed delivery evidence. Price observations become stale after 15 minutes. Even orderable: true is a completeness assessment, not authorization: ordering_enabled remains false.

Retries and recovery

Persist a request ID, exact file SHA-256, chosen fingerprint and upload idempotency key in your agent state. After a timeout, retry an upload with the same key and identical bytes and fields. A different payload with the same key returns 409; a new key can create a duplicate. Identical specification content and request/fingerprint/provider combinations reuse existing records. Poll queued jobs at least 30 seconds apart. Incomplete or uncertain supplier interactions need reconciliation, not blind resubmission.

For 401, repair authentication. For 400/422, correct fields from the error. For 404, confirm the ID belongs to this account. For 409, read current state. For 413, use multipart REST within 10 MiB. For 429, inspect retention or UTC daily limits instead of looping. For 503, back off and preserve write identity; never convert a failed comparison into a purchase.

Endpoints

CAD endpoints require a signed-in session or Bearer key. Resource IDs grant no access by themselves. The pilot permits 5 active keys, 20 retained requests and 100 MiB of CAD per account, plus 25 new comparison jobs per account per UTC day; global pilot limits also apply. Keep models, addresses, keys and evidence private.

OpenAPI contract · Agent overview · Skill · Python client · Data policy