{ "openapi": "3.1.0", "info": { "title": "ayala-attia.co.il public API", "version": "1.0.0", "description": "Public, unauthenticated, read-only endpoints an AI agent can call on ayala-attia.co.il — the site of אילה עטיה (Ayala Attia), emotional therapist in Tel Aviv. No API key, OAuth, or registration; CORS is open. Content is Hebrew. All data is retrieved from the site's published content — nothing is generated. There is NO booking-execution endpoint: booking is human-to-human via WhatsApp/phone (see getBookingInfo). Unmatched /api/* paths return the Error envelope with code=not_found (HTTP 404).\n\nRate limits: 60 requests per IP per minute, genuinely enforced. Every response carries RFC RateLimit headers (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset) plus the X-RateLimit-* mirrors; a 429 carries Retry-After. The counter is per serverless instance, so bursts may see slightly MORE headroom than declared, never less.\n\nIdempotency: every operation on this API is read-only and naturally idempotent. An Idempotency-Key request header is accepted on all endpoints (including POST /ask and POST /api/v1/batch) and echoed back unchanged, so retrying agents can correlate responses safely — a retry can never duplicate a record because nothing writes.\n\nPagination: list endpoints (listServices, searchFaq) use cursor pagination — pass limit (1-50) and the opaque nextCursor from the previous response as cursor. nextCursor is null on the last page.\n\nVersioning & deprecation policy: this is major version 1 (path-versioned /api/v1, X-API-Version response header). Breaking changes ship as a new major version; a version scheduled for removal is announced in advance via Deprecation and Sunset response headers (RFC 9745 / RFC 8594) and stays available for at least 6 months after its successor is announced.", "contact": { "name": "אילה עטיה", "url": "https://ayala-attia.co.il" } }, "servers": [ { "url": "https://ayala-attia.co.il" } ], "paths": { "/api/v1/profile": { "get": { "operationId": "getProfile", "summary": "Practice profile", "description": "The practice's public identity: name, credentials (MSW), specialties, clinic address, languages, and contact channels.", "responses": { "200": { "description": "The practice profile.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Profile" } } } } } } }, "/api/v1/services": { "get": { "operationId": "listServices", "summary": "List therapy services", "description": "The therapy services offered (individual emotional therapy, depression, anxiety, trauma & PTSD, support after sexual abuse, free intro session). Optional ?q= keyword filter.", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Keyword filter matched against service names and descriptions." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50 }, "description": "Page size (cursor pagination). Omit to receive the full list." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor from the previous response's nextCursor field." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Optional client-supplied idempotency key. All operations are read-only (naturally idempotent); the key is echoed back in the Idempotency-Key response header so retries can be correlated." } ], "responses": { "200": { "description": "Matching services (cursor-paginated).", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceList" } } } }, "429": { "description": "Rate limit exceeded (60 requests/IP/minute).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/faq": { "get": { "operationId": "searchFaq", "summary": "FAQ (with optional retrieval)", "description": "Published FAQ entries (Hebrew). With ?q=, performs deterministic keyword retrieval and returns only matching entries.", "parameters": [ { "name": "q", "in": "query", "required": false, "schema": { "type": "string" }, "description": "A natural-language question, Hebrew or English." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50 }, "description": "Page size (cursor pagination). Omit to receive the full list." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Opaque cursor from the previous response's nextCursor field." }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Optional client-supplied idempotency key. All operations are read-only (naturally idempotent); the key is echoed back in the Idempotency-Key response header so retries can be correlated." } ], "responses": { "200": { "description": "Matching FAQ entries (cursor-paginated).", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FaqList" } } } }, "429": { "description": "Rate limit exceeded (60 requests/IP/minute).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/booking": { "get": { "operationId": "getBookingInfo", "summary": "How booking works (contact-only)", "description": "States machine-readably that there is NO automated booking system: booking happens over WhatsApp or phone, and the first intro session is free. Route users to these channels instead of expecting a booking API.", "responses": { "200": { "description": "Booking channels.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingInfo" } } } } } } }, "/api/v1/batch": { "post": { "operationId": "batch", "summary": "Batch read operations", "description": "Run up to 10 read operations in one request (profile, services, faq, booking) — one round-trip for full practice context. All operations are read-only; Idempotency-Key is accepted and echoed.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Optional client-supplied idempotency key. All operations are read-only (naturally idempotent); the key is echoed back in the Idempotency-Key response header so retries can be correlated." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "operations" ], "properties": { "operations": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "object", "required": [ "op" ], "properties": { "op": { "type": "string", "enum": [ "profile", "services", "faq", "booking" ] }, "params": { "type": "object", "properties": { "q": { "type": "string" } } } } } } } } } } }, "responses": { "200": { "description": "Per-operation results, in request order.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchResult" } } } }, "400": { "description": "Invalid operations array.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 requests/IP/minute).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ask": { "post": { "operationId": "ask", "summary": "NLWeb natural-language query", "description": "Microsoft NLWeb endpoint. Send {\"query\": \"...\"} (Hebrew or English); answers are retrieved deterministically from the published FAQ/services — no generative model. SSE streaming (start/result/complete) via Accept: text/event-stream, ?streaming=true, or {\"prefer\":{\"streaming\":true}}.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 128 }, "description": "Optional client-supplied idempotency key. All operations are read-only (naturally idempotent); the key is echoed back in the Idempotency-Key response header so retries can be correlated." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "maxLength": 2000 }, "prefer": { "type": "object", "properties": { "streaming": { "type": "boolean" } } } } } } } }, "responses": { "200": { "description": "NLWeb response with _meta {response_type: 'nlws', version}, answer, and schema.org-typed results. text/event-stream when streaming is requested.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NlwebResponse" } }, "text/event-stream": { "schema": { "type": "string" } } } }, "400": { "description": "Query too long.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (60 requests/IP/minute).", "headers": { "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "operationId": "askGet", "summary": "NLWeb query via GET", "description": "Same as POST /ask, with the query passed as ?query=.", "parameters": [ { "name": "query", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "streaming", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "NLWeb response.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NlwebResponse" } } } } } } }, "/api/mcp": { "post": { "operationId": "mcp", "summary": "MCP server (Streamable HTTP, JSON-RPC 2.0)", "description": "Model Context Protocol server. Methods: initialize, tools/list, tools/call, resources/list, resources/read, ping. Tools: get_practice_info, list_services, search_faq, get_booking_info, read_site_page. Server card: /.well-known/mcp/server-card.json.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "jsonrpc", "method" ], "properties": { "jsonrpc": { "type": "string", "const": "2.0" }, "id": { "type": [ "string", "number", "null" ] }, "method": { "type": "string" }, "params": { "type": "object" } } } } } }, "responses": { "200": { "description": "JSON-RPC 2.0 response.", "headers": { "X-API-Version": { "$ref": "#/components/headers/X-API-Version" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimit-Limit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimit-Remaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimit-Reset" } }, "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "headers": { "X-API-Version": { "description": "Public API major version.", "schema": { "type": "string", "const": "1" } }, "RateLimit-Limit": { "description": "Requests allowed per IP per minute (RFC RateLimit headers).", "schema": { "type": "integer", "const": 60 } }, "RateLimit-Remaining": { "description": "Requests remaining in the current window for this IP.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until the rate-limit window resets.", "schema": { "type": "integer" } } }, "schemas": { "Error": { "type": "object", "required": [ "error", "code" ], "properties": { "error": { "type": "string", "description": "Human-readable error message." }, "code": { "type": "string", "description": "Machine-readable error code (e.g. not_found, method_not_allowed, query_too_long)." }, "hint": { "type": "string" }, "docs": { "type": "string", "format": "uri" } } }, "BatchResult": { "type": "object", "properties": { "count": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "required": [ "op", "status" ], "properties": { "op": { "type": "string" }, "status": { "type": "string", "enum": [ "ok", "error" ] }, "data": { "type": "object" } } } } } }, "Profile": { "type": "object", "properties": { "name": { "type": "string" }, "jobTitle": { "type": "string" }, "description": { "type": "string" }, "credentials": { "type": "string" }, "areaServed": { "type": "string" }, "knowsAbout": { "type": "array", "items": { "type": "string" } }, "address": { "type": "object" }, "language": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "contact": { "type": "object" }, "links": { "type": "object" } } }, "Service": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }, "ServiceList": { "type": "object", "properties": { "count": { "type": "integer", "description": "Items in this page." }, "total": { "type": "integer", "description": "Total matching items across all pages." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page; null on the last page." }, "services": { "type": "array", "items": { "$ref": "#/components/schemas/Service" } } } }, "FaqEntry": { "type": "object", "required": [ "id", "question", "answer" ], "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "answer": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }, "FaqList": { "type": "object", "properties": { "count": { "type": "integer", "description": "Items in this page." }, "total": { "type": "integer", "description": "Total matching items across all pages." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page; null on the last page." }, "query": { "type": "string" }, "faq": { "type": "array", "items": { "$ref": "#/components/schemas/FaqEntry" } } } }, "BookingInfo": { "type": "object", "properties": { "bookingSystem": { "type": "string", "const": "none" }, "capability": { "type": "string", "const": "contact-only" }, "freeIntroSession": { "type": "boolean" }, "channels": { "type": "array", "items": { "type": "object" } }, "note": { "type": "string" } } }, "NlwebResponse": { "type": "object", "properties": { "@context": { "type": "string" }, "_meta": { "type": "object", "properties": { "response_type": { "type": "string", "const": "nlws" }, "version": { "type": "string" } } }, "query": { "type": "string" }, "answer": { "type": "string" }, "results": { "type": "array", "items": { "type": "object" } } } } } } }