{ "openapi": "3.1.0", "info": { "title": "Deali (דילי) Public API", "description": "Read-only public API for deali.co.il - an Israeli AliExpress deal aggregator in Hebrew. Provides curated deals with prices in ILS, product details, and Hebrew blog content. No authentication required. For AI agents, a read-only MCP server is also available at https://www.deali.co.il/mcp (server card: /.well-known/mcp/server-card.json).\n\n## Versioning and deprecation\nEndpoints are versioned in the URL path: the current version is **v1** (`/api/v1/...`). The unversioned `/api/site/...` paths are the legacy aliases and remain supported.\n\nBreaking changes ship under a new path prefix (`/api/v2/...`); the previous version keeps working. When a version is retired we announce it at least **180 days** in advance and, for the whole notice period, every response on the retiring version carries the standard `Deprecation` and `Sunset` headers (RFC 9745 / RFC 8594) plus a `Link: <...>; rel=\"successor-version\"` pointing at the replacement. Agents should treat the presence of a `Sunset` header as the signal to migrate.\n\n## Rate limits\nResponses carry the RFC RateLimit headers (`RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset`); a `429` includes `Retry-After`. No authentication is required.\n\n## Pagination\nList endpoints use cursor pagination: pass `limit` and `cursor`, and read `pagination.next_cursor` (null when `has_more` is false).", "version": "1.1.0", "contact": { "name": "Deali", "email": "hello@deali.co.il", "url": "https://www.deali.co.il/contact" } }, "servers": [ { "url": "https://www.deali.co.il" } ], "paths": { "/api/site/deals": { "get": { "operationId": "listDeals", "summary": "List all active deals", "description": "Returns every active curated AliExpress deal (Hebrew titles/descriptions, prices in ILS) plus site-wide affiliate metadata. Responses are edge-cached for up to 10 minutes.", "responses": { "200": { "description": "Deals list", "content": { "application/json": { "schema": { "type": "object", "properties": { "deals": { "type": "array", "items": { "$ref": "#/components/schemas/Deal" } }, "aliHomeUrl": { "type": [ "string", "null" ], "description": "Affiliate link to the AliExpress homepage" }, "dutyFreeMax": { "type": [ "number", "null" ], "description": "Max order value in USD exempt from Israeli import tax" } } } } } } } } }, "/api/site/blog": { "get": { "operationId": "listOrGetBlogPosts", "summary": "List published blog posts, or fetch one by id", "description": "Without parameters, returns all published Hebrew blog posts (buying guides, product roundups, AliExpress tips). With ?id=, returns that post's full HTML content plus related-post suggestions.", "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Post id - returns the single post with full content" } ], "responses": { "200": { "description": "Post list ({posts: [...]}) or single post ({post, related, pillarCallout})", "content": { "application/json": { "schema": { "type": "object", "properties": { "posts": { "type": "array", "items": { "$ref": "#/components/schemas/BlogPostSummary" } }, "post": { "$ref": "#/components/schemas/BlogPost" } } } } } }, "404": { "description": "Post id not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/site/product-detail": { "get": { "operationId": "getProductDetail", "summary": "Live product enrichment (images, description, affiliate link)", "description": "Fetches live enrichment data for one product from AliExpress: gallery images, Hebrew description, a fresh affiliate link, and video URL when available. Slower than the cached catalog - prefer /api/site/deals for browsing.", "parameters": [ { "name": "id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Product id in the form ali_" } ], "responses": { "200": { "description": "Product enrichment", "content": { "application/json": { "schema": { "type": "object", "properties": { "images": { "type": "array", "items": { "type": "string", "format": "uri" } }, "promotionLink": { "type": [ "string", "null" ], "description": "Fresh AliExpress affiliate link" }, "description": { "type": [ "string", "null" ], "description": "Hebrew product description" }, "videoUrl": { "type": [ "string", "null" ] } } } } } }, "400": { "description": "Missing id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/mcp": { "get": { "operationId": "mcpServerInfo", "summary": "MCP server identification", "description": "Returns MCP (Model Context Protocol) server metadata. POST JSON-RPC 2.0 messages (initialize, tools/list, tools/call) to this same URL - Streamable HTTP transport, no authentication. Tools: search_deals, get_product, list_blog_posts, get_blog_post.", "responses": { "200": { "description": "Server info and usage", "content": { "application/json": { "schema": { "type": "object", "description": "JSON-RPC 2.0 message", "properties": { "jsonrpc": { "type": "string" }, "id": { "type": [ "string", "number", "null" ] }, "result": { "type": "object" }, "error": { "type": "object" } } } } } } } }, "post": { "operationId": "mcpRpc", "summary": "MCP JSON-RPC endpoint", "description": "Model Context Protocol over Streamable HTTP. Send JSON-RPC 2.0 requests; errors are returned as structured JSON-RPC error objects.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "JSON-RPC 2.0 request or batch" } } } }, "responses": { "200": { "description": "JSON-RPC response", "content": { "application/json": { "schema": { "type": "object", "description": "JSON-RPC 2.0 message", "properties": { "jsonrpc": { "type": "string" }, "id": { "type": [ "string", "number", "null" ] }, "result": { "type": "object" }, "error": { "type": "object" } } } } } }, "202": { "description": "Notification accepted (no response body)", "content": { "application/json": { "schema": { "type": "object", "description": "JSON-RPC 2.0 message", "properties": { "jsonrpc": { "type": "string" }, "id": { "type": [ "string", "number", "null" ] }, "result": { "type": "object" }, "error": { "type": "object" } } } } } } } } }, "/api/v1/deals": { "get": { "operationId": "listDealsV1", "summary": "List curated AliExpress deals (paginated)", "description": "Cursor-paginated list of curated AliExpress deals for Israel, prices in ILS. No authentication.", "parameters": [ { "name": "limit", "in": "query", "description": "Items per page (1-200, default 50)", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "description": "Opaque offset cursor from pagination.next_cursor", "schema": { "type": "string" } }, { "name": "category", "in": "query", "description": "Filter by category", "schema": { "type": "string", "enum": [ "electronics", "gadgets", "fashion", "home", "sports", "kids", "beauty", "auto" ] } } ], "responses": { "200": { "description": "A page of deals", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Deal" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } }, "required": [ "data", "pagination" ] } } } }, "404": { "description": "Unknown endpoint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Catalog temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ask": { "post": { "operationId": "askNlweb", "summary": "Natural-language search (NLWeb)", "description": "NLWeb endpoint. POST a natural-language query; returns ranked results with an _meta envelope. Send Accept: text/event-stream for SSE streaming.", "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string" } } } } } }, "responses": { "200": { "description": "Ranked results, or an endpoint descriptor when no query is supplied", "content": { "application/json": { "schema": { "type": "object", "properties": { "_meta": { "type": "object", "properties": { "response_type": { "type": "string" }, "version": { "type": "string" }, "streaming_supported": { "type": "boolean" } } }, "query": { "type": "string" }, "site": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "name": { "type": "string" }, "site": { "type": "string" }, "score": { "type": "number" }, "description": { "type": "string" } } } } }, "required": [ "_meta" ] } } } } } } } }, "components": { "schemas": { "Deal": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable product id, e.g. ali_1005010438036376" }, "title": { "type": "string", "description": "Product title (Hebrew)" }, "category": { "type": "string", "enum": [ "electronics", "gadgets", "fashion", "home", "sports", "kids", "beauty", "auto" ] }, "price_ils": { "type": "number", "description": "Current price in ILS" }, "was_price_ils": { "type": "number", "description": "Pre-discount price in ILS" }, "discount_pct": { "type": "number" }, "rating": { "type": "number" }, "reviews_count": { "type": "integer" }, "image_url": { "type": [ "string", "null" ] }, "product_url": { "type": "string" }, "coupon_code": { "type": [ "string", "null" ] } }, "required": [ "id", "title", "category", "price_ils", "product_url" ] }, "BlogPostSummary": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string", "description": "Hebrew title" }, "excerpt": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] }, "cover_url": { "type": [ "string", "null" ], "format": "uri" }, "published_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "BlogPost": { "allOf": [ { "$ref": "#/components/schemas/BlogPostSummary" }, { "type": "object", "properties": { "content": { "type": [ "string", "null" ], "description": "Full HTML content (Hebrew)" }, "author": { "type": [ "string", "null" ] } } } ] }, "Error": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "hint": { "type": "string" }, "documentation": { "type": "string" } }, "required": [ "error" ] }, "Pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "cursor": { "type": "integer" }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass back as `cursor`; null when has_more is false" }, "has_more": { "type": "boolean" }, "total": { "type": "integer" } }, "required": [ "limit", "has_more", "total" ] } } } }