fixRAgent Usage API

openapi: 3.2.0
info:
  title: fixRAgent triage Usage API
  version: engine-v2-triage-door-1.0.0
  summary: 'One photo in, one triage out: what it is, whether it is broken, how urgent, and a link to tell us whether the answer was right.'
  description: 'POST a photo. You get back a CONTRACT v1 CORE triage of 20 fields, a server-assigned

    severity and tier, a `diagnosis_id`, and a `callback_url` for reporting what actually fixed it.


    **Severity and tier are assigned by the server, from the rubric, in code.** The model is asked for

    observations — four axis values and two photo-grounded booleans — and the server derives P1..P4 from

    them and the tier from P. A model''s own opinion of severity is recorded as

    `provenance.model_proposed_severity` and then overwritten, and the overwrite is recorded too.


    **Criterion 1.** Visible wiring in the photo, or water near anything electrical, is EMERGENCY by

    definition — no other axis can lower it. Where either fact is uncertain the engine answers false and

    the decision table decides instead; that is deliberate, so a dim photo of a basement is not an

    emergency.


    **This is a demo door.** Three guards stand in front of it, in this order:

    1. 20 requests per IP per 1 hour (the same scheme /api/diagnose uses) for callers without a key of their own; an issued key is judged by the key instead (a per-minute burst and its daily limit, counted in that server-only ledger).

    2. Your own key in the `x-triage-key` header, 60 requests per UTC day per key. A free key is emailed to you from https://fixragent.com/docs#key; each person gets their own.

    3. A daily spend brake at $250, counted from a call ledger only the server writes, so every server instance sees the same count (a key with its own cap is bounded by that cap instead). Past it the endpoint answers 503 with a plain-English message and

    spends nothing — the fuse is checked before the body is read.


    **About the spend figure.** Every dollar amount this API reports is COMPUTED from token counts and a

    declared price table. It is not metered and it is not a bill. It is labelled that way in the payload

    (`basis`), and it should be labelled that way anywhere it is quoted.


    **The core is checked, not just shaped.** Every emitted core is validated against all eight of CONTRACT-v1.json''s semantic rules before it leaves the handler, and the result rides in `contract_validation` on every 200. Violations are repaired and named, never silently fixed; a repair that moves severity says so in the payload, the warnings and a response header; a violation that survives repair refuses the whole response (502 `contract_unrepairable`).


    **Photos.** Every uploaded photo has its metadata stripped before it is hashed, sent to the engine, or

    stored. A photo whose metadata cannot be stripped is refused (415 or 500) rather than processed — there

    is no pass-through fallback, because a photo that still carries GPS looks identical to one that was

    cleaned. The cleaned photo is kept with its Triage Profile (a private store, shown to anyone with the

    profile''s link) unless the request sends `keep_photo: false`; the SHA-256 of the stripped image is always kept.'
  contact:
    name: AR Logic LLC
    url: https://fixragent.com
servers:
- url: https://fixragent.com
  description: Production. Same origin as the Triage Profile on the home page.
- url: /
  description: Same origin as the app.
tags:
- name: Usage
paths:
  /api/usage:
    get:
      summary: A capped key's running total
      description: Send your key as x-triage-key. Answers only for a key with a usage plan. The same numbers ride on every /api/triage answer as X-Key-Usage-* headers and a usage block.
      parameters:
      - name: x-triage-key
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: 'usage: key_id, window, window_label, window_start, resets_at, cap, rows, billable, remaining, percent, enforcement'
        '401':
          description: demo_key_required — no key, or a key without a usage plan
        '503':
          description: usage_unreadable — try again in a minute
      tags:
      - Usage
      operationId: getApiUsage
      x-operation-id-source: derived
x-fixr:
  generated_from: api/triage.js exported constants
  checked_by: qa/triage-loop/t6-openapi-check.js
  core_field_count: 20
  tiers:
    P1: EMERGENCY
    P2: TODAY
    P3: THIS WEEK
    P4: WHENEVER
  guards:
    ip_rate_limit:
      max: 20
      window_ms: 3600000
      scheme: same as api/diagnose.js
    demo_key:
      env: TRIAGE_DEMO_KEY
      header: x-triage-key
      daily_limit: 60
    daily_spend_fuse:
      limit_usd: 250
      module: api/_triage-fuse.js
      red_proof: qa/triage-loop/fuse-redproof.js
      basis: computed_from_usage_tokens_x_declared_prices_not_metered; scope=this_warm_instance_only (in-process counter; cross-instance day spend is under-counted by up to the number of warm instances)
      retry_after: seconds to the next 00:00 UTC, computed — not a fixed 3600
      basis_note: VERBATIM, the value api/_triage-fuse.js BASIS emits in every payload. It used to read 'computed, not metered, and scoped to ONE warm instance' — a paraphrase, which is a second record of the same fact and free to drift from the first.
  error_codes:
    method_not_allowed: 405
    rate_limited: 429
    demo_key_required: 401
    demo_key_quota: 429
    budget_exhausted: 503
    image_required: 400
    image_invalid: 400
    image_too_small: 400
    image_too_large: 413
    image_unsupported: 415
    metadata_strip_failed: 500
    engine_error: 502
    contract_unrepairable: 502
    internal_error: 500
    key_cap_reached: 429
    key_burst_limited: 429
    engine_busy: 503
  provenance_columns:
  - diagnosis_id
  - engine_version
  - rubric_version
  - config_id
  - role
  - variant
  not_deployed: This branch is not deployed. Sentry events from this handler are tagged environment=preview.
  photo_limits:
    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)
    note: The photo ceiling is set BY the platform ceiling. The platform figure is cited from vendor documentation fetched 2026-09-11, not measured against a deployed function — nothing deploys from this branch.
  contract_validation:
    rules_file: qa/engine-v2/CONTRACT-v1.json rules.semantic
    rules_enforced: 8
    policy: repair-and-record; refuse (502 contract_unrepairable) if a violation survives repair
    red_proof: qa/triage-loop/contract-semantic-redproof.js
    key_set_red_proof: qa/triage-loop/core-keyset-redproof.js
    severity_path_red_proof: qa/triage-loop/severity-paths-redproof.js