{"components":{"schemas":{"envelope":{"additionalProperties":false,"description":"Uniform error envelope returned on every non-2xx response.","properties":{"error":{"additionalProperties":false,"properties":{"code":{"description":"Stable snake_case code agents key on (e.g. \"not_found\", \"forbidden\", \"conflict\").","type":"string"},"details":{"additionalProperties":true,"description":"Optional structured context — the invalid field, the required permission code.","type":"object"},"message":{"description":"Human-readable explanation.","type":"string"}},"required":["code","message"],"type":"object"}},"required":["error"],"type":"object"},"lookup":{"description":"A platform-owned vocabulary entry. ⚠️ READ ONLY — the same for every tenant and not editable through any API.","properties":{"code":{"description":"Stable machine code. Key your logic on this, not on the id.","type":"string"},"description":{"type":["null","string"]},"id":{"type":"string"},"name":{"type":"string"},"sortOrder":{"type":"integer"}},"required":["id","code","name"],"type":"object"},"quote":{"description":"A priced proposal for work that has not happened yet. ⭐ The same model as an invoice **minus the cost side**, because nobody is paid for a job nobody has done — plus a date the offer stops standing.","properties":{"createdDateTime":{"type":["null","string"]},"createdUserId":{"type":["null","string"]},"currencyCode":{"type":"string"},"customerId":{"description":"🔴 Always a customer. There is no side column here and there must not be — the existence of a driver-side quote is the thing this domain rules out.","type":"string"},"expiryDate":{"description":"🔴 The date the offer stops standing — the one field a quote has that an invoice does not. ⚠️ Nullable: an open-ended quote is real, and defaulting to thirty days would withdraw an offer nobody withdrew.","type":["null","string"]},"id":{"type":"string"},"isExpired":{"description":"⚠️ DERIVED AT READ TIME from the expiry date, and NOT the same as the `expired` status. A quote past its date that nobody has swept still reads as expired here — but one that was ACCEPTED on its last valid day never does, which is why the status is set once and the date is evidence rather than the answer.","type":"boolean"},"isLocked":{"description":"True once the customer has answered or the tenant has withdrawn it. Lines may no longer change.","type":"boolean"},"issueDate":{"description":"ISO date.","type":"string"},"notes":{"type":["null","string"]},"quoteNumber":{"type":"string"},"respondedDateTime":{"description":"⚠️ Separate from sentDateTime — a quote can be accepted over the phone before the document arrives.","type":["null","string"]},"sentDateTime":{"type":["null","string"]},"statusCode":{"description":"draft, sent, accepted, declined, expired or cancelled.","type":"string"},"subtotalAmount":{"description":"Decimal string. ⚠️ A string, not a number — JSON numbers are IEEE doubles and money is not.","type":"string"},"summary":{"description":"What the customer is being quoted for, in their words. A quote is read by someone who was not in the conversation that produced it.","type":["null","string"]},"taxAmount":{"description":"Decimal string. ⚠️ You supply it per line; Mesh never computes tax.","type":"string"},"terms":{"type":["null","string"]},"totalAmount":{"description":"Decimal string.","type":"string"},"updatedDateTime":{"type":["null","string"]},"updatedUserId":{"type":["null","string"]}},"required":["id","statusCode","customerId","quoteNumber","issueDate","currencyCode","subtotalAmount","taxAmount","totalAmount","isLocked","isExpired"],"type":"object"},"quoteDocument":{"description":"Every version of a quote’s rendered file. ⭐ Same shape and reasoning as an invoice document — a re-sent quote after a price change is version 2, and the version the customer already holds survives.","properties":{"byteSize":{"type":["null","integer"]},"contentType":{"type":"string"},"createdDateTime":{"type":["null","string"]},"id":{"type":"string"},"quoteId":{"type":"string"},"renderedDocumentId":{"type":["null","string"]},"sentDateTime":{"type":["null","string"]},"storageKey":{"type":"string"},"supersedeReason":{"type":["null","string"]},"version":{"type":"integer"}},"required":["id","quoteId","version","storageKey","contentType"],"type":"object"},"quoteDocumentDownload":{"description":"🔴 A TIME-LIMITED LINK TO THE FILE, NOT THE FILE. The browser fetches from object storage directly — `storage.md` invariant 2 forbids private bytes transiting this service, and a multi-megabyte document through a Worker is paid for twice and times out at about the size a real invoice batch produces.\n\n⚠️ **Treat the URL as a secret.** It carries its own signature, so anyone holding it can fetch the bytes without a token, and it CANNOT be revoked — only expired. Do not log it, do not put it in an email, do not store it.","properties":{"expiresDateTime":{"description":"When it stops working, as an absolute time — so a caller does not have to guess when \"now\" was.","type":"string"},"expiresInSeconds":{"description":"How long the link lives from now.","type":"integer"},"fileName":{"description":"⭐ What the file is called when it lands. The quote NUMBER, not the storage key — the key carries the internal id on purpose (design ADR 0094).","type":"string"},"url":{"description":"Fetch this with a plain GET and no Authorization header. ⚠️ Single use in practice: ask again rather than keeping one.","type":"string"}},"required":["url","expiresInSeconds","expiresDateTime"],"type":"object"},"quoteLine":{"description":"A line on a quote. ⚠️ NO BUILDER COLUMN, unlike an invoice line: an invoice line is DERIVED from work the platform already priced and records the rule that produced it, while a quote line is PROPOSED and has nothing to attribute.","properties":{"accountCode":{"description":"Carried for the accounting phase, never interpreted.","type":["null","string"]},"amount":{"description":"Decimal string, excluding tax.","type":"string"},"createdDateTime":{"type":["null","string"]},"createdUserId":{"type":["null","string"]},"description":{"type":"string"},"id":{"type":"string"},"lineNumber":{"type":"integer"},"quantity":{"description":"Decimal string.","type":"string"},"quoteId":{"type":"string"},"rateId":{"description":"The rate that suggested this price, when one did. ⚠️ Usually null — most quote lines are typed by a person pricing a job that has no shape yet.","type":["null","string"]},"rateTypeCode":{"type":["null","string"]},"taxAmount":{"description":"Decimal string. ⚠️ You supply it — Mesh never computes tax.","type":["null","string"]},"unitAmount":{"description":"Decimal string, scale 4.","type":["null","string"]}},"required":["id","quoteId","lineNumber","description","quantity","amount"],"type":"object"},"quotingSettings":{"description":"How a tenant’s quotes are produced, at one level of the cascade. 🔴 **Two levels only** — a tenant base and a per-customer override — because a quote is always to a customer and there is no cost side. ⚠️ **Deliberately smaller than invoicing settings**: quoting has no builders, no approval gate and no exception behaviour, and publishing those would be publishing settings that do nothing.","properties":{"customerId":{"description":"Set on a customer-scoped row, null on the tenant base.","type":["null","string"]},"documentTemplateId":{"description":"🔴 Which template a quote is rendered with, from public-api-document-rendering. ⚠️ **Null means INHERIT.** Null at every level means nothing is configured and generating a document refuses — there is no default, because a document with nobody’s letterhead is not one you would send.","type":["null","string"]},"id":{"description":"Opaque identifier.","type":"string"},"scopeCode":{"description":"`tenant` or `customer`.","type":"string"}},"required":["id","scopeCode"],"type":"object"}},"securitySchemes":{"bearerAuth":{"bearerFormat":"JWT (Mesh IAM-issued)","description":"Mesh IAM JWT obtained via OAuth2 client_credentials against the Mesh IAM token endpoint for your environment (call get_connection_details on the Mesh MCP server). Validated locally against the IAM JWKS; iss / aud / exp checked (ADR 0025). Locally, DEV_BYPASS_AUTH=1 accepts any non-empty bearer.","scheme":"bearer","type":"http"}}},"info":{"description":"Send a customer a priced proposal for work that has not happened yet — lines with numbers against them, a real document, and a date the offer stops standing.\n\n⭐ **A quote is an invoice for work that has not happened.** The same three statements apply: here are the priced lines and a total, here is a document format, send it to this address. Which is why it uses the same renderer as an invoice — and why it was designed alongside invoicing rather than after it.\n\n🔴 **Charges only, never costs.** A cost is what the business pays the driver who did the work, and nobody is paid for a job nobody has done. There is no side column in this API and there must not be one.\n\n🔴 **`expiryDate` is the one field a quote has that an invoice does not** — and it is nullable, because an open-ended quote is a real thing a tenant sends and defaulting it to thirty days would withdraw an offer nobody withdrew.\n\n🔴 **Marking a quote accepted creates no work.** No stops, no invoice, no schedule. What a quote *does* when accepted is a lifecycle, and lifecycles belong to the product built on Mesh — the platform owns the artefact.\n\n⭐ **A sent quote is still editable.** Revising a price and re-sending produces version 2 of the document rather than replacing version 1, so the customer keeps what they were given. It locks once they answer.\n\n⚠️ **Every amount is a decimal string, not a JSON number.** JSON numbers are IEEE doubles and money is not.\n\n⏸ **Nothing is rendered or delivered from here today.** The renderer writes to object storage and no bucket is bound anywhere; all four email sending identities failed on 2026-11-06.\n\nGenerated from route schemas — never hand-edited. Source: https://github.com/loc-mesh/public-api-quoting","title":"Quoting API","version":"1.0.18"},"openapi":"3.1.0","paths":{"/api":{"get":{"description":"What this service is, what it owns, what it deliberately does not own, and the permissions needed to use it. No authentication required.","responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":true,"type":"object"}}},"description":"Default Response"}},"summary":"Self-describing service root.","tags":["meta"]}},"/api/health":{"get":{"description":"Returns 200 with the canonical health body (design/quality-standards.md §3) once the process has booted. Has no dependencies and never fails unless the API itself is down. Public — no token required.","responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"description":"Liveness payload.","properties":{"environment":{"description":"Deployed environment (MESH_ENV).","type":"string"},"ok":{"description":"Always true on success.","type":"boolean"},"service":{"description":"Service identity.","type":"string"}},"required":["ok","service","environment"],"type":"object"}}},"description":"Liveness payload."}},"security":[],"summary":"Liveness check.","tags":["discovery"]}},"/api/health/db":{"get":{"description":"Returns 200 only if the loc-mesh Postgres is reachable. On failure returns 503 with the uniform error envelope. Public — used by the dev portal and readiness gates.","responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"description":"Readiness payload.","properties":{"dependency":{"description":"The dependency this readiness check probes.","type":"string"},"environment":{"description":"Deployed environment (MESH_ENV).","type":"string"},"ok":{"type":"boolean"},"serverTime":{"description":"Database server time, useful for clock-skew checks against the API host.","type":"string"},"service":{"description":"Service identity.","type":"string"}},"required":["ok","service","environment","dependency","serverTime"],"type":"object"}}},"description":"Readiness payload."},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Database unreachable."}}},"description":"Database unreachable."}},"security":[],"summary":"Readiness — Postgres reachability.","tags":["discovery"]}},"/api/health/ready":{"get":{"description":"Probes every critical dependency in parallel, each with a short per-probe timeout. Returns 200 when every critical dependency is reachable, 503 otherwise. The body shape is identical on both (ADR 0023 carve-out from the uniform error envelope). Public — no token required so readiness gates work before a caller has provisioned credentials. The only critical dependency is the loc-mesh Postgres.","responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"description":"Aggregate readiness payload. Identical shape on 200 and 503.","properties":{"dependencies":{"items":{"additionalProperties":false,"properties":{"critical":{"description":"When true, this dependency being down forces overall ok=false (503).","type":"boolean"},"error":{"description":"Short, leak-free failure reason (present only when ok is false).","type":"string"},"latencyMs":{"description":"How long this probe took, in milliseconds.","type":"integer"},"name":{"description":"Dependency name (e.g. \"postgres\").","type":"string"},"ok":{"description":"Whether this dependency probe succeeded.","type":"boolean"}},"required":["name","critical","ok","latencyMs"],"type":"object"},"type":"array"},"environment":{"description":"Deployed environment (MESH_ENV).","type":"string"},"ok":{"description":"True only if every critical dependency is ok.","type":"boolean"},"service":{"description":"Service identity.","type":"string"}},"required":["ok","service","environment","dependencies"],"type":"object"}}},"description":"Aggregate readiness payload. Identical shape on 200 and 503."},"503":{"content":{"application/json":{"schema":{"additionalProperties":false,"description":"Aggregate readiness payload. Identical shape on 200 and 503.","properties":{"dependencies":{"items":{"additionalProperties":false,"properties":{"critical":{"description":"When true, this dependency being down forces overall ok=false (503).","type":"boolean"},"error":{"description":"Short, leak-free failure reason (present only when ok is false).","type":"string"},"latencyMs":{"description":"How long this probe took, in milliseconds.","type":"integer"},"name":{"description":"Dependency name (e.g. \"postgres\").","type":"string"},"ok":{"description":"Whether this dependency probe succeeded.","type":"boolean"}},"required":["name","critical","ok","latencyMs"],"type":"object"},"type":"array"},"environment":{"description":"Deployed environment (MESH_ENV).","type":"string"},"ok":{"description":"True only if every critical dependency is ok.","type":"boolean"},"service":{"description":"Service identity.","type":"string"}},"required":["ok","service","environment","dependencies"],"type":"object"}}},"description":"Aggregate readiness payload. Identical shape on 200 and 503."}},"security":[],"summary":"Deep readiness — every critical dependency, probed in parallel.","tags":["discovery"]}},"/api/openapi.json":{"get":{"description":"Authoritative request/response shapes for every endpoint. Generated from per-route schemas — cannot drift from the implementation. Public — no token required.","responses":{"200":{"description":"Default Response"}},"security":[],"summary":"Generated OpenAPI 3.1 contract.","tags":["discovery"]}},"/api/quote-statuses":{"get":{"description":"⚠️ READ ONLY and the same for every tenant. 🔴 `accepted` records a fact and nothing else — turning an accepted quote into work is a lifecycle and belongs to the product, not the platform.","responses":{"200":{"content":{"application/json":{"schema":{"description":"Unpaginated collection.","properties":{"items":{"items":{"$ref":"#/components/schemas/lookup"},"type":"array"}},"required":["items"],"type":"object"}}},"description":"Unpaginated collection."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."}},"security":[{"bearerAuth":[]}],"summary":"Where a quote can be in its life.","tags":["vocabularies"]}},"/api/quotes":{"get":{"description":"Cursor-paginated, newest first. ⭐ `openOnly=true` is the question a sales person actually asks — what is still out there waiting for an answer. Nobody asks \"show me quotes in state sent OR draft\".\n\n⚠️ `isExpired` is derived from the date and is NOT the same as the `expired` status: a quote past its date that nobody has swept reads as expired here, but one that was ACCEPTED on its last valid day never does.","parameters":[{"in":"query","name":"cursor","required":false,"schema":{"type":"string"}},{"description":"Defaults to 50; above 200 is clamped.","in":"query","name":"limit","required":false,"schema":{"pattern":"^[0-9]+$","type":"string"}},{"in":"query","name":"statusCode","required":false,"schema":{"enum":["draft","sent","accepted","declined","expired","cancelled"],"type":"string"}},{"in":"query","name":"customerId","required":false,"schema":{"pattern":"^[0-9]+$","type":"string"}},{"description":"Exact match.","in":"query","name":"quoteNumber","required":false,"schema":{"maxLength":200,"type":"string"}},{"description":"Quotes whose offer lapses before this date.","in":"query","name":"expiringBefore","required":false,"schema":{"format":"date","type":"string"}},{"description":"⭐ Still awaiting an answer — not answered and not in a final state.","in":"query","name":"openOnly","required":false,"schema":{"enum":["true","false"],"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"description":"Cursor-paginated collection (design/api-standards.md §9). Offset pagination is forbidden.","properties":{"items":{"items":{"$ref":"#/components/schemas/quote"},"type":"array"},"nextCursor":{"description":"Opaque cursor for the next page, or null if this is the last page.","type":["null","string"]}},"required":["items","nextCursor"],"type":"object"}}},"description":"Cursor-paginated collection (design/api-standards.md §9). Offset pagination is forbidden."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."}},"security":[{"bearerAuth":[]}],"summary":"List quotes.","tags":["quotes"]},"post":{"description":"Created as a draft with no lines — add them, then send it.\n\n🔴 **Charges only.** There is no cost side here and there must not be: nobody is paid for a job nobody has done.\n\n⚠️ **`expiryDate` is nullable and means NO EXPIRY.** An open-ended quote is a real thing a tenant sends, and defaulting it to thirty days would withdraw an offer nobody withdrew.","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"currencyCode":{"description":"Defaults to the tenant's. Stored per quote, so a historical document is never restated in today's default.","maxLength":3,"minLength":3,"type":"string"},"customerId":{"pattern":"^[0-9]+$","type":"string"},"expiryDate":{"description":"🔴 The date the offer stops standing — the one field a quote has that an invoice does not.","format":"date","type":["string","null"]},"issueDate":{"description":"Defaults to today.","format":"date","type":"string"},"notes":{"description":"⚠️ Internal. Appears on no document unless your template asks for it.","maxLength":4000,"type":["string","null"]},"numberPrefix":{"description":"Defaults to `Q-`.","maxLength":50,"type":["string","null"]},"numberSuffix":{"maxLength":50,"type":["string","null"]},"quoteNumber":{"description":"An explicit override. Otherwise the next number for this tenant is issued.","maxLength":200,"type":["string","null"]},"summary":{"description":"What the customer is being quoted for, in their words. ⭐ A quote is read by someone who was not in the conversation that produced it.","maxLength":4000,"type":["string","null"]},"terms":{"maxLength":8000,"type":["string","null"]}},"required":["customerId"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/quote"}}},"description":"Default Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"A quote number already in use."}}},"description":"A quote number already in use."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Well-formed but not acceptable — a locked quote, an expiry before the issue date, or a referenced row that does not exist."}}},"description":"Well-formed but not acceptable — a locked quote, an expiry before the issue date, or a referenced row that does not exist."}},"security":[{"bearerAuth":[]}],"summary":"Create a quote.","tags":["quotes"]}},"/api/quotes/expire-overdue":{"post":{"description":"⚠️ THE STATUS IS SET ONCE RATHER THAN COMPUTED ON READ, and the two are not the same thing. A quote ACCEPTED on its last valid day must not read as expired the next morning — so the status records what happened and the date is evidence.\n\n⚠️ Only quotes nobody has answered are touched. A sweep that moved an accepted quote would rewrite history on a schedule.\n\n⭐ **A scheduled job now runs the same sweep hourly across every tenant**, so this endpoint is for forcing one rather than for keeping the data correct. ⚠️ **Once an hour, not once a minute**: expiry is a DATE, so a quote changes state at most once a day.","responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"expired":{"description":"How many quotes were moved.","type":"integer"}},"required":["expired"],"type":"object"}}},"description":"Default Response"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."}},"security":[{"bearerAuth":[]}],"summary":"Sweep every unanswered quote past its expiry date.","tags":["quotes"]}},"/api/quotes/{quoteId}":{"delete":{"description":"🔴 SOFT DELETE, and the number stays reserved — reissuing a number already sent to a customer is the failure numbering exists to prevent.","parameters":[{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"quoteId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"responses":{"204":{"description":"Deleted."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}}},"description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}},"security":[{"bearerAuth":[]}],"summary":"Delete a quote.","tags":["quotes"]},"get":{"description":"⚠️ A quote belonging to another tenant answers 404, not 403 — confirming that an id exists is itself a disclosure.","parameters":[{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"quoteId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/quote"}}},"description":"Default Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}}},"description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}},"security":[{"bearerAuth":[]}],"summary":"Get one quote.","tags":["quotes"]},"patch":{"description":"⭐ A SENT QUOTE IS STILL EDITABLE. Revising a price and re-sending produces version 2 of the document rather than replacing version 1 — the customer keeps what they were given. It locks once they answer or the tenant withdraws it, and then answers 422 naming the rule.","parameters":[{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"quoteId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"expiryDate":{"format":"date","type":["string","null"]},"issueDate":{"format":"date","type":"string"},"notes":{"maxLength":4000,"type":["string","null"]},"summary":{"maxLength":4000,"type":["string","null"]},"terms":{"maxLength":8000,"type":["string","null"]}},"type":"object"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/quote"}}},"description":"Default Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}}},"description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"A quote number already in use."}}},"description":"A quote number already in use."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Well-formed but not acceptable — a locked quote, an expiry before the issue date, or a referenced row that does not exist."}}},"description":"Well-formed but not acceptable — a locked quote, an expiry before the issue date, or a referenced row that does not exist."}},"security":[{"bearerAuth":[]}],"summary":"Update a quote that has not been answered.","tags":["quotes"]}},"/api/quotes/{quoteId}/documents":{"get":{"description":"⭐ A revised price re-sent to the customer is version 2. Version 1 is what they already have, and it survives.","parameters":[{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"quoteId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"description":"Unpaginated collection.","properties":{"items":{"items":{"$ref":"#/components/schemas/quoteDocument"},"type":"array"}},"required":["items"],"type":"object"}}},"description":"Unpaginated collection."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}}},"description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}},"security":[{"bearerAuth":[]}],"summary":"Every version of this quote's rendered file.","tags":["quotes"]},"post":{"description":"⏸ **This service does not call the renderer itself yet**, and the reason is not in this service: `public-api-document-rendering` writes to object storage and no bucket is bound in any environment, so a render answers 503 whoever asks. Record the version a caller rendered; when storage unblocks, this service fills the same row.\n\n⚠️ The version number is assigned, never supplied.","parameters":[{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"quoteId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"byteSize":{"minimum":1,"type":["integer","null"]},"contentType":{"description":"Defaults to application/pdf.","maxLength":200,"type":"string"},"renderedDocumentId":{"pattern":"^[0-9]+$","type":["string","null"]},"storageKey":{"description":"⚠️ **Leave this out.** Quoting owns the namespace and assigns `tenants/{tenantId}/quotes/{quoteId}/v{n}.pdf` itself (design ADR 0094) — and the version is not known until the row is written.\n\n🔴 **Supplied, it is refused unless it sits inside your own tenant prefix** (`storage.md` invariant 3).","maxLength":1024,"minLength":1,"type":"string"},"supersedeReason":{"description":"Why this version exists. ⚠️ Ignored on version 1.","maxLength":1000,"type":["string","null"]}},"type":"object"}}}},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/quoteDocument"}}},"description":"Default Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"No such quote."}}},"description":"No such quote."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"A quote number already in use."}}},"description":"A quote number already in use."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Well-formed but not acceptable — a locked quote, an expiry before the issue date, or a referenced row that does not exist."}}},"description":"Well-formed but not acceptable — a locked quote, an expiry before the issue date, or a referenced row that does not exist."}},"security":[{"bearerAuth":[]}],"summary":"Record the next version of this quote's document.","tags":["quotes"]}},"/api/quotes/{quoteId}/documents/generate":{"post":{"description":"⭐ **The one call that turns a quote into a document.** It resolves the template, asks the renderer for the bytes, stores them and records the version — in one request. 🔴 **The template comes from quoting settings, not the request**: a tenant base, overridden per customer. ⚠️ **Nothing configured anywhere is refused rather than defaulted** — there is no default, because a document with nobody’s letterhead is not one you would send — and the error names the customer. 🔴 **Your token is forwarded to the renderer**, so no service ever acts as a tenant it cannot prove. ⚠️ **The version is assigned, never supplied**, and a revised price re-sent to the customer is version 2 at a NEW key; version 1 is what they already have, and it survives. ⭐ **A SENT quote can still be rendered**, which is the point — a revision is a new version, not an edit of what was sent.","parameters":[{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"quoteId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"supersedeReason":{"description":"Why this version exists — *\"revised after the customer asked for two fewer drops\"*. ⚠️ Ignored on version 1.","maxLength":1000,"type":["string","null"]}},"type":"object"}}}},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/quoteDocument"}}},"description":"Default Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"No such quote."}}},"description":"No such quote."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"A quote number already in use."}}},"description":"A quote number already in use."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Well-formed but not acceptable — a locked quote, an expiry before the issue date, or a referenced row that does not exist."}}},"description":"Well-formed but not acceptable — a locked quote, an expiry before the issue date, or a referenced row that does not exist."},"502":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The rendering service refused or failed."}}},"description":"The rendering service refused or failed."},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Object storage is not configured here. Not transient."}}},"description":"Object storage is not configured here. Not transient."}},"security":[{"bearerAuth":[]}],"summary":"Render this quote and store the next version of its document.","tags":["quotes"]}},"/api/quotes/{quoteId}/documents/{documentId}/download":{"get":{"description":"🔴 **Returns a LINK, never the bytes.** `design/storage.md` invariant 2: private bytes never transit compute. The browser fetches straight from object storage, which is also why a large document does not time out.\n\n⚠️ **The link is a bearer credential for one object.** It carries its own signature, needs no token, and **cannot be revoked** — only expired. It lives 15 minutes, which is sized for *somebody clicks a button*, not for *an email sits in an inbox until Monday*.\n\n⭐ **The file is named for a human** — the quote number — while the storage key carries the internal id. Those are deliberately different things (design ADR 0094).\n\n⏸ **503 `storage_not_configured`** where no object storage is set, which is honest rather than a generic failure inviting a retry that can never succeed.","parameters":[{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"quoteId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}},{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"documentId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/quoteDocumentDownload"}}},"description":"Default Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}}},"description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"No object storage is configured here. Not transient."}}},"description":"No object storage is configured here. Not transient."}},"security":[{"bearerAuth":[]}],"summary":"A time-limited link to this version of the document.","tags":["quotes"]}},"/api/quotes/{quoteId}/lines":{"get":{"description":"⚠️ No builder column, unlike an invoice line: a quote line is PROPOSED rather than derived, so there is nothing to attribute.","parameters":[{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"quoteId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"description":"Unpaginated collection.","properties":{"items":{"items":{"$ref":"#/components/schemas/quoteLine"},"type":"array"}},"required":["items"],"type":"object"}}},"description":"Unpaginated collection."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}}},"description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}},"security":[{"bearerAuth":[]}],"summary":"The lines on a quote.","tags":["quotes"]},"post":{"description":"⚠️ Tax is yours to supply. Mesh never computes it — the moment a quote calculates its own tax, the platform is in the tax-jurisdiction business. The quote totals are re-summed.","parameters":[{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"quoteId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"accountCode":{"maxLength":100,"type":["string","null"]},"amount":{"description":"Decimal string, excluding tax. ⭐ Negative for a discount line.","pattern":"^-?[0-9]+(\\.[0-9]{1,2})?$","type":"string"},"description":{"maxLength":1000,"minLength":1,"type":"string"},"quantity":{"description":"Defaults to 1.","pattern":"^-?[0-9]+(\\.[0-9]{1,4})?$","type":"string"},"rateId":{"description":"The rate that suggested this price, when one did. ⚠️ Usually null — most quote lines are typed by a person pricing a job that has no shape yet.","pattern":"^[0-9]+$","type":["string","null"]},"taxAmount":{"pattern":"^-?[0-9]+(\\.[0-9]{1,2})?$","type":["string","null"]},"unitAmount":{"pattern":"^-?[0-9]+(\\.[0-9]{1,4})?$","type":["string","null"]}},"required":["description","amount"],"type":"object"}}},"required":true},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/quoteLine"}}},"description":"Default Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"No such quote."}}},"description":"No such quote."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"A quote number already in use."}}},"description":"A quote number already in use."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Well-formed but not acceptable — a locked quote, an expiry before the issue date, or a referenced row that does not exist."}}},"description":"Well-formed but not acceptable — a locked quote, an expiry before the issue date, or a referenced row that does not exist."}},"security":[{"bearerAuth":[]}],"summary":"Add a line to a quote.","tags":["quotes"]}},"/api/quotes/{quoteId}/lines/{lineId}":{"delete":{"parameters":[{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"quoteId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}},{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"lineId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"responses":{"204":{"description":"Deleted."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}}},"description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The quote has been answered and is final."}}},"description":"The quote has been answered and is final."}},"security":[{"bearerAuth":[]}],"summary":"Remove a line from a quote that has not been answered.","tags":["quotes"]}},"/api/quotes/{quoteId}/status":{"post":{"description":"🔴 `accepted` RECORDS A FACT AND DOES NOTHING ELSE. No stops are created, no invoice is raised, no work is scheduled — that is a LIFECYCLE and it belongs to the product built on Mesh. If this service ever started creating work it would have stopped being a platform capability.\n\n⚠️ A quote that has already been answered is final: a customer who changes their mind gets a NEW quote, because rewriting the answer on the old one erases what they were told.\n\nIdempotent — setting the status it already has is a no-op.","parameters":[{"description":"Opaque identifier. Currently numeric; treat as opaque.","in":"path","name":"quoteId","required":true,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"statusCode":{"description":"⭐ `sent` stamps the sent time; `accepted` and `declined` stamp the responded time and lock the quote.","enum":["draft","sent","accepted","declined","expired","cancelled"],"type":"string"}},"required":["statusCode"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/quote"}}},"description":"Default Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}}},"description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"A quote number already in use."}}},"description":"A quote number already in use."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Well-formed but not acceptable — a locked quote, an expiry before the issue date, or a referenced row that does not exist."}}},"description":"Well-formed but not acceptable — a locked quote, an expiry before the issue date, or a referenced row that does not exist."}},"security":[{"bearerAuth":[]}],"summary":"Move a quote to a new status.","tags":["quotes"]}},"/api/quoting-settings":{"get":{"description":"Two levels: a tenant base and a per-customer override. ⚠️ **A level with nothing set is simply absent** rather than present-and-null — the resolved view is what answers *what will actually happen*.","responses":{"200":{"content":{"application/json":{"schema":{"description":"Unpaginated collection.","properties":{"items":{"items":{"$ref":"#/components/schemas/quotingSettings"},"type":"array"}},"required":["items"],"type":"object"}}},"description":"Unpaginated collection."},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."}},"security":[{"bearerAuth":[]}],"summary":"Every level of quoting configuration this tenant has set.","tags":["settings"]},"put":{"description":"⚠️ **An upsert rather than a create, because the natural key is the LEVEL** — a tenant has one base and a customer has one override. A second row for the same level would make resolution depend on insert order, which is the kind of bug that only appears once there is real data.\n\n⚠️ **A customer-scoped setting needs a customerId** and a tenant-scoped one must not carry one; both are refused here AND by a database constraint, because migrations and support scripts write this table too.","requestBody":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"customerId":{"description":"Required for customer scope, forbidden for tenant scope.","pattern":"^[0-9]+$","type":["string","null"]},"documentTemplateId":{"description":"🔴 Which template a quote is rendered with. **Null clears this level**, which makes it inherit again rather than meaning \"no template\".","pattern":"^[0-9]+$","type":["string","null"]},"scopeCode":{"description":"Which level to set.","enum":["tenant","customer"],"type":"string"}},"required":["scopeCode"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/quotingSettings"}}},"description":"Default Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."}}},"description":"Unknown id, or one belonging to another tenant. ⚠️ Deliberately indistinguishable — telling a caller that an id exists but is not theirs is itself a disclosure."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"A quote number already in use."}}},"description":"A quote number already in use."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Well-formed but not acceptable — a locked quote, an expiry before the issue date, or a referenced row that does not exist."}}},"description":"Well-formed but not acceptable — a locked quote, an expiry before the issue date, or a referenced row that does not exist."}},"security":[{"bearerAuth":[]}],"summary":"Set one level of quoting configuration.","tags":["settings"]}},"/api/quoting-settings/resolved":{"get":{"description":"⭐ **`resolvedFrom` is not decoration.** *Why did this customer get that letterhead* is otherwise two queries and a guess, and it is the first thing anybody asks when a document comes out wrong. It reads `tenant`, `customer`, or `not-configured`.","parameters":[{"description":"Omit to see the tenant base alone.","in":"query","name":"customerId","required":false,"schema":{"pattern":"^[0-9]+$","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/quotingSettings"}}},"description":"Default Response"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Malformed request — a field failed validation, or a cursor could not be read."}}},"description":"Malformed request — a field failed validation, or a cursor could not be read."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"The token is valid but lacks the required permission. The message names which one."}}},"description":"The token is valid but lacks the required permission. The message names which one."}},"security":[{"bearerAuth":[]}],"summary":"What a quote for this customer would actually use, and where each value came from.","tags":["settings"]}},"/api/version":{"get":{"description":"Body shape per design/quality-standards.md §3. Anonymous — same reason as /api/health.","responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"properties":{"buildTime":{"type":"string"},"commit":{"type":"string"},"environment":{"type":"string"},"service":{"type":"string"},"version":{"type":"string"}},"required":["service","version","commit","buildTime","environment"],"type":"object"}}},"description":"Default Response"}},"security":[],"summary":"Service identity + build metadata + environment.","tags":["meta"]}},"/api/whoami":{"get":{"description":"Returns the subject, token type, tenant and scopes resolved entirely from the inbound JWT (never from the request body, query or headers). Useful for verifying a token works and inspecting what it carries. Authenticated — any valid token may call it; an absent or invalid token yields 401.","responses":{"200":{"content":{"application/json":{"schema":{"additionalProperties":false,"description":"Identity attached to the request by the bearer-token middleware.","properties":{"scopes":{"description":"Permission codes from the JWT `lm_perms` claim.","items":{"type":"string"},"type":"array"},"service":{"description":"Service identity.","type":"string"},"subject":{"description":"Caller id from the verified token: the JWT `sub` claim, falling back to `client_id` when the token carries no sub (dev-bypass). Never null — an ADR-0023 core field.","type":"string"},"tenant":{"additionalProperties":false,"description":"Tenant scope from the JWT `tenant_id` claim. name/plan are null — this service has no query path to the central tenants table.","properties":{"id":{"description":"JWT `tenant_id` claim. Null if the token carries no tenant scope.","type":["null","integer"]},"name":{"description":"Tenant display name. Null — not enriched by this service.","type":["null","string"]},"plan":{"description":"Tenant plan. Null — not enriched by this service.","type":["null","string"]}},"required":["id","name","plan"],"type":"object"},"tokenType":{"description":"Token kind. Always \"jwt\" for public-api-*.","enum":["jwt","pat","session"],"type":"string"}},"required":["service","subject","tokenType","tenant","scopes"],"type":"object"}}},"description":"Identity attached to the request by the bearer-token middleware."},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/envelope","description":"Missing or invalid bearer token."}}},"description":"Missing or invalid bearer token."}},"security":[{"bearerAuth":[]}],"summary":"Identity resolved from the verified token.","tags":["discovery"]}}},"servers":[{"url":"https://quoting-api.mesh.locate2u.app"}],"tags":[{"description":"Service identity, health, and self-description. Public (no token required).","name":"discovery"},{"description":"Quotes, their lines, their status and their rendered versions. 🔴 Charges only.","name":"quotes"},{"description":"Platform-owned, closed and read-only.","name":"vocabularies"},{"description":"Build metadata.","name":"meta"}]}