{"openapi":"3.1.0","info":{"title":"TasteRay Emotional API","version":"0.7.0","summary":"Recommendation API that returns a written reason with every result.","description":"Ranked recommendations for any vertical, each with a written explanation. Send your own catalog in `items` and every result comes from that list, returned with your own `id` and `name`, and fewer than `count` results can come back when some fall outside it. Human-readable reference: https://api.tasteray.com/docs.","contact":{"email":"hello@tasteray.com","url":"https://www.tasteray.com"}},"servers":[{"url":"https://api.tasteray.com"}],"externalDocs":{"description":"API reference","url":"https://api.tasteray.com/docs"},"security":[{"ApiKeyAuth":[]}],"paths":{"/v1/recommend":{"post":{"operationId":"recommend","summary":"Generate recommendations, or rank a list you supply","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecommendationRequest"}}}},"responses":{"200":{"description":"Recommendations.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecommendationResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Per-minute or monthly limit exceeded. Honor the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/explain":{"post":{"operationId":"explain","summary":"Explain why one item fits a person","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExplanationRequest"}}}},"responses":{"200":{"description":"Explanation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExplanationResponse"}}}},"400":{"description":"Invalid request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Per-minute or monthly limit exceeded. Honor the Retry-After header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/usage":{"get":{"operationId":"usage","summary":"Usage for the calling key","responses":{"200":{"description":"Usage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageResponse"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v1/health":{"get":{"operationId":"health","summary":"Service status","security":[],"responses":{"200":{"description":"Healthy or degraded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"RecommendationRequest":{"type":"object","properties":{"vertical":{"type":"string","minLength":1,"description":"What kind of thing to recommend, any non-empty string."},"context":{"type":"object","properties":{"preferences":{"description":"What the person likes, one trait per entry. Required unless profile is set.","type":"array","items":{"type":"string"}},"profile":{"description":"The same information as free text. Required unless preferences is set.","type":"string"},"constraints":{"description":"Hard limits as key-value pairs.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}},"history":{"maxItems":50,"type":"array","items":{"type":"object","properties":{"item":{"type":"string","minLength":1,"description":"Name or identifier of the thing the person already saw."},"rating":{"type":"string","minLength":1,"description":"Free-form rating: \"loved\", \"5 stars\", \"8/10\"."},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["item","rating"]}},"history_text":{"type":"string"}}},"items":{"description":"A list to rank instead of generating from scratch.","type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Your identifier for the item. Returned results come from this list."},"name":{"type":"string"},"description":{"type":"string"},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["id","name"]}},"options":{"type":"object","properties":{"count":{"description":"Results to return, 1 to 10. Default 3.","type":"integer","minimum":1,"maximum":10},"include_alternatives":{"type":"boolean"},"explanation_depth":{"type":"string","enum":["brief","detailed"]},"language":{"description":"Locale code such as es_ES. Default en_US.","type":"string","minLength":1},"grounding":{"description":"Allow web search. Default true, false when items is sent.","type":"boolean"},"research":{"deprecated":true,"description":"Deprecated alias of grounding.","type":"boolean"},"fast":{"description":"Use the low-latency model. Disables grounding.","type":"boolean"}}}},"required":["vertical","context"]},"ExplanationRequest":{"type":"object","properties":{"vertical":{"type":"string","minLength":1},"item":{"type":"object","properties":{"name":{"type":"string","minLength":1},"type":{"type":"string","minLength":1},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["name","type"]},"context":{"type":"object","properties":{"user_preferences":{"type":"array","items":{"type":"string"}},"profile":{"type":"string"},"constraints":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}}},"options":{"type":"object","properties":{"depth":{"type":"string","enum":["brief","detailed"]},"include_alternatives":{"type":"boolean"},"language":{"type":"string","minLength":1},"grounding":{"type":"boolean"},"research":{"deprecated":true,"type":"boolean"},"fast":{"type":"boolean"}}}},"required":["vertical","item","context"]},"RecommendationResponse":{"type":"object","properties":{"recommendations":{"type":"array","items":{"type":"object","properties":{"item":{"type":"object","properties":{"id":{"description":"Your id, present when items was sent","type":"string"},"name":{"type":"string"},"vertical":{"type":"string"},"type":{"type":"string"},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["name","vertical","type"]},"explanation":{"type":"object","properties":{"why_match":{"type":"string"},"key_factors":{"type":"array","items":{"type":"string"}},"potential_concerns":{"type":"array","items":{"type":"string"}}},"required":["why_match","key_factors"]},"confidence":{"type":"number","minimum":0,"maximum":1},"metadata":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["item","explanation","confidence"]},"description":"Ranked results. In items mode each item carries your own id and exact name, results not in your list are dropped, so fewer than `count` can come back."},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"timestamp":{"type":"string"},"processing_time_ms":{"description":"Server-side duration, excluding network time.","type":"number"},"prompt_version":{"type":"string"},"total_results":{"type":"number"},"tool_usage":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["request_id","timestamp"]}},"required":["recommendations","meta"]},"ExplanationResponse":{"type":"object","properties":{"explanation":{"type":"object","properties":{"summary":{"type":"string"},"detailed_reasoning":{"type":"object","properties":{"taste_alignment":{"type":"array","items":{"type":"string"}},"constraint_satisfaction":{"type":"array","items":{"type":"string"}},"unique_factors":{"type":"array","items":{"type":"string"}}},"required":["taste_alignment","constraint_satisfaction","unique_factors"]},"potential_concerns":{"type":"array","items":{"type":"string"}},"alternatives":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"reason":{"type":"string"},"key_difference":{"type":"string"}},"required":["name","reason","key_difference"]}}},"required":["summary","detailed_reasoning","potential_concerns"]},"confidence":{"type":"number","minimum":0,"maximum":1},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"timestamp":{"type":"string"},"processing_time_ms":{"description":"Server-side duration, excluding network time.","type":"number"},"prompt_version":{"type":"string"},"total_results":{"type":"number"},"tool_usage":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["request_id","timestamp"]}},"required":["explanation","confidence","meta"]},"UsageResponse":{"type":"object","properties":{"period":{"type":"string"},"start_date":{"type":"string"},"end_date":{"type":"string"},"usage":{"type":"object","properties":{"requests_made":{"type":"number"},"requests_limit":{"type":"number"},"requests_remaining":{"type":"number"},"percentage_used":{"type":"number"},"reset_date":{"type":"string"}},"required":["requests_made","requests_limit","requests_remaining","percentage_used","reset_date"]},"breakdown_by_vertical":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"}},"breakdown_by_day":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"requests":{"type":"number"}},"required":["date","requests"]}},"tier":{"type":"object","properties":{"name":{"type":"string"},"rate_limit":{"type":"string"}},"required":["name","rate_limit"]}},"required":["period","usage","tier"]},"HealthResponse":{"type":"object","properties":{"status":{"type":"string","enum":["healthy","degraded","unhealthy"]},"version":{"type":"string"},"uptime_seconds":{"type":"number"},"timestamp":{"type":"string"},"checks":{"type":"object","properties":{"ai_service":{"type":"string","enum":["ok","error","degraded"]},"fast_ai_service":{"type":"string","enum":["ok","error","degraded"]},"analytics":{"type":"string","enum":["ok","error","degraded"]},"cache":{"type":"string","enum":["ok","error","degraded"]}},"required":["ai_service","fast_ai_service","analytics","cache"]}},"required":["status","version","timestamp","checks"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{"type":"string"},"suggestion":{"type":"string"},"documentation_url":{"type":"string"}},"required":["code","message"]},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"timestamp":{"type":"string"}},"required":["request_id","timestamp"]}},"required":["error","meta"]}}}}