{"openapi":"3.1.2","info":{"title":"Manova API","version":"1.0.0","description":"The public Manova API: the store integration (catalog sync for shops) and the token chat API. Guides are at https://docs.manova.ir."},"servers":[{"url":"https://manova.ir/api/v1/external","description":"Production"}],"tags":[{"name":"Store","description":"Sync a shop's catalog. Authenticated with the store connection key."},{"name":"Chat","description":"Talk to Manova's AI models. Authenticated with an API token."}],"paths":{"/usage":{"get":{"operationId":"get-usage","description":"Credits of the current period. `remainingCredits` is what new replies can use.","summary":"Get credit usage","tags":["Chat"],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"periodStart":{"type":["string","null"]},"periodEnd":{"type":["string","null"]},"includedCredits":{"type":"integer"},"purchasedCredits":{"type":"integer"},"usedCredits":{"type":"integer"},"reservedCredits":{"type":"integer"},"remainingCredits":{},"updatedAt":{"type":["string","null"]}},"required":["periodStart","periodEnd","includedCredits","purchasedCredits","usedCredits","reservedCredits","remainingCredits","updatedAt"]}}}},"401":{"description":"The key is missing, wrong, revoked or expired.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable error code; branch on this.","examples":["UNAUTHENTICATED"]},"message":{"type":"string","description":"A message for people, in Persian.","examples":["کلید API معتبر نیست."]}},"required":["code","message"]}}}},"429":{"description":"Too many requests. Wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable error code; branch on this.","examples":["RATE_LIMITED"]},"message":{"type":"string","description":"A message for people, in Persian.","examples":["درخواست‌ها زیاد شد؛ کمی بعد دوباره تلاش کن."]}},"required":["code","message"]}}}}},"security":[{"token":[]}]}},"/chat/messages":{"post":{"operationId":"send-message","description":"Sends a message and streams the reply as server-sent events (`text/event-stream`): `message.started`, `message.delta`..., then one of `message.completed` / `message.aborted` / `message.failed`, and `usage.updated`. Errors before the stream starts are JSON.\n\n`clientRequestId` must equal the `Idempotency-Key` header. Retrying an id whose reply has ended replays its final events without charging again.\n\nEvents: https://docs.manova.ir/chat-api/streaming","summary":"Send a message","tags":["Chat"],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"The same value as `clientRequestId`.","schema":{"type":"string"},"example":"6f1d2c9e-6b8a-4f0e-9a51-0c2a7d1f4b33"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"conversationId":{"type":["string","null"],"format":"uuid","description":"Continue this conversation; omit it to start a new one."},"content":{"type":"array","description":"The message: one text part.","items":{"type":"object","properties":{"type":{"type":"string","enum":["text"]},"text":{"type":"string","description":"Up to 4,000 characters.","examples":["یک متن کوتاه برای معرفی فروشگاه کفش بنویس"]}},"required":["type","text"]},"minItems":1,"maxItems":1},"projectId":{"type":["string","null"],"format":"uuid","description":"Start the conversation in one of your projects."},"agentId":{"type":["string","null"],"format":"uuid","description":"Answer as one of your agents."},"webSearch":{"type":"boolean","description":"Search the web first and cite the sources."},"mode":{"type":"string","description":"`auto`, a role (`fast`, `smart`, `code`) or a model id.","examples":["auto"]},"clientRequestId":{"type":"string","description":"Your id for this send; the same value as the Idempotency-Key header.","examples":["6f1d2c9e-6b8a-4f0e-9a51-0c2a7d1f4b33"],"minLength":8,"maxLength":100}},"required":["content","mode","clientRequestId"]}}}},"responses":{"200":{"description":"The reply, streamed.","content":{"text/event-stream":{"schema":{"type":"string","description":"Server-sent events: https://docs.manova.ir/chat-api/streaming"}}}},"401":{"description":"The key is missing, wrong, revoked or expired.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable error code; branch on this.","examples":["UNAUTHENTICATED"]},"message":{"type":"string","description":"A message for people, in Persian.","examples":["کلید API معتبر نیست."]}},"required":["code","message"]}}}},"402":{"description":"Not enough credits left for this reply.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable error code; branch on this.","examples":["INSUFFICIENT_CREDITS"]},"message":{"type":"string","description":"A message for people, in Persian.","examples":["اعتبار کافی نیست."]}},"required":["code","message"]}}}},"409":{"description":"This id is still running, or was used with a different body.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable error code; branch on this.","examples":["CONFLICT"]},"message":{"type":"string","description":"A message for people, in Persian.","examples":["این درخواست هنوز در حال اجرا است."]}},"required":["code","message"]}}}},"422":{"$ref":"#/components/responses/ValidationException"},"429":{"description":"Too many requests. Wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable error code; branch on this.","examples":["RATE_LIMITED"]},"message":{"type":"string","description":"A message for people, in Persian.","examples":["درخواست‌ها زیاد شد؛ کمی بعد دوباره تلاش کن."]}},"required":["code","message"]}}}}},"security":[{"token":[]}]}},"/conversations":{"get":{"operationId":"list-conversations","description":"Your conversations, pinned first, then newest first. Pass `nextCursor` back as `cursor` for the next page.","summary":"List conversations","tags":["Chat"],"parameters":[{"name":"projectId","in":"query","description":"Only this project's conversations; `none` for those outside any project.","schema":{"type":"string","maxLength":40}},{"name":"limit","in":"query","description":"1 to 40.","schema":{"type":"integer","default":40}},{"name":"cursor","in":"query","description":"The `nextCursor` of the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"createdAt":{"type":["string","null"]},"updatedAt":{"type":["string","null"]},"lastMessagePreview":{"type":["string","null"]},"projectId":{"type":["string","null"]},"agentId":{"type":["string","null"]},"isPinned":{"type":"boolean"},"createdByUserId":{"type":["integer","null"]}},"required":["id","title","createdAt","updatedAt","lastMessagePreview","projectId","agentId","isPinned","createdByUserId"]}},"nextCursor":{"type":["string","null"]}},"required":["items","nextCursor"]}}}},"401":{"description":"The key is missing, wrong, revoked or expired.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable error code; branch on this.","examples":["UNAUTHENTICATED"]},"message":{"type":"string","description":"A message for people, in Persian.","examples":["کلید API معتبر نیست."]}},"required":["code","message"]}}}},"422":{"$ref":"#/components/responses/ValidationException"},"429":{"description":"Too many requests. Wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable error code; branch on this.","examples":["RATE_LIMITED"]},"message":{"type":"string","description":"A message for people, in Persian.","examples":["درخواست‌ها زیاد شد؛ کمی بعد دوباره تلاش کن."]}},"required":["code","message"]}}}}},"security":[{"token":[]}]}},"/conversations/{id}":{"get":{"operationId":"get-conversation","description":"One conversation with its messages, oldest first.","summary":"Get a conversation","tags":["Chat"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string"},"createdAt":{"type":["string","null"]},"updatedAt":{"type":["string","null"]},"lastMessagePreview":{"type":["string","null"]},"projectId":{"type":["string","null"]},"agentId":{"type":["string","null"]},"isPinned":{"type":"boolean"},"createdByUserId":{"type":["integer","null"]},"messages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"conversationId":{"type":"string","format":"uuid"},"role":{"type":"string","enum":["user","assistant"]},"content":{"type":"array","description":"The text is in the part with `\"type\": \"text\"`.","items":{"type":"object","properties":{"type":{"type":"string","examples":["text"]},"text":{"type":"string"}}}},"status":{"type":"string","description":"`completed`, `streaming`, `aborted` or `failed`."},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","conversationId","role","content","status","createdAt","updatedAt"]}}},"required":["id","title","createdAt","updatedAt","lastMessagePreview","projectId","agentId","isPinned","createdByUserId","messages"]}}}},"401":{"description":"The key is missing, wrong, revoked or expired.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable error code; branch on this.","examples":["UNAUTHENTICATED"]},"message":{"type":"string","description":"A message for people, in Persian.","examples":["کلید API معتبر نیست."]}},"required":["code","message"]}}}},"404":{"description":"No such conversation, or not yours.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable error code; branch on this.","examples":["NOT_FOUND"]},"message":{"type":"string","description":"A message for people, in Persian.","examples":["مورد درخواستی پیدا نشد."]}},"required":["code","message"]}}}},"429":{"description":"Too many requests. Wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable error code; branch on this.","examples":["RATE_LIMITED"]},"message":{"type":"string","description":"A message for people, in Persian.","examples":["درخواست‌ها زیاد شد؛ کمی بعد دوباره تلاش کن."]}},"required":["code","message"]}}}}},"security":[{"token":[]}]}},"/store":{"get":{"operationId":"get-store","description":"The connection as Manova sees it: the assistant's widget key, whether it is active, product counts and the last full sync. A good check that the key works.","summary":"Get the store connection","tags":["Store"],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"publicKey":{"type":"string"},"botName":{"type":"string"},"active":{"type":"boolean"},"widgetUrl":{"type":"string"},"ordersEnabled":{"type":"boolean"},"panelUrl":{"type":"string"},"products":{"type":"integer"},"inStock":{"type":"integer"},"lastSyncAt":{"type":["string","null"]}},"required":["publicKey","botName","active","widgetUrl","ordersEnabled","panelUrl","products","inStock","lastSyncAt"]}}}},"401":{"description":"The key is missing, wrong, revoked or expired.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable error code; branch on this.","examples":["UNAUTHENTICATED"]},"message":{"type":"string","description":"A message for people, in Persian.","examples":["کلید API معتبر نیست."]}},"required":["code","message"]}}}},"429":{"description":"Too many requests. Wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable error code; branch on this.","examples":["RATE_LIMITED"]},"message":{"type":"string","description":"A message for people, in Persian.","examples":["درخواست‌ها زیاد شد؛ کمی بعد دوباره تلاش کن."]}},"required":["code","message"]}}}}},"security":[{"store":[]}]}},"/store/connect":{"post":{"operationId":"connect-store","description":"Tells Manova where the shop is (`siteUrl`) and where to send order lookups (`apiUrl`, on the same domain; Manova calls `{apiUrl}/order`). The shop's domain is added to the assistant's allowed domains. Connecting a different shop with the same key deletes the previous shop's products.\n\nGuide: https://docs.manova.ir/store/product-sync","summary":"Connect the store","tags":["Store"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"siteUrl":{"type":"string","format":"uri","maxLength":255},"apiUrl":{"type":"string","format":"uri","maxLength":500},"currency":{"type":["string","null"],"maxLength":12},"pluginVersion":{"type":["string","null"],"maxLength":20},"wcVersion":{"type":["string","null"],"maxLength":20},"wpVersion":{"type":["string","null"],"maxLength":20}},"required":["siteUrl","apiUrl"]}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"publicKey":{"type":"string"},"botName":{"type":"string"},"active":{"type":"boolean"},"widgetUrl":{"type":"string"},"ordersEnabled":{"type":"boolean"},"panelUrl":{"type":"string"},"products":{"type":"integer"},"inStock":{"type":"integer"},"lastSyncAt":{"type":["string","null"]}},"required":["publicKey","botName","active","widgetUrl","ordersEnabled","panelUrl","products","inStock","lastSyncAt"]}}}},"401":{"description":"The key is missing, wrong, revoked or expired.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable error code; branch on this.","examples":["UNAUTHENTICATED"]},"message":{"type":"string","description":"A message for people, in Persian.","examples":["کلید API معتبر نیست."]}},"required":["code","message"]}}}},"422":{"$ref":"#/components/responses/ValidationException"},"429":{"description":"Too many requests. Wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable error code; branch on this.","examples":["RATE_LIMITED"]},"message":{"type":"string","description":"A message for people, in Persian.","examples":["درخواست‌ها زیاد شد؛ کمی بعد دوباره تلاش کن."]}},"required":["code","message"]}}}}},"security":[{"store":[]}]}},"/store/sync":{"post":{"operationId":"sync-store","description":"`start` begins a full sync under your `syncId`; send the products with the same `syncId`, then `finish`, which removes every product the sync did not send. A newer `start` replaces the running sync; calls with the older `syncId` then get `409`.","summary":"Start or finish a full sync","tags":["Store"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"syncId":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,40}$"},"phase":{"type":"string","enum":["start","finish"]}},"required":["syncId","phase"]}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"ok":{"type":"boolean"},"removed":{"type":"integer"},"products":{"type":"integer"},"inStock":{"type":"integer"}},"required":["ok","removed","products","inStock"]},{"type":"object","properties":{"ok":{"type":"boolean"}},"required":["ok"]}]}}}},"401":{"description":"The key is missing, wrong, revoked or expired.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable error code; branch on this.","examples":["UNAUTHENTICATED"]},"message":{"type":"string","description":"A message for people, in Persian.","examples":["کلید API معتبر نیست."]}},"required":["code","message"]}}}},"409":{"description":"Products were sent before connecting, or a newer full sync has started.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable error code; branch on this.","examples":["CONFLICT"]},"message":{"type":"string","description":"A message for people, in Persian.","examples":["همگام‌سازی تازه‌تری در جریان است."]}},"required":["code","message"]}}}},"422":{"$ref":"#/components/responses/ValidationException"},"429":{"description":"Too many requests. Wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable error code; branch on this.","examples":["RATE_LIMITED"]},"message":{"type":"string","description":"A message for people, in Persian.","examples":["درخواست‌ها زیاد شد؛ کمی بعد دوباره تلاش کن."]}},"required":["code","message"]}}}}},"security":[{"store":[]}]}},"/store/products":{"post":{"operationId":"send-products","description":"Up to 100 products per call, plus up to 500 ids in `deleted`. With `syncId` they are part of a full sync; without it they are an incremental update. Each product replaces the stored one, so send every field you have. `id`, `name` and `url` (on the shop's domain) are required for a product to be stored; `\"visible\": false` removes it.\n\nField guide: https://docs.manova.ir/store/product-sync#product-fields","summary":"Send products","tags":["Store"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"syncId":{"type":["string","null"],"pattern":"^[A-Za-z0-9_-]{8,40}$"},"products":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Your product id, unique in the store.","examples":[1042],"minimum":1},"name":{"type":["string","null"],"description":"Product name. HTML is stripped.","examples":["کفش رانینگ مردانه مدل آریا"],"maxLength":400},"url":{"type":["string","null"],"description":"Product page, on the shop's own domain.","examples":["https://shop.example.com/product/aria-running"],"maxLength":600},"summary":{"type":["string","null"],"description":"Description. HTML is stripped and the text is cut to 600 characters.","maxLength":20000},"categories":{"type":["array","null"],"description":"Category names; the first 8 are kept.","examples":[["کفش","ورزشی"]],"items":{"type":"string"},"maxItems":30},"tags":{"type":["array","null"],"description":"Extra search words; the first 12 are kept.","examples":[["رانینگ"]],"items":{"type":"string"},"maxItems":50},"image":{"type":"string","format":"uri","description":"Main image, an absolute http(s) URL.","examples":["https://shop.example.com/media/aria.jpg"]},"sku":{"type":"string","description":"Stock code; an exact match ranks the product first.","examples":["ARIA-42"]},"type":{"type":"string","description":"`variable` when there are sizes or models to pick.","enum":["simple","variable"],"default":"simple"},"price":{"type":"number","description":"Numeric price, for comparison.","examples":[2450000]},"price_text":{"type":"string","description":"The price as customers read it, with currency.","examples":["۲٬۴۵۰٬۰۰۰ تومان"]},"regular_price_text":{"type":"string","description":"The price before a discount, only when on sale.","examples":["۲٬۹۰۰٬۰۰۰ تومان"]},"in_stock":{"type":"boolean","description":"Whether it can be bought now.","default":true},"stock_quantity":{"type":"integer","description":"Units left; at 10 or fewer the assistant mentions it.","examples":[7]},"cart_url":{"type":"string","format":"uri","description":"Adds the product to the cart, on the shop's domain. The card's buy button when in stock."},"total_sales":{"type":"integer","description":"Units sold; ranks best sellers.","examples":[318]},"visible":{"type":"boolean","description":"`false` removes the product.","default":true}},"required":["id","name","url"]},"maxItems":100},"deleted":{"type":"array","items":{"type":"integer","minimum":1},"maxItems":500}},"required":["products"]}}}},"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"saved":{"type":"integer"},"removed":{"type":"integer","description":"Products removed through `deleted`."}},"required":["ok","saved","removed"]}}}},"401":{"description":"The key is missing, wrong, revoked or expired.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable error code; branch on this.","examples":["UNAUTHENTICATED"]},"message":{"type":"string","description":"A message for people, in Persian.","examples":["کلید API معتبر نیست."]}},"required":["code","message"]}}}},"409":{"description":"Products were sent before connecting, or a newer full sync has started.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable error code; branch on this.","examples":["CONFLICT"]},"message":{"type":"string","description":"A message for people, in Persian.","examples":["همگام‌سازی تازه‌تری در جریان است."]}},"required":["code","message"]}}}},"422":{"$ref":"#/components/responses/ValidationException"},"429":{"description":"Too many requests. Wait for `Retry-After` seconds.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable error code; branch on this.","examples":["RATE_LIMITED"]},"message":{"type":"string","description":"A message for people, in Persian.","examples":["درخواست‌ها زیاد شد؛ کمی بعد دوباره تلاش کن."]}},"required":["code","message"]}}}}},"security":[{"store":[]}]}}},"components":{"securitySchemes":{"token":{"type":"http","description":"An API token from the panel's «دسترسی API» page: `manova_` and 64 hex characters, valid for 90 days.","scheme":"bearer","bearerFormat":"manova_..."},"store":{"type":"http","description":"The store connection key from the assistant's «فروشگاه» section: `mnv_<store>_<secret>`.","scheme":"bearer","bearerFormat":"mnv_..."}},"responses":{"ValidationException":{"description":"A field is invalid. `details` lists the messages per field.","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"string","description":"Stable error code; branch on this.","examples":["VALIDATION_ERROR"]},"message":{"type":"string","description":"A message for people, in Persian.","examples":["ورودی معتبر نیست."]},"details":{"type":"object","description":"Messages per field.","additionalProperties":{"type":"array","items":{"type":"string"}}}},"required":["code","message"]}}}}}}}