{"openapi":"3.0.3","info":{"title":"Al-Narjis AI Public API","version":"1.0.0","description":"Customer API for Al-Narjis AI (النرجس), the Arabic-first platform at https://alnarjisai.com. Plans are 790, 1,490, and 2,990 SAR per month before VAT.\n\nواجهة العميل لمنصة النرجس. الباقات 790 و1490 و2990 ريال شهرياً قبل الضريبة.\n\nAuthentication is the portal session cookie after signup or a one-time code. This API does not issue API keys. Owner, admin, webhook, and payment-test routes are not in this document.","contact":{"email":"AlNarjisai@gmail.com","url":"https://alnarjisai.com/contact"}},"servers":[{"url":"https://alnarjisai.com","description":"Production"}],"tags":[{"name":"Status","description":"Liveness and the public status feed."},{"name":"Catalog","description":"Plans and the public agent roster."},{"name":"Portal","description":"Signup and the customer session."},{"name":"Consultant","description":"The public AI CEO diagnosis."},{"name":"Support","description":"Tickets and interest registration."},{"name":"Payments","description":"Moyasar card checkout. Amounts are halalas."},{"name":"Voice","description":"Public voice advisor availability."}],"components":{"securitySchemes":{"portalSession":{"type":"apiKey","in":"cookie","name":"narjis_portal","description":"HttpOnly session cookie set by POST /api/portal/projects or POST /api/portal/login/verify. It is a browser session, not an API key. Send it only to alnarjisai.com."}}},"paths":{"/health":{"get":{"tags":["Status"],"summary":"Process liveness","description":"Cheap liveness check used by the host. A healthy process returns status and the public version. This response does not include database or provider detail.","responses":{"200":{"description":"Success.","content":{"application/json":{"example":{"status":"healthy","version":"1.0.0"}}}}}}},"/api/status":{"get":{"tags":["Status"],"summary":"Public component status","description":"Cached roll-up of the site, /health, the customer portal, and the agent registry. Status words are operational, degraded, or outage. No credentials, hostnames, or error text.","responses":{"200":{"description":"Success.","content":{"application/json":{"example":{"status":"operational","version":"1.0.0","checked_at":"2026-11-12T00:00:00+00:00","components":{"site":{"status":"operational"},"health":{"status":"operational"},"portal":{"status":"operational"},"agents":{"status":"operational","count":39}}}}}}}}},"/api/agents":{"get":{"tags":["Catalog"],"summary":"Public agent roster","description":"Names, categories, and public introductions for the roster. Model identifiers and owner-only fields are omitted unless the caller is the owner, and those fields are not part of this public contract.","responses":{"200":{"description":"Success.","content":{"application/json":{"example":{"agents":[{"slug":"customer_service","name":"Customer service","category":"support","title_ar":"خدمة العملاء","title_en":"Customer service"}]}}}}},"parameters":[{"name":"category","in":"query","required":false,"schema":{"type":"string"},"description":"Optional category filter, such as support or content."}]}},"/api/portal/packages":{"get":{"tags":["Catalog"],"summary":"Subscription plans","description":"The three public plans. price is SAR per month before VAT. amount is the same price in halalas. VAT is not charged while the operator is not VAT-registered.","responses":{"200":{"description":"Success.","content":{"application/json":{"example":{"packages":[{"key":"bidaya","name":"البداية","name_en":"Starter","price":"790","amount":79000}]}}}}}}},"/api/portal/packages/{package_key}/demo":{"get":{"tags":["Catalog"],"summary":"Illustrative plan demo","description":"Sample content for a plan key: bidaya, numuw, or sharikat. The sample is an illustration, not a customer result.","responses":{"200":{"description":"Demo content for the plan."},"404":{"description":"Unknown plan key."}},"parameters":[{"name":"package_key","in":"path","required":true,"schema":{"type":"string","enum":["bidaya","numuw","sharikat"]}}]}},"/api/portal/projects":{"post":{"tags":["Portal"],"summary":"Open a customer project","description":"Creates a pending project and sets the portal session cookie. package is bidaya, numuw, or sharikat. This is the signup call the portal form uses.","responses":{"200":{"description":"Project created. The session cookie is set.","content":{"application/json":{"example":{"project_id":"00000000-0000-4000-8000-000000000001","package":"bidaya","status":"pending","requires_payment":true}}}},"400":{"description":"Unknown package."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"client_name":"Example Studio","phone":"0550000000","email":"owner@example.com","package":"bidaya","addons":0}}}}}},"/api/portal/login/request":{"post":{"tags":["Portal"],"summary":"Request a sign-in code","description":"Sends a one-time code when the email or phone matches a project. The response is the same when it does not, so the call cannot be used to discover accounts. The code itself is never returned.","responses":{"200":{"description":"Success.","content":{"application/json":{"example":{"sent":true,"channel":"email","expires_in":600}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"identifier":"owner@example.com"}}}}}},"/api/portal/login/verify":{"post":{"tags":["Portal"],"summary":"Verify a sign-in code","description":"Checks the code and sets the portal session cookie. A wrong or expired code is rejected and the code is not echoed.","responses":{"200":{"description":"Signed in. The session cookie is set.","content":{"application/json":{"example":{"project_id":"00000000-0000-4000-8000-000000000001"}}}},"401":{"description":"The code is invalid or expired."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"identifier":"owner@example.com","code":"000000"}}}}}},"/api/portal/session":{"get":{"tags":["Portal"],"summary":"Current portal session","description":"Who the session cookie belongs to. With probe=1, a visitor who is signed out gets authenticated false instead of an error.","responses":{"200":{"description":"Success.","content":{"application/json":{"example":{"authenticated":true,"project_id":"00000000-0000-4000-8000-000000000001","status":"pending"}}}}},"security":[{"portalSession":[]}],"parameters":[{"name":"probe","in":"query","required":false,"schema":{"type":"boolean"}}]}},"/api/portal/logout":{"post":{"tags":["Portal"],"summary":"End the portal session","description":"Clears the portal session cookie.","responses":{"200":{"description":"Success.","content":{"application/json":{"example":{"ok":true}}}}},"security":[{"portalSession":[]}]}},"/api/portal/projects/{project_id}":{"get":{"tags":["Portal"],"summary":"Read one project","description":"The signed-in customer's project: plan, status, and team. Another customer's id is rejected.","responses":{"200":{"description":"The project.","content":{"application/json":{"example":{"project_id":"00000000-0000-4000-8000-000000000001","package":"bidaya","status":"pending","requires_payment":true}}}},"401":{"description":"Portal login required."}},"security":[{"portalSession":[]}],"parameters":[{"name":"project_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]}},"/api/ceo/consult":{"post":{"tags":["Consultant"],"summary":"Ask the AI CEO for a plan","description":"Diagnoses a business goal and recommends a real plan from the catalog. No API key is required. The text is not stored as a lead.","responses":{"200":{"description":"A diagnosis and a recommended plan.","content":{"application/json":{"example":{"plan":{"key":"bidaya","name_en":"Starter","price":"790"}}}}},"400":{"description":"The problem is too short."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"problem":"Customers ask about orders on WhatsApp and nobody follows up.","lang":"en"}}}}}},"/api/support/ticket":{"post":{"tags":["Support"],"summary":"Open a support ticket","description":"Stores a support question and tells the customer the reply window. consent must be true. The reference is an id, not a secret.","responses":{"200":{"description":"Ticket stored.","content":{"application/json":{"example":{"ok":true,"reference":"T-EXAMPLE","response_time":"within one business day"}}}},"422":{"description":"A required field is missing or consent was not given."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"name":"Example Studio","email":"owner@example.com","question":"How do I add another agent?","consent":true,"lang":"en"}}}}}},"/api/leads":{"post":{"tags":["Support"],"summary":"Register interest","description":"Public lead form. A phone, when sent, must be a real number. The response contains the new lead id only.","responses":{"200":{"description":"Success.","content":{"application/json":{"example":{"success":true,"lead_id":"00000000-0000-4000-8000-000000000002","email_queued":true}}}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"name":"Example Studio","phone":"0550000000","email":"owner@example.com","message":"I want the Starter plan.","package":"bidaya"}}}}}},"/api/payments/capabilities":{"get":{"tags":["Payments"],"summary":"Which payment methods can take money","description":"Booleans and public labels only. Card checkout is Moyasar (mada, Visa, Mastercard). No key, bank account, or webhook value is included.","responses":{"200":{"description":"Success.","content":{"application/json":{"example":{"card":false,"paypal":false,"moyasar_status":"unavailable","methods":{"mada":false,"creditcard":false,"stcpay":false,"paypal":false}}}}}}}},"/api/payments":{"post":{"tags":["Payments"],"summary":"Start a card payment","description":"Starts a guest card payment. method is mada, creditcard, or stcpay. refund_consent must be true. amount in the response is halalas (790 SAR is 79000). The reply may include a checkout URL. It never includes the Moyasar secret key.","responses":{"200":{"description":"Payment started. Send the buyer to redirect_url.","content":{"application/json":{"example":{"payment_id":"00000000-0000-4000-8000-000000000003","status":"pending","gateway":"moyasar","redirect_url":"https://checkout.moyasar.com/invoices/example","amount":79000,"vat":0,"total":79000}}}},"400":{"description":"The method or the package is not accepted."},"422":{"description":"Refund consent was not given."},"503":{"description":"Card checkout is not open."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"},"example":{"package":"bidaya","method":"creditcard","customer_name":"Example Studio","customer_phone":"0550000000","customer_email":"owner@example.com","billing_period":"monthly","refund_consent":true}}}}}},"/api/voice/status":{"get":{"tags":["Voice"],"summary":"Voice advisor availability","description":"Whether the public voice advisor can start a call. This call does not mint a client credential.","responses":{"200":{"description":"Success.","content":{"application/json":{"example":{"ok":false,"reason":"unconfigured","max_seconds":180}}}}}}}}}