{"openapi":"3.1.0","info":{"title":"Fieldworks study catalog API","version":"questionnaire-inline-v1","description":"Public read-only access to the same fictional lamp facts and return policy shown on the website. No credentials are required. These endpoints do not submit selections, place orders, or accept payments. A study selection can be submitted on a product page after recording consent."},"servers":[{"url":"https://cove.miscreants.dev"}],"security":[],"paths":{"/api/agent/products":{"get":{"operationId":"listProducts","summary":"List lamps matching optional product requirements","description":"Filters are combined with AND. Empty filter values are omitted; duplicate filter keys or invalid values return HTTP 400. priceBelow is exclusive and minBatteryHours is inclusive.","parameters":[{"name":"run","in":"query","required":false,"description":"Optional study run identifier. Use the value from the supplied visit URL to associate requests with that run.","schema":{"type":"string","pattern":"^[a-zA-Z0-9_-]{4,80}$"}},{"name":"variant","in":"query","required":false,"description":"Optional study page variant; defaults to standard when no visit context exists.","schema":{"type":"string","enum":["standard","guide"]}},{"name":"priceBelow","in":"query","required":false,"description":"Return products priced strictly below this amount in USD.","schema":{"type":"number","minimum":0,"maximum":100000}},{"name":"minBatteryHours","in":"query","required":false,"description":"Return products with at least this many hours of battery life.","schema":{"type":"number","minimum":0,"maximum":100000}},{"name":"charging","in":"query","required":false,"description":"Return products with this charging connector.","schema":{"type":"string","enum":["USB-C"]}}],"responses":{"200":{"description":"Matching products and the return policy. An empty match is a successful response with total 0.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductList"}}}},"400":{"description":"Invalid or repeated filter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/products/{id}":{"get":{"operationId":"getProduct","summary":"Read a lamp's specifications and its website URL","parameters":[{"name":"run","in":"query","required":false,"description":"Optional study run identifier. Use the value from the supplied visit URL to associate requests with that run.","schema":{"type":"string","pattern":"^[a-zA-Z0-9_-]{4,80}$"}},{"name":"variant","in":"query","required":false,"description":"Optional study page variant; defaults to standard when no visit context exists.","schema":{"type":"string","enum":["standard","guide"]}},{"name":"id","in":"path","required":true,"schema":{"type":"string","enum":["arc-mini","cove-flex","beam-pro"]}}],"responses":{"200":{"description":"Product facts and the return policy.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProductDetail"}}}},"404":{"description":"Unknown product ID.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/agent/returns":{"get":{"operationId":"getReturnPolicy","summary":"Read the fictional return conditions and refund timing","parameters":[{"name":"run","in":"query","required":false,"description":"Optional study run identifier. Use the value from the supplied visit URL to associate requests with that run.","schema":{"type":"string","pattern":"^[a-zA-Z0-9_-]{4,80}$"}},{"name":"variant","in":"query","required":false,"description":"Optional study page variant; defaults to standard when no visit context exists.","schema":{"type":"string","enum":["standard","guide"]}}],"responses":{"200":{"description":"The same return policy displayed on /returns.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PolicyResponse"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}},"Product":{"type":"object","required":["id","name","price","power","batteryHours","weightGrams","description","url"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"price":{"type":"number","minimum":0,"description":"USD"},"power":{"type":"string","enum":["USB-C"]},"batteryHours":{"type":"number","minimum":0},"weightGrams":{"type":"number","minimum":0},"description":{"type":"string"},"url":{"type":"string","format":"uri-reference","description":"Website product page with study run parameters when supplied."}}},"ReturnPolicy":{"type":"object","required":["days","startsFrom","openedPackagingAccepted","damagedItemsAccepted","originalChargingCableRequired","refundMethod","refundProcessingBusinessDays"],"properties":{"days":{"type":"integer"},"startsFrom":{"type":"string"},"openedPackagingAccepted":{"type":"boolean"},"damagedItemsAccepted":{"type":"boolean"},"originalChargingCableRequired":{"type":"boolean"},"refundMethod":{"type":"string"},"refundProcessingBusinessDays":{"type":"integer","description":"Business days after the return arrives."}}},"ResourceLinks":{"type":"object","required":["catalog","automationGuide","returnPolicy","start"],"properties":{"catalog":{"type":"string","format":"uri-reference"},"automationGuide":{"type":"string","format":"uri-reference"},"returnPolicy":{"type":"string","format":"uri-reference"},"start":{"type":"string","format":"uri-reference"}}},"ProductList":{"type":"object","required":["siteRevision","fictional","currency","filters","total","products","returnPolicy","links"],"properties":{"siteRevision":{"type":"string"},"fictional":{"type":"boolean","const":true},"links":{"$ref":"#/components/schemas/ResourceLinks"},"returnPolicy":{"$ref":"#/components/schemas/ReturnPolicy"},"currency":{"type":"string","const":"USD"},"filters":{"type":"object","additionalProperties":false,"properties":{"priceBelow":{"type":"number","minimum":0,"maximum":100000},"minBatteryHours":{"type":"number","minimum":0,"maximum":100000},"charging":{"type":"string","enum":["USB-C"]}}},"total":{"type":"integer","minimum":0},"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}}},"ProductDetail":{"type":"object","required":["siteRevision","fictional","currency","product","returnPolicy","links"],"properties":{"siteRevision":{"type":"string"},"fictional":{"type":"boolean","const":true},"links":{"$ref":"#/components/schemas/ResourceLinks"},"returnPolicy":{"$ref":"#/components/schemas/ReturnPolicy"},"currency":{"type":"string","const":"USD"},"product":{"$ref":"#/components/schemas/Product"}}},"PolicyResponse":{"type":"object","required":["siteRevision","fictional","returnPolicy","links"],"properties":{"siteRevision":{"type":"string"},"fictional":{"type":"boolean","const":true},"links":{"$ref":"#/components/schemas/ResourceLinks"},"returnPolicy":{"$ref":"#/components/schemas/ReturnPolicy"}}}}}}