{"openapi":"3.1.0","info":{"title":"Wingmark Matching API","version":"0.7.0","description":"Requirements-first venue matching for agents, with isolated synthetic and authenticated-decision public-source catalogs. A local authenticated M1 contract adds persistent qualification, supplier-scoped fictional consent and in-process simulated handover while rejecting real contact data. PAP draft 0.3 foundation discovery and a fail-closed delegated-Session verifier are under implementation, but this OpenAPI API is not yet advertised through PAP and no PAP compatibility is claimed. Unknown requirements remain distinct from known conflicts. Reviews, ratings, popularity and sentiment do not affect matching. No MCP, availability, booking, or quote protocol is implemented."},"servers":[{"url":"http://127.0.0.1:8787","description":"Local Wrangler"}],"paths":{"/.well-known/poppy.json":{"get":{"operationId":"getPoppyDiscovery","summary":"Discover Wingmark's PAP Company metadata","description":"Returns the version-pinned PAP draft 0.3 Company document when the environment has a Company domain, protected-resource origin, issuer and pilot agent allowlist. During the foundation milestone it advertises ordinary web access only; the existing OpenAPI API is not advertised through PAP until the interface milestone passes.","responses":{"200":{"description":"PAP Company discovery document","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PoppyDiscovery"}}}},"503":{"$ref":"#/components/responses/PapUnconfigured"}}}},"/.well-known/oauth-protected-resource":{"get":{"operationId":"getOAuthProtectedResourceMetadata","summary":"Discover the authorization issuer for Wingmark's Company domain","description":"Returns RFC 9728 protected-resource metadata for the exact configured API resource origin, which may differ from the Company domain. The external issuer must be selected and independently validated before PAP sign-in is enabled.","responses":{"200":{"description":"Protected-resource metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OAuthProtectedResourceMetadata"}}}},"503":{"$ref":"#/components/responses/PapUnconfigured"}}}},"/v1/admin/snapshots":{"post":{"operationId":"importSourceSnapshot","security":[{"OperatorToken":[]}],"summary":"Import a bounded captured public source into review","description":"No remote fetch is performed. Raw HTML is limited to 2 MiB decoded UTF-8 and the total request to 3 MiB. Omit normalization for a direct capture no larger than 256 KiB. evidence-html-1 removes comments, styles and non-JSON-LD scripts; evidence-html-2 additionally removes presentation-only elements and attributes and compacts markup whitespace. Both produce a separately hashed evidence artifact capped at 256 KiB. Exact import replay is deduplicated. Identity evidence is required. Publication requires a separate review.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"venueId":{"type":"string","pattern":"^[a-z0-9_-]{1,80}$"},"slug":{"type":"string","pattern":"^[a-z0-9-]{1,80}$"},"name":{"type":"string","minLength":1,"maxLength":120},"city":{"type":"string","minLength":1,"maxLength":100},"areaCode":{"type":"string","enum":["los_angeles","orange_county","san_diego","santa_barbara","palm_springs"]},"identityEvidence":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":1000},"city":{"type":"string","minLength":1,"maxLength":1000}},"required":["name","city"],"additionalProperties":false},"url":{"type":"string","format":"uri"},"fetchedAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"html":{"type":"string","minLength":1,"maxLength":2097152},"normalization":{"type":"string","enum":["identity-1","evidence-html-1","evidence-html-2"]}},"required":["venueId","slug","name","city","areaCode","identityEvidence","url","fetchedAt","html"],"additionalProperties":false}}}},"responses":{"201":{"description":"Draft created or exact replay located","content":{"application/json":{"schema":{"type":"object","required":["id","status","duplicate"],"properties":{"id":{"type":"string"},"status":{"enum":["pending","published","rejected"]},"duplicate":{"type":"boolean"}}}}}},"400":{"description":"Malformed input"},"401":{"description":"Missing or incorrect operator token"},"404":{"description":"Record not found"},"409":{"description":"Stale revision or previously reviewed draft"},"413":{"description":"Source or request exceeded byte limit"},"422":{"description":"Evidence, timestamp or storage validation failed; existing publication retained"},"503":{"description":"Operator token or source bucket is not configured"}}}},"/v1/admin/drafts":{"get":{"operationId":"listReviewDrafts","security":[{"OperatorToken":[]}],"summary":"List latest 100 drafts and review states","responses":{"200":{"description":"Draft metadata"},"400":{"description":"Malformed input"},"401":{"description":"Missing or incorrect operator token"},"404":{"description":"Record not found"},"409":{"description":"Stale revision or previously reviewed draft"},"413":{"description":"Source or request exceeded byte limit"},"422":{"description":"Evidence, timestamp or storage validation failed; existing publication retained"},"503":{"description":"Operator token or source bucket is not configured"}}}},"/v1/admin/drafts/{id}":{"get":{"operationId":"getReviewDraft","security":[{"OperatorToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"summary":"Read extracted assertions, snapshot metadata and current profile","responses":{"200":{"description":"Draft with candidate input and assertions, base revision and current publication"},"400":{"description":"Malformed input"},"401":{"description":"Missing or incorrect operator token"},"404":{"description":"Record not found"},"409":{"description":"Stale revision or previously reviewed draft"},"413":{"description":"Source or request exceeded byte limit"},"422":{"description":"Evidence, timestamp or storage validation failed; existing publication retained"},"503":{"description":"Operator token or source bucket is not configured"}}}},"/v1/admin/drafts/{id}/source":{"get":{"operationId":"getInertEvidenceArtifact","security":[{"OperatorToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"summary":"Read the exact publication evidence artifact as inert text","responses":{"200":{"description":"Bounded evidence artifact, never interpreted as HTML","content":{"text/plain":{"schema":{"type":"string"}}}},"400":{"description":"Malformed input"},"401":{"description":"Missing or incorrect operator token"},"404":{"description":"Record not found"},"409":{"description":"Stale revision or previously reviewed draft"},"413":{"description":"Source or request exceeded byte limit"},"422":{"description":"Evidence, timestamp or storage validation failed; existing publication retained"},"503":{"description":"Operator token or source bucket is not configured"}}}},"/v1/admin/drafts/{id}/raw-source":{"get":{"operationId":"getInertRawSource","security":[{"OperatorToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"summary":"Read the immutable original response as inert text","responses":{"200":{"description":"Original response, never interpreted as HTML","content":{"text/plain":{"schema":{"type":"string"}}}},"400":{"description":"Malformed input"},"401":{"description":"Missing or incorrect operator token"},"404":{"description":"Record not found"},"409":{"description":"Stale revision or previously reviewed draft"},"413":{"description":"Source or request exceeded byte limit"},"422":{"description":"Evidence, timestamp or storage validation failed; existing publication retained"},"503":{"description":"Operator token or source bucket is not configured"}}}},"/v1/admin/drafts/{id}/review-start":{"post":{"operationId":"startDraftReview","security":[{"OperatorToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"summary":"Start or resume server-timed review","description":"Idempotently records the first operator review start for a pending draft. Queue time before this action is excluded from review duration.","responses":{"200":{"description":"Stable server-recorded review start timestamp","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["id","reviewStartedAt"],"properties":{"id":{"type":"string"},"reviewStartedAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Malformed input"},"401":{"description":"Missing or incorrect operator token"},"404":{"description":"Record not found"},"409":{"description":"Stale revision or previously reviewed draft"},"413":{"description":"Source or request exceeded byte limit"},"422":{"description":"Evidence, timestamp or storage validation failed; existing publication retained"},"503":{"description":"Operator token or source bucket is not configured"}}}},"/v1/admin/drafts/{id}/review":{"post":{"operationId":"reviewSourceDraft","security":[{"OperatorToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"summary":"Publish reviewed assertions or reject a draft","description":"Assertions can be corrected or cleared to null. Require verbatim evidence and one value per field. Confirmation remains public_unconfirmed or unknown. Stale revisions and supplier-confirmed profile replacement are rejected. Retained fields preserve their original age. A prior review-start action enables server-computed duration; direct API decisions without a start retain a null duration.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"expectedRevision":{"type":"integer","minimum":0,"maximum":9007199254740991},"action":{"type":"string","enum":["publish","reject"]},"reviewer":{"type":"string","minLength":1,"maxLength":100},"note":{"type":"string","minLength":1,"maxLength":1000},"assertions":{"maxItems":3,"type":"array","items":{"type":"object","properties":{"fieldPath":{"type":"string","enum":["$.capacity.meeting","$.capacity.bedrooms","$.capacity.overnightGuests"]},"value":{"anyOf":[{"type":"integer","minimum":0,"maximum":9007199254740991},{"type":"null"}]},"evidence":{"type":"string","minLength":1,"maxLength":1000}},"required":["fieldPath","value","evidence"],"additionalProperties":false}}},"required":["expectedRevision","action","reviewer","note","assertions"],"additionalProperties":false}}}},"responses":{"200":{"description":"Decision recorded with actor, note, assertion count and optional review duration; published revisions retained in history","content":{"application/json":{"schema":{"type":"object","required":["id","status","decisionAt","reviewDurationSeconds","assertionCount"],"properties":{"id":{"type":"string"},"status":{"enum":["published","rejected"]},"decisionAt":{"type":"string","format":"date-time"},"reviewDurationSeconds":{"type":["integer","null"],"minimum":0},"assertionCount":{"type":"integer","minimum":0},"revision":{"type":"integer","minimum":1},"refreshDueAt":{"type":"string","format":"date-time"}}}}}},"400":{"description":"Malformed input"},"401":{"description":"Missing or incorrect operator token"},"404":{"description":"Record not found"},"409":{"description":"Stale revision or previously reviewed draft"},"413":{"description":"Source or request exceeded byte limit"},"422":{"description":"Evidence, timestamp or storage validation failed; existing publication retained"},"503":{"description":"Operator token or source bucket is not configured"}}}},"/v1/admin/review-metrics":{"get":{"operationId":"getReviewMetrics","security":[{"OperatorToken":[]}],"summary":"Summarize the latest 500 review decisions","description":"Reports measured and unmeasured decisions, publication yield, known versus unknown published assertion totals, median/P90/slowest duration and common rejection notes. At least ten measured reviews are required before the sample is marked ready.","responses":{"200":{"description":"Bounded review-effort report; durations are server-recorded seconds","content":{"application/json":{"schema":{"type":"object","required":["window","measurement","outcomes","durationSeconds","commonRejectionReasons"],"properties":{"window":{"type":"object","required":["limit","decisionCount","newestDecisionAt","oldestDecisionAt"],"properties":{"limit":{"type":"integer","const":500},"decisionCount":{"type":"integer","minimum":0},"newestDecisionAt":{"type":["string","null"],"format":"date-time"},"oldestDecisionAt":{"type":["string","null"],"format":"date-time"}}},"measurement":{"type":"object","required":["target","measuredCount","unmeasuredCount","ready"],"properties":{"target":{"type":"integer","const":10},"measuredCount":{"type":"integer","minimum":0},"unmeasuredCount":{"type":"integer","minimum":0},"ready":{"type":"boolean"}}},"outcomes":{"type":"object","required":["published","rejected","publicationYieldBasisPoints","measuredPublishedAssertionCount","unmeasuredPublishedAssertionCount","knownPublishedAssertionTotal"],"properties":{"published":{"type":"integer","minimum":0},"rejected":{"type":"integer","minimum":0},"publicationYieldBasisPoints":{"type":["integer","null"],"minimum":0,"maximum":10000},"measuredPublishedAssertionCount":{"type":"integer","minimum":0},"unmeasuredPublishedAssertionCount":{"type":"integer","minimum":0},"knownPublishedAssertionTotal":{"type":"integer","minimum":0}}},"durationSeconds":{"type":"object","required":["median","p90","slowest"],"properties":{"median":{"type":["number","null"],"minimum":0},"p90":{"type":["integer","null"],"minimum":0},"slowest":{"oneOf":[{"type":"null"},{"type":"object","required":["draftId","outcome","seconds","assertionCount"],"properties":{"draftId":{"type":"string"},"outcome":{"enum":["published","rejected"]},"seconds":{"type":"integer","minimum":0},"assertionCount":{"type":["integer","null"],"minimum":0}}}]}}},"commonRejectionReasons":{"type":"array","maxItems":5,"items":{"type":"object","required":["note","count"],"properties":{"note":{"type":"string"},"count":{"type":"integer","minimum":1}}}}}}}}},"400":{"description":"Malformed input"},"401":{"description":"Missing or incorrect operator token"},"404":{"description":"Record not found"},"409":{"description":"Stale revision or previously reviewed draft"},"413":{"description":"Source or request exceeded byte limit"},"422":{"description":"Evidence, timestamp or storage validation failed; existing publication retained"},"503":{"description":"Operator token or source bucket is not configured"}}}},"/v1/admin/profiles/{id}/suppression":{"post":{"operationId":"setProfileSuppression","security":[{"OperatorToken":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"summary":"Suppress or restore a reviewed profile","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["suppressed","reviewer","note"],"properties":{"suppressed":{"type":"boolean"},"reviewer":{"type":"string","minLength":1,"maxLength":100},"note":{"type":"string","minLength":1,"maxLength":1000}}}}}},"responses":{"200":{"description":"Suppression updated with audit event"},"400":{"description":"Malformed input"},"401":{"description":"Missing or incorrect operator token"},"404":{"description":"Record not found"},"409":{"description":"Stale revision or previously reviewed draft"},"413":{"description":"Source or request exceeded byte limit"},"422":{"description":"Evidence, timestamp or storage validation failed; existing publication retained"},"503":{"description":"Operator token or source bucket is not configured"}}}},"/v1/transactions":{"post":{"operationId":"createQualificationTransaction","security":[{"SyntheticAgentToken":[]}],"summary":"Create a synthetic qualification transaction","description":"M1 experimental contract. Runs matching, binds versioned fictional supplier qualification policies and returns exact buyer questions and supplier facts to verify. Available only in local synthetic mode with a configured agent credential. Real contact data is rejected; later consent/handover operations accept only fictional .invalid contact data.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Opaque 16-100 character key. Reuse is allowed only for an identical request.","schema":{"type":"string","minLength":16,"maxLength":100,"pattern":"^[A-Za-z0-9._:-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateTransactionRequest"}}}},"responses":{"200":{"description":"Identical create request replayed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transaction"}}}},"201":{"description":"Transaction created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transaction"}}}},"400":{"description":"Invalid transaction input or idempotency key"},"401":{"description":"Missing or invalid synthetic-agent bearer token"},"409":{"description":"Idempotency, revision, concurrency, or expiry conflict"},"413":{"$ref":"#/components/responses/RequestTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"description":"Per-agent synthetic request limit exceeded"},"503":{"description":"Synthetic transaction experiment is not enabled"}}}},"/v1/transactions/{transactionId}/answers":{"post":{"operationId":"updateQualificationAnswers","security":[{"SyntheticAgentToken":[]}],"summary":"Supply or replace synthetic qualification answers","description":"Re-evaluates the transaction against the policy versions bound at creation. Requires the owning agent, optimistic revision and an idempotency key. Does not capture contact data or consent.","parameters":[{"name":"transactionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Opaque 16-100 character key. Reuse is allowed only for an identical request.","schema":{"type":"string","minLength":16,"maxLength":100,"pattern":"^[A-Za-z0-9._:-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTransactionAnswersRequest"}}}},"responses":{"200":{"description":"Answers recorded or identical update replayed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transaction"}}}},"400":{"description":"Invalid transaction input or idempotency key"},"401":{"description":"Missing or invalid synthetic-agent bearer token"},"404":{"description":"Transaction not found"},"409":{"description":"Idempotency, revision, concurrency, or expiry conflict"},"413":{"$ref":"#/components/responses/RequestTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"description":"Per-agent synthetic request limit exceeded"},"503":{"description":"Synthetic transaction experiment is not enabled"}}}},"/v1/transactions/{transactionId}/consent":{"post":{"operationId":"recordSyntheticConsent","security":[{"SyntheticAgentToken":[]}],"summary":"Record supplier-scoped synthetic buyer authorization","description":"Accepts only a fictional contact name and reserved .invalid email. Consent is scoped to qualified fictional suppliers and the exact disclosed fields.","parameters":[{"name":"transactionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Opaque 16-100 character key. Reuse is allowed only for an identical request.","schema":{"type":"string","minLength":16,"maxLength":100,"pattern":"^[A-Za-z0-9._:-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecordConsentRequest"}}}},"responses":{"200":{"description":"Identical consent replayed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentResponse"}}}},"201":{"description":"Synthetic consent recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConsentResponse"}}}},"400":{"description":"Invalid transaction input or idempotency key"},"401":{"description":"Missing or invalid synthetic-agent bearer token"},"404":{"description":"Transaction not found for this agent"},"409":{"description":"Idempotency, revision, concurrency, or expiry conflict"},"413":{"$ref":"#/components/responses/RequestTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"description":"Per-agent synthetic request limit exceeded"},"503":{"description":"Synthetic transaction experiment is not enabled"}}}},"/v1/transactions/{transactionId}/handover":{"post":{"operationId":"createSimulatedHandover","security":[{"SyntheticAgentToken":[]}],"summary":"Deliver an authorized lead to the in-process simulator","description":"Creates one idempotent simulated delivery per consented fictional supplier. No communication leaves Wingmark.","parameters":[{"name":"transactionId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Opaque 16-100 character key. Reuse is allowed only for an identical request.","schema":{"type":"string","minLength":16,"maxLength":100,"pattern":"^[A-Za-z0-9._:-]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateHandoverRequest"}}}},"responses":{"200":{"description":"Identical handover replayed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HandoverResponse"}}}},"201":{"description":"Simulated deliveries created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HandoverResponse"}}}},"400":{"description":"Invalid transaction input or idempotency key"},"401":{"description":"Missing or invalid synthetic-agent bearer token"},"404":{"description":"Transaction or consent not found for this agent"},"409":{"description":"Idempotency, revision, concurrency, or expiry conflict"},"413":{"$ref":"#/components/responses/RequestTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"},"429":{"description":"Per-agent synthetic request limit exceeded"},"503":{"description":"Synthetic transaction experiment is not enabled"}}}},"/health":{"get":{"operationId":"getHealth","summary":"Check Worker and catalog database readiness","responses":{"200":{"description":"Ready","content":{"application/json":{"schema":{"type":"object","required":["status","database","timestamp"],"properties":{"status":{"const":"ok"},"database":{"const":"ready"},"timestamp":{"type":"string","format":"date-time"}}}}}},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/v1/coverage":{"get":{"operationId":"getCoverage","summary":"Describe current market and catalog coverage","responses":{"200":{"description":"Coverage summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Coverage"}}}}}}},"/v1/compare":{"post":{"operationId":"compareVenues","summary":"Legacy comparison representation","deprecated":true,"description":"Compatibility route for the original comparison contract. New clients should use POST /v1/match. Stateless. Mandatory failures are excluded; mandatory unknowns are returned separately. Body limit: 32 KiB. Maximum requested result count: 5.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyerBrief"},"examples":{"threeDayOffsite":{"value":{"requestId":"buyer-request-001","event":{"attendees":30,"eventDays":3,"nights":2,"dates":{"startDate":"2027-05-12","endDate":"2027-05-14"}},"location":{"allowedAreaCodes":["los_angeles","orange_county","san_diego","santa_barbara","palm_springs"]},"meeting":{"mandatory":true,"minimumCapacity":30},"accommodation":{"mandatory":true,"guests":30,"rooms":15,"rooming":"double"},"exclusiveUse":{"mandatory":false},"amenities":[{"key":"wifi","mandatory":true},{"key":"projector","mandatory":true}],"budget":{"mandatory":false,"unit":"total","amountMinor":2500000,"currency":"USD"},"maxResults":5}}}}}},"responses":{"200":{"description":"Deterministic comparison","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ComparisonResult"},"examples":{"summary":{"value":{"requestId":"buyer-request-001","generatedAt":"2026-10-23T12:00:00.000Z","catalog":{"synthetic":true,"venuesEvaluated":5},"counts":{"confirmedMatches":1,"uncertainCandidates":3,"excluded":1},"confirmedMatches":[],"uncertainCandidates":[],"excluded":[],"truncated":false,"notices":["All milestone catalog entries are fictional synthetic fixtures."]}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"413":{"$ref":"#/components/responses/RequestTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"}}}},"/v1/match":{"post":{"operationId":"matchVenues","summary":"Match venues to explicit event requirements","description":"Stateless requirements-first matching. A known mandatory conflict makes a venue not applicable; a mandatory unknown requires verification. Reviews, ratings, popularity and sentiment are not inputs. Body limit: 32 KiB. Maximum returned candidate count: 5 across all applicability tiers.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuyerBrief"},"examples":{"threeDayOffsite":{"value":{"requestId":"buyer-request-001","event":{"attendees":30,"eventDays":3,"nights":2,"dates":{"startDate":"2027-05-12","endDate":"2027-05-14"}},"location":{"allowedAreaCodes":["los_angeles","orange_county","san_diego","santa_barbara","palm_springs"]},"meeting":{"mandatory":true,"minimumCapacity":30},"accommodation":{"mandatory":true,"guests":30,"rooms":15,"rooming":"double"},"exclusiveUse":{"mandatory":false},"amenities":[{"key":"wifi","mandatory":true},{"key":"projector","mandatory":true}],"budget":{"mandatory":false,"unit":"total","amountMinor":2500000,"currency":"USD"},"maxResults":5}}}}}},"responses":{"200":{"description":"Deterministic requirements-first matches","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchResult"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"413":{"$ref":"#/components/responses/RequestTooLarge"},"415":{"$ref":"#/components/responses/UnsupportedMediaType"}}}},"/openapi.json":{"get":{"operationId":"getOpenApi","summary":"Return this OpenAPI document","responses":{"200":{"description":"OpenAPI 3.1 document","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"OperatorToken":{"type":"http","scheme":"bearer","description":"Operator secret; supplier authentication is a later milestone."},"SyntheticAgentToken":{"type":"http","scheme":"bearer","description":"Local synthetic-agent credential configured outside the repository. Not a production identity mechanism."}},"schemas":{"PoppyDiscovery":{"type":"object","additionalProperties":true,"required":["protocol_version","organization","auth","web"],"properties":{"protocol_version":{"const":"0.3"},"organization":{"type":"object","additionalProperties":false,"required":["name","domain"],"properties":{"name":{"const":"Wingmark"},"domain":{"type":"string","format":"hostname"}}},"auth":{"type":"object","additionalProperties":false,"required":["issuer"],"properties":{"issuer":{"type":"string","format":"uri","pattern":"^https://"}}},"web":{"type":"object","additionalProperties":false}}},"OAuthProtectedResourceMetadata":{"type":"object","additionalProperties":false,"required":["resource","authorization_servers","bearer_methods_supported"],"properties":{"resource":{"type":"string","format":"uri","pattern":"^https://"},"authorization_servers":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"string","format":"uri","pattern":"^https://"}},"bearer_methods_supported":{"type":"array","items":{"const":"header"}}}},"QualificationAnswer":{"oneOf":[{"type":"object","additionalProperties":false,"required":["key","value"],"properties":{"key":{"const":"budget_authority_confirmed"},"value":{"type":"boolean"}}},{"type":"object","additionalProperties":false,"required":["key","value"],"properties":{"key":{"const":"decision_timeframe_days"},"value":{"type":"integer","minimum":0,"maximum":730}}},{"type":"object","additionalProperties":false,"required":["key","value"],"properties":{"key":{"const":"event_flexibility_days"},"value":{"type":"integer","minimum":0,"maximum":30}}}]},"CreateTransactionRequest":{"type":"object","additionalProperties":false,"required":["apiVersion","brief"],"properties":{"apiVersion":{"const":"2026-10-29"},"brief":{"$ref":"#/components/schemas/BuyerBrief","description":"requestId must be an opaque non-contact identifier using letters, numbers, dot, underscore, colon or hyphen."},"answers":{"type":"array","maxItems":3,"items":{"$ref":"#/components/schemas/QualificationAnswer"}}}},"UpdateTransactionAnswersRequest":{"type":"object","additionalProperties":false,"required":["apiVersion","expectedRevision","answers"],"properties":{"apiVersion":{"const":"2026-10-29"},"expectedRevision":{"type":"integer","minimum":0},"answers":{"type":"array","minItems":1,"maxItems":3,"items":{"$ref":"#/components/schemas/QualificationAnswer"}}}},"Transaction":{"type":"object","additionalProperties":false,"required":["apiVersion","transactionId","agentSubject","revision","status","journeyStage","createdAt","updatedAt","expiresAt","brief","answers","matching","suppliers","nextActions","capabilities","notices"],"properties":{"apiVersion":{"const":"2026-10-29"},"transactionId":{"type":"string","format":"uuid"},"agentSubject":{"type":"string","pattern":"^agent_[a-z0-9_-]{1,60}$"},"revision":{"type":"integer","minimum":0},"status":{"enum":["awaiting_information","verification_required","qualified","no_qualified_suppliers"]},"journeyStage":{"enum":["qualification","consented","handed_over"]},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"brief":{"$ref":"#/components/schemas/BuyerBrief"},"answers":{"type":"array","items":{"$ref":"#/components/schemas/QualificationAnswer"}},"matching":{"$ref":"#/components/schemas/MatchResult"},"suppliers":{"type":"array","items":{"type":"object","required":["venueId","venueName","matchApplicability","state","policy","missingAnswers","failedRequirements","supplierFactsToVerify","knownMatchConflicts"],"properties":{"venueId":{"type":"string"},"venueName":{"type":"string"},"matchApplicability":{"enum":["applicable_on_record","verification_required","not_applicable"]},"state":{"enum":["qualified","needs_information","verification_required","not_qualified","not_applicable","policy_unavailable"]},"policy":{"oneOf":[{"type":"null"},{"type":"object"}]},"missingAnswers":{"type":"array","items":{"type":"object"}},"failedRequirements":{"type":"array","items":{"type":"object"}},"supplierFactsToVerify":{"type":"array","items":{"type":"object"}},"knownMatchConflicts":{"type":"array","items":{"type":"object"}}}}},"nextActions":{"type":"array","items":{"type":"object","required":["type"],"properties":{"type":{"type":"string"}}}},"capabilities":{"type":"object","additionalProperties":false,"required":["syntheticOnly","buyerContactDataAccepted","syntheticContactDataOnly","consentCaptureAvailable","handoverAvailable","deliveryMode"],"properties":{"syntheticOnly":{"const":true},"buyerContactDataAccepted":{"const":false},"syntheticContactDataOnly":{"const":true},"consentCaptureAvailable":{"const":true},"handoverAvailable":{"const":true},"deliveryMode":{"const":"simulated"}}},"notices":{"type":"array","items":{"type":"string"}}}},"SyntheticContact":{"type":"object","additionalProperties":false,"required":["contactName","email"],"properties":{"contactName":{"type":"string","pattern":"^Synthetic .+ \\(Fictional\\)$"},"email":{"type":"string","format":"email","description":"Must end in the reserved .invalid top-level domain."}}},"RecordConsentRequest":{"type":"object","additionalProperties":false,"required":["apiVersion","expectedRevision","authorizationConfirmed","purpose","selectedVenueIds","disclosedFields","syntheticContact"],"properties":{"apiVersion":{"const":"2026-10-29"},"expectedRevision":{"type":"integer","minimum":0},"authorizationConfirmed":{"const":true},"purpose":{"const":"supplier_lead_handover"},"selectedVenueIds":{"type":"array","minItems":1,"maxItems":5,"uniqueItems":true,"items":{"type":"string"}},"disclosedFields":{"type":"array","minItems":3,"maxItems":3,"uniqueItems":true,"items":{"enum":["contact_name","email","event_requirements"]}},"syntheticContact":{"$ref":"#/components/schemas/SyntheticContact"}}},"ConsentResponse":{"type":"object","additionalProperties":false,"required":["transaction","consent"],"properties":{"transaction":{"$ref":"#/components/schemas/Transaction"},"consent":{"$ref":"#/components/schemas/ConsentRecord"}}},"ConsentRecord":{"type":"object","additionalProperties":false,"required":["id","transactionId","agentSubject","selectedVenueIds","disclosedFields","syntheticContact","purpose","status","createdAt","expiresAt"],"properties":{"id":{"type":"string","format":"uuid"},"transactionId":{"type":"string","format":"uuid"},"agentSubject":{"type":"string"},"selectedVenueIds":{"type":"array","items":{"type":"string"}},"disclosedFields":{"type":"array","items":{"enum":["contact_name","email","event_requirements"]}},"syntheticContact":{"$ref":"#/components/schemas/SyntheticContact"},"purpose":{"const":"supplier_lead_handover"},"status":{"const":"active"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"}}},"CreateHandoverRequest":{"type":"object","additionalProperties":false,"required":["apiVersion","expectedRevision","consentId"],"properties":{"apiVersion":{"const":"2026-10-29"},"expectedRevision":{"type":"integer","minimum":0},"consentId":{"type":"string","format":"uuid"}}},"HandoverResponse":{"type":"object","additionalProperties":false,"required":["transaction","consent","deliveries"],"properties":{"transaction":{"$ref":"#/components/schemas/Transaction"},"consent":{"$ref":"#/components/schemas/ConsentRecord"},"deliveries":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/SimulatedDelivery"}}}},"SimulatedDelivery":{"type":"object","additionalProperties":false,"required":["id","transactionId","consentId","venueId","status","payloadHash","receipt","createdAt"],"properties":{"id":{"type":"string","format":"uuid"},"transactionId":{"type":"string","format":"uuid"},"consentId":{"type":"string","format":"uuid"},"venueId":{"type":"string"},"status":{"const":"delivered_simulated"},"payloadHash":{"type":"string","pattern":"^[a-f0-9]{64}$"},"receipt":{"type":"object","additionalProperties":false,"required":["provider","receiptId","deliveredAt"],"properties":{"provider":{"const":"wingmark_simulator"},"receiptId":{"type":"string"},"deliveredAt":{"type":"string","format":"date-time"}}},"createdAt":{"type":"string","format":"date-time"}}},"BuyerBrief":{"type":"object","additionalProperties":false,"required":["requestId","event","location","meeting","accommodation","exclusiveUse","amenities","budget"],"properties":{"requestId":{"type":"string","minLength":1,"maxLength":100},"event":{"type":"object","additionalProperties":false,"required":["attendees","eventDays","nights","dates"],"properties":{"attendees":{"type":"integer","minimum":15,"maximum":50},"eventDays":{"type":"integer","minimum":1,"maximum":14},"nights":{"type":"integer","minimum":0,"maximum":13},"dates":{"type":"object","additionalProperties":false,"required":["startDate","endDate"],"properties":{"startDate":{"type":"string","format":"date"},"endDate":{"type":"string","format":"date"}}}}},"location":{"type":"object","additionalProperties":false,"required":["allowedAreaCodes"],"properties":{"allowedAreaCodes":{"type":"array","minItems":1,"maxItems":5,"items":{"$ref":"#/components/schemas/AreaCode"}}}},"meeting":{"type":"object","additionalProperties":false,"required":["mandatory","minimumCapacity"],"properties":{"mandatory":{"type":"boolean"},"minimumCapacity":{"type":["integer","null"],"minimum":1}}},"accommodation":{"type":"object","additionalProperties":false,"required":["mandatory","guests","rooms","rooming"],"properties":{"mandatory":{"type":"boolean"},"guests":{"type":"integer","minimum":0},"rooms":{"type":"integer","minimum":0},"rooming":{"enum":["none","single","double","mixed"]}}},"exclusiveUse":{"type":"object","additionalProperties":false,"required":["mandatory"],"properties":{"mandatory":{"type":"boolean"}}},"amenities":{"type":"array","maxItems":6,"items":{"type":"object","additionalProperties":false,"required":["key","mandatory"],"properties":{"key":{"$ref":"#/components/schemas/AmenityKey"},"mandatory":{"type":"boolean"}}}},"budget":{"oneOf":[{"type":"null"},{"type":"object","additionalProperties":false,"required":["mandatory","unit","amountMinor","currency"],"properties":{"mandatory":{"type":"boolean"},"unit":{"enum":["total","per_person"]},"amountMinor":{"type":"integer","minimum":1},"currency":{"const":"USD"}}}]},"maxResults":{"type":"integer","minimum":1,"maximum":5,"default":5}}},"AreaCode":{"enum":["los_angeles","orange_county","san_diego","santa_barbara","palm_springs"]},"AmenityKey":{"enum":["wifi","projector","video_conferencing","outdoor_space","accessible_meeting_space","onsite_catering"]},"ConstraintResult":{"type":"object","required":["requirement","mandatory","status","explanation","venueField"],"properties":{"requirement":{"type":"string"},"mandatory":{"type":"boolean"},"status":{"enum":["pass","fail","unknown"]},"explanation":{"type":"string"},"venueField":{"type":["string","null"]}}},"SourceReference":{"type":"object","additionalProperties":false,"required":["id","title","url","kind","accessedAt"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"url":{"type":"string","format":"uri"},"kind":{"enum":["public_venue_website","supplier_material"]},"accessedAt":{"type":"string","format":"date-time"}}},"FieldProvenance":{"type":"object","additionalProperties":false,"required":["fieldPath","informationSource","confirmationState","sourceId","observedAt"],"properties":{"fieldPath":{"type":"string"},"informationSource":{"enum":["public_source","supplier_confirmed"]},"confirmationState":{"enum":["public_unconfirmed","supplier_confirmed","unknown"]},"sourceId":{"type":["string","null"]},"observedAt":{"type":"string","format":"date-time"},"evidence":{"type":"string","minLength":1,"maxLength":1000}}},"PublicPricingContext":{"type":"object","additionalProperties":false,"required":["summary","unit","amountMinor","currency","sourceId","disclaimer"],"properties":{"summary":{"type":"string"},"unit":{"enum":["event_day","room_night","per_person_event_day","total_event"]},"amountMinor":{"type":["integer","null"],"minimum":0},"currency":{"const":"USD"},"sourceId":{"type":"string"},"disclaimer":{"type":"string"}}},"VenueProfile":{"type":"object","additionalProperties":false,"required":["id","slug","name","description","fictional","location","capacity","rooming","exclusiveUse","amenities","publicPricingContext","sources","provenance","profileVersion","dataAsOf","publishedAt"],"properties":{"id":{"type":"string"},"slug":{"type":"string","pattern":"^[a-z0-9-]+$"},"name":{"type":"string"},"description":{"type":"string"},"fictional":{"type":"boolean"},"location":{"type":"object","additionalProperties":false,"required":["city","region","countryCode","areaCode"],"properties":{"city":{"type":"string"},"region":{"type":"string"},"countryCode":{"const":"US"},"areaCode":{"$ref":"#/components/schemas/AreaCode"}}},"capacity":{"type":"object","additionalProperties":false,"required":["meeting","bedrooms","overnightGuests"],"properties":{"meeting":{"type":["integer","null"],"minimum":1},"bedrooms":{"type":["integer","null"],"minimum":0},"overnightGuests":{"type":["integer","null"],"minimum":0}}},"rooming":{"type":"object","additionalProperties":false,"required":["supported","notes"],"properties":{"supported":{"oneOf":[{"type":"null"},{"type":"array","items":{"enum":["single","double","mixed"]}}]},"notes":{"type":["string","null"]}}},"exclusiveUse":{"type":["boolean","null"]},"amenities":{"type":"object","additionalProperties":{"enum":["available","unavailable","unknown"]}},"publicPricingContext":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/PublicPricingContext"}]},"sources":{"type":"array","items":{"$ref":"#/components/schemas/SourceReference"}},"provenance":{"type":"array","items":{"$ref":"#/components/schemas/FieldProvenance"}},"profileVersion":{"type":"integer","minimum":1},"dataAsOf":{"type":"string","format":"date-time"},"publishedAt":{"type":"string","format":"date-time"}}},"Estimate":{"type":"object","additionalProperties":false,"required":["kind","currency","totalMinor","perPersonMinor","breakdown","assumptions","disclaimer","policy"],"properties":{"kind":{"const":"indicative_supplier_approved_rule"},"currency":{"const":"USD"},"totalMinor":{"type":"integer","minimum":0},"perPersonMinor":{"type":"integer","minimum":0},"breakdown":{"type":"array","items":{"type":"object","additionalProperties":false,"required":["label","quantity","unit","unitAmountMinor","amountMinor"],"properties":{"label":{"type":"string"},"quantity":{"type":"integer","minimum":0},"unit":{"enum":["event_day","room_night","person_event_day","fixed","tax"]},"unitAmountMinor":{"type":"integer","minimum":0},"amountMinor":{"type":"integer","minimum":0}}}},"assumptions":{"type":"array","items":{"type":"string"}},"disclaimer":{"type":"string"},"policy":{"type":"object","additionalProperties":false,"required":["id","version","approvedAt"],"properties":{"id":{"type":"string"},"version":{"type":"integer","minimum":1},"approvedAt":{"type":"string","format":"date-time"}}}}},"Candidate":{"type":"object","description":"Contains the complete runtime-validated venue profile, field provenance, source timestamps, profile version, constraints and any supplier-approved-rule estimate.","required":["venue","classification","constraints","estimate","estimateUnavailableReason","assumptions","missingInformation"],"properties":{"venue":{"$ref":"#/components/schemas/VenueProfile"},"classification":{"enum":["confirmed_match","uncertain_candidate","excluded"]},"constraints":{"type":"array","items":{"$ref":"#/components/schemas/ConstraintResult"}},"estimate":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/Estimate"}]},"estimateUnavailableReason":{"type":["string","null"]},"assumptions":{"type":"array","items":{"type":"string"}},"missingInformation":{"type":"array","items":{"type":"string"}}}},"ComparisonResult":{"type":"object","required":["requestId","generatedAt","catalog","counts","confirmedMatches","uncertainCandidates","excluded","truncated","notices"],"properties":{"requestId":{"type":"string"},"generatedAt":{"type":"string","format":"date-time"},"catalog":{"type":"object","additionalProperties":false,"required":["synthetic","venuesEvaluated"],"properties":{"synthetic":{"type":"boolean"},"venuesEvaluated":{"type":"integer","minimum":0}}},"counts":{"type":"object","additionalProperties":false,"required":["confirmedMatches","uncertainCandidates","excluded"],"properties":{"confirmedMatches":{"type":"integer","minimum":0},"uncertainCandidates":{"type":"integer","minimum":0},"excluded":{"type":"integer","minimum":0}}},"confirmedMatches":{"type":"array","items":{"$ref":"#/components/schemas/Candidate"}},"uncertainCandidates":{"type":"array","items":{"$ref":"#/components/schemas/Candidate"}},"excluded":{"type":"array","items":{"$ref":"#/components/schemas/Candidate"}},"truncated":{"type":"boolean"},"notices":{"type":"array","items":{"type":"string"}}}},"MatchCandidate":{"type":"object","additionalProperties":false,"description":"A venue evaluated only against explicit structured requirements and recorded evidence.","required":["venue","applicability","requirements","requirementSummary","estimate","estimateUnavailableReason","assumptions","knownConflicts","unknownRequirements"],"properties":{"venue":{"$ref":"#/components/schemas/VenueProfile"},"applicability":{"enum":["applicable_on_record","verification_required","not_applicable"]},"requirements":{"type":"array","items":{"$ref":"#/components/schemas/ConstraintResult"}},"requirementSummary":{"type":"object","additionalProperties":false,"required":["passed","failed","unknown"],"properties":{"passed":{"type":"integer","minimum":0},"failed":{"type":"integer","minimum":0},"unknown":{"type":"integer","minimum":0}}},"estimate":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/Estimate"}]},"estimateUnavailableReason":{"type":["string","null"]},"assumptions":{"type":"array","items":{"type":"string"}},"knownConflicts":{"type":"array","items":{"$ref":"#/components/schemas/ConstraintResult"}},"unknownRequirements":{"type":"array","items":{"$ref":"#/components/schemas/ConstraintResult"}}}},"MatchResult":{"type":"object","additionalProperties":false,"required":["requestId","generatedAt","catalog","counts","applicableOnRecord","verificationRequired","notApplicable","truncated","ranking","notices"],"properties":{"requestId":{"type":"string"},"generatedAt":{"type":"string","format":"date-time"},"catalog":{"type":"object","additionalProperties":false,"required":["synthetic","venuesEvaluated"],"properties":{"synthetic":{"type":"boolean"},"venuesEvaluated":{"type":"integer","minimum":0}}},"counts":{"type":"object","additionalProperties":false,"required":["applicableOnRecord","verificationRequired","notApplicable"],"properties":{"applicableOnRecord":{"type":"integer","minimum":0},"verificationRequired":{"type":"integer","minimum":0},"notApplicable":{"type":"integer","minimum":0}}},"applicableOnRecord":{"type":"array","items":{"$ref":"#/components/schemas/MatchCandidate"}},"verificationRequired":{"type":"array","items":{"$ref":"#/components/schemas/MatchCandidate"}},"notApplicable":{"type":"array","items":{"$ref":"#/components/schemas/MatchCandidate"}},"truncated":{"type":"boolean"},"ranking":{"type":"object","additionalProperties":false,"required":["method","subjectiveSignalsUsed","description"],"properties":{"method":{"const":"requirements_first"},"subjectiveSignalsUsed":{"const":false},"description":{"type":"string"}}},"notices":{"type":"array","items":{"type":"string"}}}},"Coverage":{"type":"object","required":["market","catalog","areas","limitations"],"properties":{"market":{"type":"object","additionalProperties":false,"required":["eventType","attendeeRange","geography"],"properties":{"eventType":{"const":"planned_corporate_offsite"},"attendeeRange":{"type":"object","additionalProperties":false,"required":["minimum","maximum"],"properties":{"minimum":{"const":15},"maximum":{"const":50}}},"geography":{"const":"Southern California"}}},"catalog":{"type":"object","additionalProperties":false,"required":["venueCount","fictional","approvedEstimatePolicyCount","latestDataAsOf"],"properties":{"venueCount":{"type":"integer","minimum":0},"fictional":{"type":"boolean"},"approvedEstimatePolicyCount":{"type":"integer","minimum":0},"latestDataAsOf":{"type":["string","null"],"format":"date-time"}}},"areas":{"type":"array","items":{"$ref":"#/components/schemas/AreaCode"}},"limitations":{"type":"array","items":{"type":"string"}}}},"ValidationError":{"type":"object","required":["error","message","issues"],"properties":{"error":{"const":"validation_error"},"message":{"type":"string"},"issues":{"type":"array","items":{"type":"object","required":["path","code","message"],"properties":{"path":{"type":"string"},"code":{"type":"string"},"message":{"type":"string"}}}}}}},"responses":{"ValidationError":{"description":"Invalid, incomplete, or ambiguous brief","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ValidationError"},"example":{"error":"validation_error","message":"The event brief is invalid or ambiguous.","issues":[{"path":"$.meeting.minimumCapacity","code":"custom","message":"minimumCapacity is required when meeting space is mandatory"}]}}}},"RequestTooLarge":{"description":"Request body exceeds 32 KiB","content":{"application/json":{"schema":{"type":"object"}}}},"UnsupportedMediaType":{"description":"Content-Type must be application/json","content":{"application/json":{"schema":{"type":"object"}}}},"ServiceUnavailable":{"description":"Database unavailable","content":{"application/json":{"schema":{"type":"object"}}}},"PapUnconfigured":{"description":"PAP metadata is intentionally unavailable until all environment settings are valid","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"const":"pap_unconfigured"}}}}}}}}}