# PREVIEW. The keyed interface this file describes is not live; reads run signed in on trywren.ai today. Request access: admin@trywren.ai # Keys open underwrites only. The live keyed contract is https://trywren.ai/v1/openapi-salesforce.json (OpenAPI 3.0.3); this preview is 3.1 and does not import into Salesforce. openapi: 3.1.0 info: title: Wren Condition API version: 1.0.0-stopgap summary: A photo-grounded condition read of one residential property, by API key. description: | One product, one door. A condition read takes a set of photographs (uploaded, or reachable by HTTPS URL) plus optional notes and property facts, and returns a Rowan assessment: what each area shows, which systems were observed, what needs attention, and what the read could not see. It never contains a price, a cost, a rehab budget, a valuation or a buy/pass recommendation; the server refuses to emit that language (src/core/Rowan/Assessment.py, `_PROHIBITED`). Paths, field names and status words are the ones in docs/directives/D113/D113_PRODUCT_SPLIT_RECON.md section 4 item 4, so nothing a partner builds against here changes when the product split lands. The assessment body is `schema_version: rowan-condition/5`; fields are only ever added within a version, and any removal or rename bumps the version. Clients must tolerate fields they do not know. A read runs for minutes (the engine budget is 600 s, src/core/Rowan/Vision.py:106). The POST answers 202 in under a second; the result arrives by polling, and optionally by a signed webhook. The webhook is a hint; the poll is the truth. The first release (D115, 2026-09-16) opens these paths to the signed-in web app only, with a Clerk session token, a lifetime free allowance per account and a photo cap of 30 per read. Partner keys, photo URLs and the webhook below are the next cut and are not live yet. Authentication is a partner key in the Authorization header. Keys that start with `wren_test_` run in sandbox mode: the same validation, the same state machine, the same webhook, and a recorded real assessment in place of a live model call, at zero vendor spend. Keys that start with `wren_live_` spend. The prefix is the only thing that decides the mode. A header cannot. contact: name: Wren url: https://trywren.ai servers: - url: https://trywren.ai description: Production. There is no separate sandbox host; sandbox is a key prefix. security: - partnerKey: [] tags: - name: condition description: Condition reads. paths: /v1/condition/reads: post: tags: [condition] operationId: createConditionRead summary: Start a condition read description: | Two request bodies are accepted and produce the same read. `application/json` with `photo_urls`: the server validates every URL before answering (HTTPS only, host on the key's allowlist, resolved address public), answers 202, then fetches the bytes in the background with a hard 15 MB per file, a per-read total, and a 20 s timeout per fetch. A URL that fails after the 202 shows up as `photos[].fetch_status: rejected` on the read; a read with zero fetched photos ends as `status: error` and spends nothing. This is the variant for Salesforce Apex, which cannot practically send multipart and is limited to a 6 MB callout body. `multipart/form-data` with `photos[]`: the bytes arrive on the request, and the same limits apply at the door. Send `Idempotency-Key` on every POST. A repeat with the same key and the same body returns the existing read with 200 instead of starting another; a repeat with a different body is refused with 409. parameters: - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/SandboxHeader' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConditionReadJsonRequest' examples: salesforce: summary: Two photos by URL, notes, a callback value: photo_urls: - https://partner.file.force.com/sfc/dist/version/download/?oid=00D...&ids=068...&d=/a/abc - https://partner.file.force.com/sfc/dist/version/download/?oid=00D...&ids=068...&d=/a/def address: 1411 Oak St, Nashville, TN 37206 notes: Seller reports the roof was replaced in 2019. Water heater is original. metadata: year_built: 1962 sqft: 1480 beds: 3 baths: 2 property_type: single_family photo_hints: - photo_number: 1 area: kitchen callback_url: https://partner.my.salesforce-sites.com/services/apexrest/wren/condition external_ref: a0B5f000001AbCdEAK multipart/form-data: schema: $ref: '#/components/schemas/ConditionReadMultipartRequest' encoding: photos: contentType: image/jpeg, image/png, image/webp, image/heic, image/gif options: contentType: application/json responses: '202': description: Accepted. Poll `Location` after `Retry-After` seconds. headers: Location: description: The read's URL, `/v1/condition/reads/{read_id}`. schema: { type: string } Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/ConditionReadAccepted' '200': description: Idempotent replay. The read that an earlier POST with this `Idempotency-Key` created. content: application/json: schema: $ref: '#/components/schemas/ConditionRead' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '402': $ref: '#/components/responses/RunGate' '403': $ref: '#/components/responses/Forbidden' '409': $ref: '#/components/responses/IdempotencyConflict' '413': $ref: '#/components/responses/LimitExceeded' '422': $ref: '#/components/responses/ValidationError' '429': $ref: '#/components/responses/RateLimited' '503': $ref: '#/components/responses/ServiceUnavailable' get: tags: [condition] operationId: listConditionReads summary: List this key's reads, newest first parameters: - name: limit in: query schema: { type: integer, minimum: 1, maximum: 100, default: 20 } - name: cursor in: query description: Opaque. Pass back `next_cursor` from the previous page. schema: { type: string, maxLength: 256 } - name: status in: query schema: $ref: '#/components/schemas/ReadLifecycleStatus' - name: external_ref in: query description: Exact match on the `external_ref` the read was created with. schema: { type: string, maxLength: 128 } responses: '200': description: One page. content: application/json: schema: $ref: '#/components/schemas/ConditionReadList' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '429': $ref: '#/components/responses/RateLimited' /v1/condition/reads/{read_id}: get: tags: [condition] operationId: getConditionRead summary: Poll one read description: | While `status` is `processing` the response carries `Retry-After` (15 s). `stages` grows as the engine reports progress. When `status` is `complete`, `assessment` is present and `read_status` says how much of the read succeeded: `complete`, `partial` (some areas assessed, some not), or `failed` (no area assessed; the read still carries its photo inventory and limits). A `failed` read is a finished read with nothing in it, never an HTTP error. `status: error` means the read itself did not finish (fetch failure, task restart, timeout) and `error` says which. parameters: - $ref: '#/components/parameters/ReadId' responses: '200': description: The read, in whatever state it is in. headers: Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/ConditionRead' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' webhooks: condition_read.finished: post: summary: Delivered to `callback_url` when a read reaches `complete` or `error` description: | POST, `Content-Type: application/json`, body exactly as described below, signed with the key's `webhook_secret`. Signature. `X-Wren-Signature: t=,v1=` where `v1 = HMAC_SHA256(webhook_secret, "." + raw_body)` in lowercase hex. Recompute over the raw bytes received (never a re-serialised body), compare in constant time, and reject when `|now - t| > 300` seconds. This is the scheme Wren itself consumes from Stripe (src/services/Billing.py:2778), so any Stripe-style verifier works unchanged. Delivery. Answer 2xx within 10 s. Anything else, or no answer, is retried at 30 s, 5 min and 30 min (four attempts in all), then marked `failed` on the read's `callback` block. Retries live in the API process; a deploy during the window ends them, and the read remains pollable. Deduplicate on `X-Wren-Event-Id`; the same event can arrive more than once. `callback_url` passes the same checks as `photo_urls`: HTTPS, host on the key's allowlist, public address, no redirects followed. parameters: - name: X-Wren-Signature in: header required: true schema: { type: string, examples: ['t=1758036000,v1=5f3c...e9'] } - name: X-Wren-Event-Id in: header required: true schema: { type: string, format: uuid } - name: X-Wren-Delivery-Attempt in: header required: true schema: { type: integer, minimum: 1, maximum: 4 } requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConditionReadFinishedEvent' responses: '2XX': description: Received. Any 2xx stops retries. components: securitySchemes: partnerKey: type: http scheme: bearer bearerFormat: wren_live__ or wren_test__ description: | `Authorization: Bearer wren_live__`. The `wren_` prefix is what routes the request to key authentication instead of a Clerk session; a bearer without it is treated as a session token on these routes and refused with 401 when it is not one. `key_id` selects the key record; the secret is compared as a SHA-256 digest in constant time. A key names one organization, one mode (live or test), one scope set (`condition:execute`, `condition:read`), one webhook secret and one URL host allowlist. The `X-Wren-Org` header the web app sends is ignored on key auth: the key already says which organization it is. clerkSession: type: http scheme: bearer bearerFormat: JWT description: The web app's Clerk session token. Same routes, same shapes; not for partners. parameters: ReadId: name: read_id in: path required: true schema: type: string pattern: '^[a-z0-9]{12,32}$' IdempotencyKey: name: Idempotency-Key in: header required: false description: | Any string up to 128 characters, unique per read on the partner side (a Salesforce record id plus a counter works). Scoped to the key. Stored with the read for 7 days. schema: { type: string, minLength: 1, maxLength: 128 } SandboxHeader: name: X-Wren-Sandbox in: header required: false deprecated: true description: | Not honored. Mode comes from the key prefix only. Sending `X-Wren-Sandbox: 1` with a `wren_live_` key is refused with 400 `sandbox_key_required` so a client that believes it is in sandbox can never spend by mistake; sending it with a `wren_test_` key is redundant and accepted. schema: { type: string, enum: ['1'] } headers: RetryAfter: description: Seconds to wait before the next request. schema: { type: integer, minimum: 1 } responses: BadRequest: description: A URL was refused before the read started, or the sandbox header was sent with a live key. content: application/json: schema: oneOf: - $ref: '#/components/schemas/UrlRejectedError' - $ref: '#/components/schemas/SimpleError' examples: hostNotAllowed: value: error: photo_url_rejected message: photo_urls[1] host is not on this key's allowlist details: { index: 1, reason: host_not_allowed } sandboxHeader: value: error: sandbox_key_required message: X-Wren-Sandbox is only accepted with a wren_test_ key Unauthorized: description: No bearer, an unknown key id, a wrong secret, or a revoked key. The body never says which. content: application/json: schema: $ref: '#/components/schemas/DetailError' example: { detail: Authentication required } Forbidden: description: The key lacks the scope this route needs. content: application/json: schema: $ref: '#/components/schemas/DetailError' example: { detail: 'Missing scope: condition:execute' } NotFound: description: No read with this id belongs to this key. content: application/json: schema: $ref: '#/components/schemas/DetailError' example: { detail: Not found } RunGate: description: | The read is not allowed to start. Same body as the web app's refused underwrite (src/Main.py:3502-3512). For a partner key today the only reason emitted is `quota_exhausted`, when the key's monthly cap is reached; the other reasons are reserved for the product gate the split introduces. content: application/json: schema: $ref: '#/components/schemas/RunGateError' IdempotencyConflict: description: This `Idempotency-Key` was used with a different body. content: application/json: schema: $ref: '#/components/schemas/SimpleError' example: error: idempotency_conflict message: Idempotency-Key was already used with a different request body LimitExceeded: description: Over a size or count limit. `limit` names which one and `max` its value. content: application/json: schema: $ref: '#/components/schemas/LimitExceededError' ValidationError: description: The options did not validate (a hint out of range, notes too long, a bad field). content: application/json: schema: $ref: '#/components/schemas/ValidationErrorBody' RateLimited: description: | Either the per-key sliding window (6 creates and 60 reads per 60 s) or the in-flight cap (2 live reads per key at once). Wait `Retry-After` seconds. headers: Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/RateLimitedError' ServiceUnavailable: description: Key auth or the sandbox recording is not configured on this deployment. content: application/json: schema: $ref: '#/components/schemas/SimpleError' schemas: # ----- requests ----------------------------------------------------------- ConditionReadOptions: type: object description: Everything about a read except the photo bytes. Shared by both request variants. additionalProperties: false properties: address: type: [string, 'null'] maxLength: 300 description: Fills `metadata.address`. Used for the read's own record and for labeling; the read is not a valuation. notes: type: [string, 'null'] maxLength: 30000 description: Inspector or listing notes. Rowan reads them as `listing_remarks` and reports conflicts between them and the photos. Longer than 30,000 characters is refused with 413 `notes_chars`. metadata: $ref: '#/components/schemas/PropertyMetadata' photo_hints: type: array maxItems: 100 items: $ref: '#/components/schemas/RowanPhotoHint' description: Optional grouping hints by photo position (1-based, in the order sent). Positions must be unique and within the photo count. verify_risks: type: boolean default: true description: Run the second-pass risk verification over material findings. callback_url: type: [string, 'null'] format: uri maxLength: 2048 description: HTTPS URL on the key's allowlist. Receives `condition_read.finished`. external_ref: type: [string, 'null'] maxLength: 128 description: The partner's own identifier for this read (a Salesforce record id). Echoed on every response and in the webhook. ConditionReadJsonRequest: allOf: - $ref: '#/components/schemas/ConditionReadOptions' - type: object required: [photo_urls] properties: photo_urls: type: array minItems: 1 maxItems: 100 items: type: string format: uri maxLength: 2048 pattern: '^https://' description: | Fetched in order; position n becomes photo `P{n:02d}`. Each must be HTTPS on an allowlisted host, answer 200 with an image body of at most 15 MB within 20 s, and not redirect. Duplicates are detected by content, not by URL. ConditionReadMultipartRequest: type: object required: [photos] properties: photos: type: array minItems: 1 maxItems: 100 items: type: string format: binary description: Image files, at most 15 MB each and 150 MB together per read on a partner key. options: type: string description: A JSON string encoding `ConditionReadOptions`. Defaults to `{}`. PropertyMetadata: type: object description: Property facts handed to the read. Mirrors src/core/Rowan/Assessment.py `PropertyMetadata`; unknown fields are refused. additionalProperties: false properties: address: { type: [string, 'null'], maxLength: 300 } sqft: { type: [number, 'null'], exclusiveMinimum: 0 } year_built: { type: [integer, 'null'], minimum: 1600, maximum: 2100 } beds: { type: [integer, 'null'], minimum: 0 } baths: { type: [number, 'null'], minimum: 0 } property_type: { type: [string, 'null'], maxLength: 80 } RowanPhotoHint: type: object description: One position's grouping hint. Mirrors src/schemas/api.py `RowanPhotoHint`. additionalProperties: false required: [photo_number] properties: photo_number: { type: integer, minimum: 1 } area: { type: [string, 'null'], maxLength: 80 } area_id: { type: [string, 'null'], maxLength: 80 } # ----- read envelope --------------------------------------------------------- ReadLifecycleStatus: type: string enum: [processing, complete, error] description: Whether the read has finished. Distinct from `read_status`, which says how much of a finished read succeeded. ConditionReadAccepted: type: object required: [read_id, status, product, sandbox, created_at, poll_url, retry_after_s] properties: read_id: { type: string } status: { type: string, const: processing } product: { type: string, const: condition } sandbox: { type: boolean, description: True when the key is a `wren_test_` key. Nothing was spent and `assessment` will be a recording. } external_ref: { type: [string, 'null'] } created_at: { type: string, format: date-time } poll_url: { type: string, examples: ['/v1/condition/reads/9f2c1a7b3e5d'] } retry_after_s: { type: integer, examples: [15] } ConditionRead: type: object required: [read_id, status, product, sandbox, schema_version, photo_count, stages, photos, created_at] properties: read_id: { type: string } status: $ref: '#/components/schemas/ReadLifecycleStatus' product: { type: string, const: condition } sandbox: { type: boolean } external_ref: { type: [string, 'null'] } read_status: oneOf: - $ref: '#/components/schemas/ReadStatus' - type: 'null' description: Null until `status` is `complete`. schema_version: { type: string, const: rowan-condition/5 } photo_count: { type: integer, minimum: 0, description: Photos accepted at the door (uploads) or fetched (URLs). } areas_assessed: { type: [integer, 'null'], minimum: 0 } areas_total: { type: [integer, 'null'], minimum: 0 } stages: type: array items: $ref: '#/components/schemas/ReadStage' description: Engine progress, oldest first. Informational; never branch on the text. photos: type: array items: $ref: '#/components/schemas/PhotoSource' assessment: oneOf: - $ref: '#/components/schemas/RowanAssessment' - type: 'null' error: oneOf: - $ref: '#/components/schemas/ReadError' - type: 'null' callback: oneOf: - $ref: '#/components/schemas/CallbackState' - type: 'null' created_at: { type: string, format: date-time } completed_at: { type: [string, 'null'], format: date-time } ConditionReadSummary: type: object required: [read_id, status, sandbox, photo_count, created_at] properties: read_id: { type: string } status: $ref: '#/components/schemas/ReadLifecycleStatus' read_status: oneOf: - $ref: '#/components/schemas/ReadStatus' - type: 'null' sandbox: { type: boolean } external_ref: { type: [string, 'null'] } photo_count: { type: integer, minimum: 0 } created_at: { type: string, format: date-time } completed_at: { type: [string, 'null'], format: date-time } ConditionReadList: type: object required: [reads, next_cursor] properties: reads: type: array items: $ref: '#/components/schemas/ConditionReadSummary' next_cursor: { type: [string, 'null'] } ReadStage: type: object required: [stage, message, ts] properties: stage: { type: string, examples: [preparing, indexing, assessing, verifying] } message: { type: string } ts: { type: number, description: Unix seconds. } PhotoSource: type: object required: [photo_id, position, source, fetch_status] properties: photo_id: { type: string, pattern: '^P[0-9]{2,}$', description: The id the assessment cites in `evidence` and `photo_inventory`. } position: { type: integer, minimum: 1 } source: { type: string, enum: [upload, url] } filename: { type: [string, 'null'] } bytes: { type: [integer, 'null'], minimum: 0 } sha256: { type: [string, 'null'], pattern: '^[0-9a-f]{64}$' } fetch_status: type: string enum: [pending, fetched, rejected] description: Uploads are `fetched` at the door. URLs move from `pending` to `fetched` or `rejected` in the background. error: type: [string, 'null'] description: For `rejected`, one of the `UrlRejectReason` values. ReadError: type: object required: [code, message] properties: code: type: string enum: [no_photos_fetched, timed_out, task_restarted, engine_failed] description: | `no_photos_fetched`: every URL was rejected; nothing spent. `timed_out`: the 660 s backstop fired (engine budget plus 60 s). `task_restarted`: the API process restarted (a deploy) while this read was processing. Resubmit. `engine_failed`: the engine raised; the read is not billed. message: { type: string } CallbackState: type: object required: [url, status, attempts] properties: url: { type: string } status: { type: string, enum: [pending, delivered, failed] } attempts: { type: integer, minimum: 0, maximum: 4 } last_attempt_at: { type: [string, 'null'], format: date-time } last_status_code: { type: [integer, 'null'] } ConditionReadFinishedEvent: type: object required: [event, event_id, created_at, attempt, read] properties: event: { type: string, const: condition_read.finished } event_id: { type: string, format: uuid } created_at: { type: string, format: date-time } attempt: { type: integer, minimum: 1, maximum: 4 } read: $ref: '#/components/schemas/ConditionRead' # ----- the assessment (src/core/Rowan/Assessment.py) ------------------------ ConditionState: type: string enum: [damaged, worn, dated_functional, serviceable] FindingConfidence: type: string enum: [observed, likely, uncertain] CoverageStatus: type: string enum: [observed, partially_observed, not_observed] ReadStatus: type: string enum: [complete, partial, failed] description: | `complete`: every area assessed. `partial`: at least one area assessed and at least one not. `failed`: zero areas assessed, whatever the reason. Never defaulted; a read always says which. IndexStatus: type: string enum: [ok, failed_fallback] description: Whether the photo indexer answered. `failed_fallback` means every photo became its own area. FindingCategory: type: string enum: [structural, moisture, safety, system, functional, finish] PhotoStatus: type: string enum: [analyzed, ready, duplicate, invalid, failed] PhotoQualityFlag: type: string enum: - blurry - low_light - low_resolution - tight_crop - obstructed - overexposed - wide_angle_distortion - virtual_staging_suspected - heavy_editing_suspected PhotoInventoryItem: type: object required: [photo_id, status] properties: photo_id: { type: string } filename: { type: [string, 'null'] } status: $ref: '#/components/schemas/PhotoStatus' area: { type: [string, 'null'] } area_id: { type: [string, 'null'] } view_type: { type: [string, 'null'] } quality_flags: type: array items: $ref: '#/components/schemas/PhotoQualityFlag' duplicate_of: { type: [string, 'null'], description: The photo id this one duplicates. } error: type: [string, 'null'] description: For `invalid`, one of empty_file, file_too_large, invalid_image_dimensions, unsupported_or_corrupt_image. Finding: type: object required: [finding_id, category, component, observation, state, confidence, evidence, visible_scope] properties: finding_id: { type: string, pattern: '^F[0-9]{3}$' } category: $ref: '#/components/schemas/FindingCategory' component: { type: string, minLength: 1 } observation: { type: string, minLength: 1 } state: $ref: '#/components/schemas/ConditionState' confidence: $ref: '#/components/schemas/FindingConfidence' evidence: type: array minItems: 1 items: { type: string } description: Photo ids. Every finding cites at least one photo in its own area. visible_scope: { type: string, minLength: 1 } conditional_scope: { type: [string, 'null'] } uncertainty: { type: [string, 'null'] } FinishObservation: type: object required: [component, observation, state, confidence, evidence] properties: component: { type: string, minLength: 1 } observation: { type: string, minLength: 1 } state: $ref: '#/components/schemas/ConditionState' confidence: $ref: '#/components/schemas/FindingConfidence' evidence: type: array minItems: 1 items: { type: string } AreaAssessment: type: object required: [area_id, area, photos] properties: area_id: { type: string } area: { type: string } photos: type: array items: { type: string } finish_observations: type: array items: $ref: '#/components/schemas/FinishObservation' findings: type: array items: $ref: '#/components/schemas/Finding' not_visible_in_area: type: array items: { type: string } InventoryAssessment: type: object required: [system, status] description: | One system. The fifteen standard systems always appear, in this order: roof, attic, foundation, crawlspace, hvac_equipment, water_heater, electrical_panel, visible_plumbing, windows, exterior_front, exterior_rear, exterior_left, exterior_right, garage, laundry. Others the read named follow, sorted. `not_observed` carries no evidence and no findings; any other status carries at least one photo. properties: system: { type: string } status: $ref: '#/components/schemas/CoverageStatus' evidence: type: array items: { type: string } findings: type: array items: $ref: '#/components/schemas/Finding' limits: { type: [string, 'null'] } AttentionItem: type: object required: [item, evidence, reason, confidence] properties: item: { type: string } evidence: type: array minItems: 1 items: { type: string } reason: { type: string } confidence: $ref: '#/components/schemas/FindingConfidence' ListingRemarkConflict: type: object required: [remark, conflict, evidence] properties: remark: { type: string, description: The sentence from `notes` the photos contradict. } conflict: { type: string } evidence: type: array minItems: 1 items: { type: string } RowanAssessment: type: object description: | The read. Every list is present, possibly empty. Free text never contains currency, cost, budget, rehab tier, valuation or buy/pass language; the server rejects a read that does. Fields are additive within a `schema_version`; clients ignore what they do not know. required: - schema_version - read_status - areas_assessed - areas_total - index_status - read_id - prompt_version - model - photo_inventory - areas - systems - attention_items - not_observed_inventory - listing_remark_conflicts - condition_narrative - assessment_limits properties: schema_version: { type: string, const: rowan-condition/5 } read_status: $ref: '#/components/schemas/ReadStatus' areas_assessed: { type: integer, minimum: 0 } areas_total: { type: integer, minimum: 0 } index_status: $ref: '#/components/schemas/IndexStatus' read_id: { type: string, minLength: 1, description: Provenance id shared by every model call the read made. Equals the envelope's `read_id`. } prompt_version: { type: string, minLength: 1, description: Twelve hex characters, a content hash of the prompt text that produced this read. } model: { type: string, minLength: 1 } sdk_version: { type: [string, 'null'] } photo_inventory: type: array items: $ref: '#/components/schemas/PhotoInventoryItem' areas: type: array items: $ref: '#/components/schemas/AreaAssessment' systems: type: array items: $ref: '#/components/schemas/InventoryAssessment' attention_items: type: array maxItems: 5 items: $ref: '#/components/schemas/AttentionItem' description: The short list to act on, most material first. At most five; the full finding set stays on `areas`. not_observed_inventory: type: array items: { type: string } description: Standard systems no photo showed. listing_remark_conflicts: type: array items: $ref: '#/components/schemas/ListingRemarkConflict' condition_narrative: type: string description: The lead-in, most material findings first, each citing its photos. assessment_limits: type: array items: { type: string } description: What the read could not do and why, in the read's own words. # ----- errors --------------------------------------------------------------- DetailError: type: object required: [detail] properties: detail: { type: string } SimpleError: type: object required: [error, message] properties: error: { type: string } message: { type: string } UrlRejectReason: type: string enum: - not_https - host_not_allowed - address_not_public - dns_failed - redirect_refused - timeout - too_large - not_an_image - http_status UrlRejectedError: type: object required: [error, message, details] properties: error: { type: string, enum: [photo_url_rejected, callback_url_rejected] } message: { type: string } details: type: object required: [reason] properties: index: { type: integer, minimum: 0, description: Position in `photo_urls`. Absent for `callback_url`. } reason: $ref: '#/components/schemas/UrlRejectReason' RunGate: type: object description: Mirrors frontend/src/core/Api.ts `RunGate` and src/services/Billing.py `check_run_allowance`. required: [reason, message] properties: reason: type: string enum: - free_exhausted - quota_exhausted - ceiling_reached - billing_suspended - payment_action_required - payment_disputed - legacy_no_overage message: { type: string } free_used: { type: integer } free_allowance: { type: integer } used: { type: [integer, 'null'] } detail: { type: [string, 'null'] } plan: type: object properties: quota_source: { type: [string, 'null'], enum: [default, subscription, grant, null] } underwrite_quota: { type: [integer, 'null'] } plan_code: { type: [string, 'null'] } price_display: { type: [string, 'null'] } price_period: { type: [string, 'null'] } billing_interval: { type: [string, 'null'] } subscription_status: { type: [string, 'null'] } current_period_end: { type: [string, 'null'] } RunGateError: type: object required: [success, error, error_code, gate] properties: success: { type: boolean, const: false } error: { type: string, description: The sentence a person can read. Same text as `gate.message`. } error_code: { type: string, const: run_gate } gate: $ref: '#/components/schemas/RunGate' example: success: false error: This key has used its 200 condition reads for September. The cap resets on October 1. error_code: run_gate gate: reason: quota_exhausted message: This key has used its 200 condition reads for September. The cap resets on October 1. used: 200 plan: { quota_source: grant, underwrite_quota: 200, plan_code: partner_stopgap } LimitExceededError: type: object required: [error, limit, max, message] properties: error: { type: string, const: limit_exceeded } limit: type: string enum: [photos, file_bytes, total_bytes, notes_chars, photo_urls, request_bytes] description: | photos and photo_urls: 100 per read. file_bytes: 15,728,640 per photo. total_bytes: 157,286,400 per read on a partner key (the web app's own limit is higher). notes_chars: 30,000. request_bytes: the JSON body, 64 KB. max: { type: integer } actual: { type: [integer, 'null'] } message: { type: string } RateLimitedError: type: object required: [error, message] properties: error: { type: string, enum: [rate_limited, in_flight_limit] } message: { type: string } ValidationErrorBody: type: object required: [error, details] properties: error: { type: string, const: invalid condition read options } details: type: array items: type: object properties: loc: type: array items: { type: [string, integer] } msg: { type: string } type: { type: string }