fixRAgent triage API

{
  "diagnosis_id": "1abde77c-4b71-42fc-9dc1-1596b0d9901e",
  "engine_version": "engine-v2-vote-1.0.0",
  "rubric_version": "v1.1-2026-09-11",
  "config_id": "fast-a1v11-gemini-3.5-flash-lite-2026-09-12",
  "config_source": {
    "fallback_used": false
  },
  "agreement": {
    "mode": "fast",
    "n": 3,
    "k": 3,
    "decided": true
  },
  "core": {
    "is_building_asset": true,
    "asset_type": "Copper water supply pipe",
    "photo_subject": "Copper plumbing pipe with an active pinhole leak and severe corrosion at the elbow joint",
    "fault_detected": true,
    "fault_visible_in_photo": true,
    "fault_summary": "An active continuous plumbing leak is spraying from a corroded copper pipe elbow joint in the basement.",
    "tier": "EMERGENCY",
    "criterion_1_fired": false,
    "safety_hazard": true,
    "hazard_detail": "active-loss emergency: Continuous active spraying and dripping of water from the pressurized copper pipe joint.",
    "trade_required": "Plumber"
  },
  "callback_url": "/api/outcome?diagnosis_id=1abde77c-4b71-42fc-9dc1-1596b0d9901e",
  "extended": {
    "observations": []
  }
}

Make a request

POST /api/triage — one photo in, one triage out. Three steps:

1. Base64 the photo (JPEG, PNG or WebP; 1 KB to 3 MB decoded) and put it in the image field of a JSON body.
2. Send it with your demo key in the x-triage-key header. ?config=fast reads the photo three times — that is what production served on the one call measured on 13 Sep 2026 at 13:36:18Z (Parameters has the reading), and agreement.n on your reply says how many reads answered. ?config=deep reads it five times. Both report how many of those reads agreed. &extended=1 adds the rest of the contract.
3. Read core (the twenty fields below), keep diagnosis_id, and when you find out what it turned out to be, POST that to callback_url.

curl -X POST "https://fixragent.com/api/triage?config=fast&extended=1" \
  -H "Content-Type: application/json" \
  -H "x-triage-key: $FIXRAGENT_KEY" \
  -d "{\"image\":\"$(base64 -w0 photo.jpg)\",\"mimeType\":\"image/jpeg\"}"

curl -fsSL https://fixragent.com/sdk/js/index.mjs -o fixragent-triage.mjs

import { triage } from './fixragent-triage.mjs';
const reply = await triage(await readFile('photo.jpg'), { key: process.env.FIXRAGENT_KEY, config: 'fast' });
console.log(reply.core.tier, reply.core.trade_required, reply.core.resident_explanation);

curl -fsSL https://fixragent.com/sdk/python/fixragent_triage/__init__.py -o fixragent_triage.py

from fixragent_triage import triage
reply = triage(open('photo.jpg', 'rb').read(), key=os.environ['FIXRAGENT_KEY'], config='fast')
print(reply['core']['tier'], reply['core']['trade_required'], reply['core']['resident_explanation'])

The three ways make the same request and return the same JSON. The two clients take the photo as bytes, a base64 string or a data URL, send your key as x-triage-key, and turn a refused reply into an error that carries the status, the API's own error code, its sentence and the Retry-After seconds. The clients section below has the options, the outcome call and the Spanish switch; the MCP tool is the fourth way, for an agent. To use fixRAgent inside Claude, ChatGPT, Cursor or Gemini, follow the setup for your AI assistant.

{
  "diagnosis_id": "cce64cbc-97b2-410d-a761-2a8d65d570ad",
  "engine_version": "engine-v2-vote-1.0.0",
  "rubric_version": "v1.1-2026-09-11",
  "config_id": "fast-a1v11-gemini-3.5-flash-lite-2026-09-12",
  "config_source": {
    "candidates_file": "api/_engine-v2-candidates.json",
    "candidates_file_present": true,
    "requested": "fast",
    "fallback_used": false,
    "fallback_reason": null,
    "warning": null,
    "vote": true
  },
  "agreement": {
    "mode": "fast",
    "n": 3,
    "k": 3,
    "decided": true,
    "votes": {
      "fault": 0,
      "no_fault": 3,
      "no_verdict": 0
    },
    "vote_rule": "decided when the majority verdict has k >= ceil(n/2) parsed votes; n = reads attempted, failed reads count in n and never in k; a tie is never decided; undecided re-votes once",
    "re_voted": false,
    "reported_round": 1,
    "rounds": [
      {
        "round": 1,
        "n": 3,
        "reads_parsed": 3,
        "read_failures": [],
        "k": 3,
        "decided": true,
        "votes": {
          "fault": 0,
          "no_fault": 3,
          "no_verdict": 0
        },
        "reason": "k >= ceil(n/2)",
        "reported": true
      }
    ],
    "reads_attempted_total": 3,
    "majority_verdict": false,
    "need": 2,
    "verdict_field": "grounded fault_detected (contract R1 visible-in-photo + R3 taxonomy class and summary), majority per a2_selfcons_v11 over parsed reads",
    "delivered_matches_majority": true,
    "applicable": true
  },
  "callback_url": "/api/outcome?diagnosis_id=cce64cbc-97b2-410d-a761-2a8d65d570ad",
  "callback": {
    "method": "POST",
    "url": "/api/outcome",
    "note": "api/outcome.js reads diagnosis_id from the JSON BODY on POST; the query string on callback_url is there so the link identifies the diagnosis to a human and in logs, not because the endpoint reads it.",
    "required_body": {
      "diagnosis_id": "cce64cbc-97b2-410d-a761-2a8d65d570ad",
      "outcome": [
        "fixed",
        "not_fixed",
        "partial"
      ],
      "reported_via": [
        "results_screen",
        "scan_log",
        "triage_link"
      ]
    }
  },
  "core": {
    "is_building_asset": true,
    "asset_type": "HVAC Air Handler and Furnace",
    "asset_category": "HVAC",
    "photo_subject": "HVAC air handler and furnace unit with connected ductwork and piping",
    "report_photo_agreement": null,
    "fault_detected": false,
    "fault_visible_in_photo": false,
    "fault_summary": "",
    "fault_classes": [],
    "severity": "P4",
    "tier": "WHENEVER",
    "criterion_1_fired": false,
    "tier_forced_by": null,
    "visible_wiring": false,
    "water_near_electrical": false,
    "safety_hazard": false,
    "hazard_detail": null,
    "trade_required": null,
    "confidence": 1,
    "resident_explanation": "Your HVAC system is currently in a healthy state with no visible faults or active damage."
  },
  "provenance": {
    "contract_version": "v1-DRAFT-2026-09-10",
    "models": {
      "identification": "gemini-3.5-flash-lite",
      "reasoning": "gemini-3.5-flash-lite"
    },
    "temperature": 0.2,
    "prompt_hash": "b52b0e83c8d01ccb",
    "prompt_base": "api/_engine-v2-fast.json system_prompt (sha256 93f5cb191f1c14d46ab33a003622fe94e32feb069e29c61fb69c3c0be70d3f56) + user_text — the run-2 a1_rubric_v11 export, held to the harness by qa/engine-v2-fast/check-export-drift.py; the resident report, when sent, rides in the user text (api/_engine-v2-fast.js USER_TEXT_WITH_REPORT, unmeasured variant)",
    "agreement": {
      "mode": "fast",
      "n": 3,
      "k": 3,
      "decided": true,
      "votes": {
        "fault": 0,
        "no_fault": 3,
        "no_verdict": 0
      },
      "vote_rule": "decided when the majority verdict has k >= ceil(n/2) parsed votes; n = reads attempted, failed reads count in n and never in k; a tie is never decided; undecided re-votes once",
      "re_voted": false,
      "reported_round": 1,
      "rounds": [
        {
          "round": 1,
          "n": 3,
          "reads_parsed": 3,
          "read_failures": [],
          "k": 3,
          "decided": true,
          "votes": {
            "fault": 0,
            "no_fault": 3,
            "no_verdict": 0
          },
          "reason": "k >= ceil(n/2)",
          "reported": true
        }
      ],
      "reads_attempted_total": 3,
      "majority_verdict": false,
      "need": 2,
      "verdict_field": "grounded fault_detected (contract R1 visible-in-photo + R3 taxonomy class and summary), majority per a2_selfcons_v11 over parsed reads",
      "delivered_matches_majority": true,
      "applicable": true
    },
    "prompt_addendum": "none — the RUBRIC v1.1 axes and criterion-1 facts are asked for by the exported system prompt and enforced by responseSchema (sha256 559265bb8d66ae4fbe98d756b0f574fb51a042997388c4b58ff630071a04991b); the model is never asked for severity or tier",
    "latency_ms": 4174,
    "photo_sha256": "a4232950f74c029d219eacff3d0f84ad86744c3c584b3c2fdafb49afbfeed913",
    "exif_strip_version": "exif-strip-v3-2026-09-11",
    "model_proposed_severity": null,
    "severity_assigned_by": "server:RUBRIC-v1.1-2026-09-11 via a2_selfcons_v11 vote (assignSeverityV11 on the voted facts)",
    "severity_overwritten": false,
    "vote": {
      "candidate": "a1_rubric_v11",
      "n": 3,
      "rounds": [
        {
          "round": 1,
          "n": 3,
          "reads_parsed": 3,
          "read_failures": [],
          "k": 3,
          "decided": true,
          "votes": {
            "fault": 0,
            "no_fault": 3,
            "no_verdict": 0
          },
          "reason": "k >= ceil(n/2)",
          "reported": true
        }
      ],
      "tally": {
        "n_votes_parsed": 3,
        "n_asked": 3,
        "fault_detected": {
          "true": 0,
          "n": 3,
          "voted": false
        },
        "is_building_asset": {
          "true": 3,
          "n": 3,
          "voted": true
        },
        "n_agreeing": 3,
        "base_pool": "raw-matching agreeing reads",
        "rubric_axes_pool": {
          "indices": [
            0,
            1,
            2
          ],
          "rule": "all reads"
        },
        "fault_classes": {
          "counts": {},
          "voted": []
        },
        "safety_hazard": {
          "true": 0,
          "n": 3,
          "voted": false
        },
        "fault_visible_in_photo": {
          "true": 0,
          "n": 3,
          "voted": false
        },
        "rubric_axes": {
          "hazard_class": {
            "counts": {
              "H0": 3
            },
            "voted": "H0",
            "tie_rule": "outright"
          },
          "active_loss": {
            "counts": {
              "L0": 3
            },
            "voted": "L0",
            "tie_rule": "outright"
          },
          "habitability": {
            "counts": {
              "C0": 3
            },
            "voted": "C0",
            "tie_rule": "outright"
          },
          "deferral_cost": {
            "counts": {
              "D0": 3
            },
            "voted": "D0",
            "tie_rule": "outright"
          }
        },
        "criterion_1": {
          "visible_wiring": {
            "true": 0,
            "n": 3,
            "voted": false,
            "tie_rule": "tie -> FALSE (v1.1 §2.1 uncertain does not fire)"
          },
          "water_near_electrical": {
            "true": 0,
            "n": 3,
            "voted": false,
            "tie_rule": "tie -> FALSE (v1.1 §2.1 uncertain does not fire)"
          }
        },
        "base_vote_index": 0,
        "fault_prose_cleared": [],
        "confidence_agreement_fraction": 1,
        "decision": {
          "n": 3,
          "k": 3,
          "need": 2,
          "decided": true,
          "votes": {
            "fault": 0,
            "no_fault": 3,
            "no_verdict": 0
          },
          "majority_verdict": false,
          "reason": "k >= ceil(n/2)"
        }
      },
      "rubric": {
        "rubric_version": "v1.1-2026-09-11",
        "rubric_v11_sha256": "f5968d73f21b1488da9fb25b1568ed7efdfa7cc888b4cec56b20c2b72a4ee951",
        "rubric_axes": {
          "hazard_class": "H0",
          "active_loss": "L0",
          "habitability": "C0",
          "deferral_cost": "D0",
          "hazard_reason": "none visible",
          "active_loss_reason": "no active leaks or losses visible",
          "habitability_reason": "unit is intact and operational",
          "deferral_reason": "nothing changes in a week"
        },
        "rubric_axes_invalid": {},
        "criterion_1": {
          "visible_wiring": false,
          "water_near_electrical": false,
          "visible_wiring_reason": "none visible",
          "water_near_electrical_reason": "none visible"
        },
        "criterion_1_invalid": {},
        "criterion_1_fired": false,
        "criterion_1_facts_fired": [],
        "severity_reason_row": 7,
        "step": "2:v1-row-7",
        "rubric_p_uncapped": "P4",
        "severity_capped_by": null,
        "tier_forced_by": null,
        "illegal_p1_no_fault": false,
        "severity_source": "assignSeverityV11 on VOTED facts (never voted, never model-emitted)",
        "per_vote_severity": [
          "P4",
          "P4",
          "P4"
        ],
        "severity_final": "P4",
        "tier_final": "WHENEVER"
      },
      "per_read": [
        {
          "fault_detected": false,
          "fault_visible_in_photo": false,
          "fault_classes": [],
          "severity": "P4",
          "tier": "WHENEVER",
          "criterion_1_fired": false,
          "is_building_asset": true,
          "finish_reason": "STOP",
          "attempts": 1,
          "latency_ms": 3989,
          "usage": {
            "prompt_tokens": 9572,
            "output_tokens": 976
          }
        },
        {
          "fault_detected": false,
          "fault_visible_in_photo": false,
          "fault_classes": [],
          "severity": "P4",
          "tier": "WHENEVER",
          "criterion_1_fired": false,
          "is_building_asset": true,
          "finish_reason": "STOP",
          "attempts": 1,
          "latency_ms": 4154,
          "usage": {
            "prompt_tokens": 9572,
            "output_tokens": 1139
          }
        },
        {
          "fault_detected": false,
          "fault_visible_in_photo": false,
          "fault_classes": [],
          "severity": "P4",
          "tier": "WHENEVER",
          "criterion_1_fired": false,
          "is_building_asset": true,
          "finish_reason": "STOP",
          "attempts": 1,
          "latency_ms": 4170,
          "usage": {
            "prompt_tokens": 9572,
            "output_tokens": 1066
          }
        }
      ],
      "read_failures": [],
      "confidence_definition": "agreement fraction on the fault verdict over the reads that parsed (a2_selfcons_v11) — a vote count, not a model number"
    }
  },
  "stored": {
    "degraded": false,
    "table": "diy_guest_scans"
  },
  "warnings": []
}

What the deep configuration adds

?config=deep reads the same photo five times, independently, and tallies the reads fact by fact. The delivered answer is not a single read picked out: the fault verdict is the answer most reads gave (a tie reads no fault); each photo-borne fact — visible_wiring, water_near_electrical — is the answer most reads gave, with a tie reading false, so the EMERGENCY floor never fires on a coin toss; each of the four graded readings is the most common value, a tie taking the lower one except the fuel-gas / carbon-monoxide / exposed-conductor tie, which rounds up; and the urgency is then derived once, in code, from those tallied facts. The prose comes from the read whose own urgency matches the tallied one. A read that failed or returned no verdict counts against agreement — it is in n, never in k — so the engine that fails most cannot read as the most consistent. The reply is decided when the answer most reads gave has at least half the reads asked for (k >= ceil(n/2), stamped on every reply as agreement.vote_rule); a tie is never decided. When the first round is undecided the door takes a second round of reads — the same number again — and reports what it has, with both rounds' counts in agreement.rounds and a sentence in warnings; so a deep call can cost two rounds, and says when it did. ?config=fast is the same tally over three reads.

{
  "diagnosis_id": "2a0a447e-9ef1-4ec2-bde0-46ef5e7088bb",
  "config_id": "engine-v2.deep.gemini-3-5-flash-lite.a1_rubric_v11.n5",
  "agreement": {
    "mode": "deep",
    "n": 5,
    "k": 5,
    "decided": true,
    "votes": {
      "fault": 0,
      "no_fault": 5,
      "no_verdict": 0
    },
    "vote_rule": "decided when the majority verdict has k >= ceil(n/2) parsed votes; n = reads attempted, failed reads count in n and never in k; a tie is never decided; undecided re-votes once",
    "re_voted": false,
    "reported_round": 1,
    "rounds": [
      {
        "round": 1,
        "n": 5,
        "reads_parsed": 5,
        "read_failures": [],
        "k": 5,
        "decided": true,
        "votes": {
          "fault": 0,
          "no_fault": 5,
          "no_verdict": 0
        },
        "reason": "k >= ceil(n/2)",
        "reported": true
      }
    ],
    "reads_attempted_total": 5,
    "majority_verdict": false,
    "need": 3,
    "verdict_field": "grounded fault_detected (contract R1 visible-in-photo + R3 taxonomy class and summary), majority per a2_selfcons_v11 over parsed reads",
    "delivered_matches_majority": true,
    "applicable": true
  },
  "core": {
    "severity": "P4",
    "tier": "WHENEVER",
    "criterion_1_fired": false,
    "tier_forced_by": null,
    "water_near_electrical": false,
    "visible_wiring": false
  }
}

Try it without a key

A mock server replays the captured replies above so you can wire up a client before a key arrives. It does not run the engine and it ignores the photo you send; it matches on the path and the query string only. It also ignores every header, including x-triage-key — a wrong key still gets a 200 — and a POST with no query string returns the five-read reply, so do not test your key handling or your query handling against it (measured 13 Sep 2026).

curl -X POST "https://b1442b0b-4a7a-4135-ab4d-9c4b9c1ab0d2.mock.pstmn.io/api/triage?config=fast&extended=1" \
  -H "Content-Type: application/json" -d '{"image":"AAAA"}'

config=fast returns the three-read reply, config=deep the five-read reply, in full. The same requests and examples are in the Postman collection file (Collection v2.1 — import it, then point baseUrl at the mock or at https://fixragent.com). The file is generated from the captured replies by qa/api-launch-kit/build-postman.js, so it cannot say something the handler did not. The Postman environment file points the same requests at production: import it beside the collection, put your key in the environment's key variable (the one marked secret), switch the environment on, and the fast request runs for real.

The clients: JavaScript and Python

Two thin clients, each one file with no dependencies, each generated against openapi.json so the types cannot drift from the handler: sdk/js/index.mjs for JavaScript (Node 18 or newer, or a browser) and sdk/python/fixragent_triage/__init__.py for Python (3.9 or newer, standard library only). Download the file and import it; that is the install today. The same files are the @fixragent/triage npm package and the fixragent-triage PyPI package, and those install lines land here with the first release.

Spanish. lang: 'es' in JavaScript, lang='es' in Python, or ?lang=es on the URL: the prose fields come back in Spanish and hazard_detail stays in English, on purpose — the hazard line is never machine-translated. The reply's language object says what was served.

Both clients replay the captured replies on this page through an injected transport in their tests, and the JavaScript client has been read against the mock byte for byte. Source: sdk/ in the repository, MIT.

The one-page sheet

A printable one-page summary — the Triage Profile the deep reply above makes, the payload behind it, and the pilot offer — is at /one-pager, and as a PDF in Letter and A4. It shows no photo: the photo behind that Triage Profile is a user upload held under a licence that covers processing only, so the sheet shows the Triage Profile's structure with the engine's own words and coordinates.

On your own site: the photo drop

No key and no code to write: paste one tag where the box should sit on your page — <script src="https://fixragent.com/embed.js" data-source="your-site" async></script>. Change your-site to a short name for your site; every Triage Profile made from your page carries that name, so the Triage Profiles from your site count as yours. The box takes a photo and shows the same Triage Profile as fixragent.com, it grows to fit the Triage Profile, and it sets no cookies on your site. Wix, Squarespace and WordPress steps, and a live box to try first, are on the embed page.

The three guards

This is a demo door, so three things stand in front of it. They run in this order, and the cheapest one runs first.

In plain words: twenty requests an hour from one address when you have no key; sixty a day on each key; and a daily spending brake that protects the service — when it trips you get 503 budget_exhausted until 00:00 UTC, and a key with its own cap is not stopped by it. When any of the three stops you, the reply says which one, in a sentence, with a Retry-After that is computed from the clock rather than a round number.

The key goes in the x-triage-key header. The brake is checked before the request body is read, so hitting it costs nothing, and the 503 carries Retry-After, retry_after_seconds and resets_at, all three computed from the current time to the next 00:00 UTC.

Keys with a usage plan: bursts, a hard cap, your running total

A pilot or paid key can carry a usage plan. A key with a plan is treated differently from the demo key in four ways, and every one of them is there so a campaign can send hundreds of photos in minutes without failing and without a surprise bill.

The billing rule. You are billed for distinct photos (or distinct Idempotency-Keys) in the window, and never for more than your cap. The door checks the cap before it runs the engine. Requests already in flight on other servers at the moment the cap is crossed can still be answered; those are never billed. The cap on your key is set with us in writing and can be raised the same day.

When the engine is busy. If our model provider is rate-limiting or down, you get 503 engine_busy with Retry-After instead of a 502. Nothing is billed. Retry with the same photo or the same Idempotency-Key and it is never charged twice.

curl -s https://fixragent.com/api/usage -H "x-triage-key: $FIXRAGENT_KEY"

/api/usage answers for pilot keys with a usage cap; a demo key has a fixed 60 a day and gets 401 demo_key_required here.

severity and tier

The server assigns both, in code. The model is asked for observations — four graded readings and two photo-grounded booleans — and the server derives severity from the rubric's decision table and tier from severity. Whatever severity the model proposed is kept in provenance.model_proposed_severity and overwritten, and the overwrite itself is recorded in severity_overwritten.

Parameters

Spanish

Send lang=es on the query string, or "lang": "es" in the body, and the prose fields come back in Spanish: fault_summary, photo_subject, asset_type, trade_required, resident_explanation, resident_why_it_matters, resident_what_happens_next, root_cause, failure_mechanism and the rest of the free text. A browser that prefers Spanish gets the same by its Accept-Language header, and the Triage Profile on the home page does the same when the browser asks for Spanish or the page is opened with ?lang=es.

Three things are the same in both languages, on purpose. Every JSON key, enum value and taxonomy id is the one this page documents. The four urgency words on the wire are EMERGENCY, TODAY, THIS WEEK and WHENEVER, assigned in code; the Spanish Triage Profile maps them to its own four words. And hazard_detail, resident_do_not and every *_reason field are written in English on every path, so a safety line is always the engine's own English sentence; the Spanish Triage Profile prints it after a Spanish lead-in, marked as English.

The reply carries a language object: requested (what you sent, or null), served (en or es), source (body, query, header or default) and hazard_text, a reading of the language hazard_detail actually came back in: en, or not-en when the engine wrote it in another language despite the instruction (measured on 14 Sep 2026: nine of twelve hazard reads under the first wording came back Spanish, so the server reads the line instead of trusting the request). The Triage Profile on the home page withholds a not-en hazard line and prints a fixed sentence in its place; a client of the API decides the same way, from this field. Read served before you assume the language: an unknown value is answered in English and requested keeps what you sent.

Request body

The response contract, versioned

The 200 body is published as a JSON Schema: https://fixragent.com/schemas/triage-response-v1.json. Every response, errors included, names the schema it answers under in the X-Triage-Schema header (readable from a browser), and every 200 repeats it in schema_version. Today that is triage-response-v1@1.1.0.

Additive only within v1. A required field is never removed or renamed, its type never changes, and an enum never loses or changes a value. New optional fields can appear — ignore fields you do not know. A change that would break any of that ships as triage-response-v2 at a new URL, and v1 keeps answering. Run npm run check:response-contract to refuse any change that breaks the v1 lock; CI wiring ships separately. core, customer, data_use and the top-level ids are contract-stable; extended, provenance, agreement and contract_validation are diagnostic and may grow.

Response: customer — the part you show your customer

Six fields you can put in front of your own customer, under your own brand, without rewriting them. Every value is derived in code from core and the rubric's hazard axis; none is copied from model text, so none carries our name, a hedge, or an empty sentence.

Response: data_use — training

Training is off by default for every call on this endpoint. data_use.training_allowed is true only for a key whose holder has authorised it in writing, and no key is authorised today. Any request can make itself stricter with "do_not_train": true in the body or the header x-triage-do-not-train: 1; nothing in a request can turn training on. data_use.photo_bytes_stored is always false. Nothing trains on these calls today, so no pipeline reads this flag yet; it is recorded on every call so that any future one must honour it. If you show your own users a photo-consent choice, you collect it; our API terms say what you tell them.

Response: contract_validation

Every core that leaves this endpoint is checked against the whole of CONTRACT-v1.json — both halves of it.

• The eight semantic rules — the sentences that say things like a detected fault must be visible in the photo, and no fault means no trade, no parts and no urgency. The sentences are read from the contract file itself and each is bound to the predicate that enforces it; a sentence with no predicate, or a predicate with no sentence, is reported as drift on the response.
• Every field definition — its type, its enum, its numeric bounds, its minimum string length, its array shape and item shape, uniqueness, and the keys nested objects must carry. These are walked straight out of the contract's json_schema, so a change to the contract changes what is enforced with no code change at all.

The second half is newer than the first, and the gap it closed was real: before it existed, an engine reply carrying asset_category: "BANANA" came back 200 with that value intact — a value not in the contract's own list for that field. Eight sentences were enforced; fifty-one field definitions were never read.

The validator publishes which JSON-Schema keywords it can execute. If the contract ever uses one it cannot, that appears in contract_validation.rules_source.shape_drift and in warnings as UNENFORCED — a constraint that stopped being checked must never read like one that still is.

The policy is repair and record:

• A violation is repaired, and the repair is listed in contract_validation.repairs and echoed into the top-level warnings array. Nothing is fixed silently.
• A repair never invents a photo-grounded fact, a taxonomy class, or prose. Where the engine gave no support for something it asserted, the assertion is withdrawn — and what it said is kept verbatim under retracted, so nothing is lost.
• If a repair changes severity, the response says so in repairs_changed_severity, in warnings, and in an X-Triage-Contract-Repair header. A run whose severity was moved by a repair is not a measurement of the rubric and must not be reported as one.
• If any violation survives repair, the whole response is refused with 502 contract_unrepairable rather than served with a note attached.

One rule has a standing exemption, and it is recorded rather than assumed: RUBRIC v1.1 §2.2's criterion-1 carve-out is the single legal way to reach P1 with fault_detected: false. When it applies it appears in contract_validation.exemptions, so an exemption never reads like conformance.

And one place where the contract and the code genuinely disagree, named rather than papered over: CONTRACT v1 types confidence as a number between 0 and 1 with no null, while the engine pipeline emits null whenever the model gave no usable number. There is no repair — a calibrated probability is the sort of thing a repair may not invent, and 0 is not "unknown", it is a confident no. So that one case is carved out by name: it still appears in shape_violations_found, it is described in contract_validation.contract_conflicts, and it is pushed onto warnings on every response it occurs in. It is an open item, not a fix. Remove the carve-out and the same reply is refused with 502 — which is how we know it is a decision on the record and not a blind spot.

Response: core

CONTRACT v1 CORE — 20 fields, in this order. 15 are CONTRACT-v1.json fields under their contract names; 5 (tier, criterion_1_fired, tier_forced_by, visible_wiring, water_near_electrical) are RUBRIC v1.1-2026-09-11 additions that CONTRACT-v1 predates. Everything the engine produced beyond these rides in extended; nothing is dropped.

Response: extended

Present only when extended=1 is requested; null otherwise. The rest of the contract output.

Response: provenance

What produced this answer. Recorded by the wrapper — a model is never asked to report its own configuration.

Response: stored

What happened to the database row in public.diy_guest_scans. A degraded write never reads the same as a clean one.

Rows land in public.diy_guest_scans. The provenance columns (diagnosis_id, engine_version, rubric_version, config_id, role, variant) come from a migration that was applied to production on 12 Sep 2026; on a database where it has not been applied the insert is retried with the pre-existing columns and the response comes back with degraded: true and the migration's filename. The values are still inside ai_result; they are simply not queryable by column until the migration runs. A degraded write never reads the same as a clean one.

Errors

Every error is { "error": "<code>", "message": "<plain English>" }. The message is written for a person; it is never a stack trace and never an internal code.

Every one of these leaves through the same exit. The status you see is read from one table in api/triage.js; there is no second path that writes a status of its own. budget_exhausted used to be that second path — it hand-wrote 503 beside the table instead of reading it — and because the two numbers agreed, nothing ever showed. qa/triage-loop/error-status-redproof.js now drives all 14 codes to the wire and compares each response's ACTUAL status to the table.

Retry-After. The three responses that ask you to come back later — rate_limited, demo_key_quota and budget_exhausted — carry a Retry-After header, the same number in the body as retry_after_seconds, and a retry_after_basis naming which clock it came from (ip_rate_window for your address's own one-hour window, utc_day for the next 00:00 UTC). It is computed, never a round number: ask again 30 minutes into a closed rate-limit window and the header says 1800, not 3600. Everything else on this page sends no Retry-After, and says nothing in its message about trying again — a sentence that promises a retry with no header behind it is a promise nothing can keep.

HTTP 405
{
  "error": "method_not_allowed",
  "message": "Method not allowed. POST a photo to this endpoint."
}

HTTP 401
{
  "error": "demo_key_required",
  "message": "A demo key is required. Send it as the x-triage-key header."
}

HTTP 400
{
  "error": "image_required",
  "message": "A photo is required. Send it as base64 in the \"image\" field."
}

HTTP 413
{
  "error": "image_too_large",
  "message": "That photo is larger than 3MB. Please send a smaller one.",
  "max_photo_bytes": 3145728,
  "platform_request_body_limit": {
    "bytes": 4500000,
    "stated_as": "4.5 MB",
    "source": "https://vercel.com/docs/functions/limitations",
    "source_last_updated": "August 24, 2026",
    "fetched": "2026-09-11",
    "evidence": "cited from vendor documentation fetched on this date — NOT measured against a deployed function (nothing deploys from this branch)"
  }
}

HTTP 503   Retry-After: 57600
{
  "error": "budget_exhausted",
  "message": "The triage demo has used up its compute budget for today. This is a spending limit on our side, not a problem with your photo or your request. The budget resets at 00:00 UTC — please try again then.",
  "resets_at": "2026-09-14T00:00:00.000Z",
  "budget": {
    "day": "2026-09-13",
    "limit_usd": 250,
    "limit_source": "default"
  },
  "retry_after_seconds": 57600,
  "retry_after_basis": "utc_day"
}

What happens to your photo

Every uploaded photo has its metadata stripped — EXIF, XMP, IPTC, and the other carriers that hold GPS — before it is hashed, before it is sent to the model, and before anything is stored.

If the metadata cannot be stripped, the photo is refused (415 image_unsupported or 500 metadata_strip_failed) rather than processed. There is no pass-through fallback, because a photo that still carries GPS looks the same as one that was cleaned.

This endpoint stores no photo bytes anywhere. The only thing kept about the image is the SHA-256 of the stripped version, in provenance.photo_sha256. The model provider, Google, keeps what it is sent — prompt, response and photo — for 55 days. What we keep ourselves, and for how long, is in the privacy policy.

The outcome loop: callback_url

Each triage comes back with a diagnosis_id and a callback_url. The URL is not stored anywhere — it is derived on every reply as /api/outcome?diagnosis_id=<id> — and the id it carries is what joins the two records: the triage row (diy_guest_scans.diagnosis_id) and the outcome row (outcomes, one row per triage per lane). When you find out what the thing actually was, POST it back:

Send it with the diagnosis_id from a triage you made. This endpoint takes no key, and an id it has never seen is recorded as a new outcome row against nothing, so an id copied from an example writes noise into the corpus.

curl -X POST "https://fixragent.com/api/outcome" -H "Content-Type: application/json" \
  -d '{"diagnosis_id":"<the diagnosis_id from your triage reply>","outcome":"fixed","reported_via":"triage_link","fixed_by":"pro","trade":"hvac"}'

Merge, not replace. The row is updated with only the keys you sent. A key you did not send leaves the stored value alone — an unanswered question and an answer of "none" must not write the same thing — so a second, fuller report never wipes a first one. A concurrent first report is merged onto rather than dropped.

Replies. 200 { ok: true, outcome: { id, diagnosis_id, outcome, fixed_by, reported_via } } on a write that landed. 400 with one of outcome_orphan_refused, outcome_label_invalid, reported_via_invalid, fixed_by_invalid, trade_invalid (each carries allowed). 409 triage_lane_migration_pending names the migration file if the database does not yet accept the triage-link lane; the write is refused, never downgraded. 500 is a plain { error: "Internal error" }.

The same endpoint answers GET /api/outcome?email=&diagnosis_ids= with the outcomes for triages that email's account owns — that is the app's own scan log, not an API surface, and it returns nothing for an id the account does not own.

The terms

Use of the API is governed by the API terms at /api-terms, alongside the terms of service and the privacy policy. In one line: this is an educational triage, not professional advice; gas, water near electrics and exposed wiring are licensed-trade jobs.

Help

This reference is the help centre; /help puts the common questions in plain words and sends each to its anchor here. Stuck, or something on the Triage Profile looks wrong? Write to support@fixragent.com. A founder reads every message and replies within one business day. Legal questions and deletion requests go to legal@fixragent.com.