{"openapi":"3.1.0","info":{"title":"Haravan (BYOK) API","version":"0.1.0","description":"Haravan (BYOK) lets an AI assistant read your own Haravan data through the Haravan API with a key you supply (Haravan private app token). Read-only: 11 tools (get_shop, list_orders, count_orders, get_order, list_products, count_products, get_product, list_custom_collections, list_smart_collections, list_locations, list_provinces). The BYOK key travels with each request, is used for that one call...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-haravan.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-haravan/docs"},"termsOfService":"https://connectorbay.com/byok-haravan/terms"},"servers":[{"url":"https://byok-haravan.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-haravan/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_shop":{"post":{"operationId":"get_shop","summary":"Show the store the token belongs to: name, domains, plan, currency, country, timezone and owner name. Use for \"Which Har","description":"Show the store the token belongs to: name, domains, plan, currency, country, timezone and owner name. Use for \"Which Haravan store is this token for and what plan is it on\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_shopArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_orders":{"post":{"operationId":"list_orders","summary":"List orders (newest first by default) with status, payment and fulfillment state and totals; no customer contact details","description":"List orders (newest first by default) with status, payment and fulfillment state and totals; no customer contact details are returned. Needs the read orders scope. Use for \"Which Haravan orders are unshipped and paid\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["open","closed","cancelled","any"],"type":"string"},{"type":"null"}],"default":null,"description":"Order state: open, closed, cancelled or any (any also includes archived orders).","title":"Status"},"financial_status":{"anyOf":[{"enum":["pending","paid","partially_paid","refunded","voided","partially_refunded"],"type":"string"},{"type":"null"}],"default":null,"description":"Payment status filter: pending, paid, partially_paid, refunded, voided or partially_refunded.","title":"Financial Status"},"fulfillment_status":{"anyOf":[{"enum":["unshipped","shipped","partial"],"type":"string"},{"type":"null"}],"default":null,"description":"Fulfillment filter: unshipped, shipped or partial.","title":"Fulfillment Status"},"created_at_min":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders created after this ISO 8601 UTC time, for example 2026-01-01T00:00:00Z.","title":"Created At Min"},"created_at_max":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders created before this ISO 8601 UTC time.","title":"Created At Max"},"order":{"anyOf":[{"enum":["created_at asc","created_at desc","updated_at asc","updated_at desc"],"type":"string"},{"type":"null"}],"default":null,"description":"Sort: created_at asc, created_at desc, updated_at asc or updated_at desc.","title":"Order"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return (1 to 50).","title":"Limit"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"since_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Return only records with an id greater than this one (for paging by id).","title":"Since Id"}},"title":"list_ordersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/count_orders":{"post":{"operationId":"count_orders","summary":"Count orders matching the same filters as the order list. Use for \"How many Haravan orders were created this month\".","description":"Count orders matching the same filters as the order list. Use for \"How many Haravan orders were created this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"enum":["open","closed","cancelled","any"],"type":"string"},{"type":"null"}],"default":null,"description":"Order state: open, closed, cancelled or any.","title":"Status"},"financial_status":{"anyOf":[{"enum":["pending","paid","partially_paid","refunded","voided","partially_refunded"],"type":"string"},{"type":"null"}],"default":null,"description":"Payment status filter.","title":"Financial Status"},"fulfillment_status":{"anyOf":[{"enum":["unshipped","shipped","partial"],"type":"string"},{"type":"null"}],"default":null,"description":"Fulfillment filter: unshipped, shipped or partial.","title":"Fulfillment Status"},"created_at_min":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders created after this ISO 8601 UTC time.","title":"Created At Min"},"created_at_max":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only orders created before this ISO 8601 UTC time.","title":"Created At Max"}},"title":"count_ordersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_order":{"post":{"operationId":"get_order","summary":"Get one order by its numeric API id with status, totals and payment gateway (not the buyer's contact details). Use for \"","description":"Get one order by its numeric API id with status, totals and payment gateway (not the buyer's contact details). Use for \"Show Haravan order 1032300001\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"order_id":{"description":"Numeric API id of the order (the id field, not the order number).","title":"Order Id","type":"integer"}},"required":["order_id"],"title":"get_orderArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_products":{"post":{"operationId":"list_products","summary":"List products with vendor, type, tags, publish dates and variants (SKU, price, stock), filterable by vendor, type, colle","description":"List products with vendor, type, tags, publish dates and variants (SKU, price, stock), filterable by vendor, type, collection or SKU. Use for \"Which Haravan products come from vendor Acme\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"vendor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only products from this vendor.","title":"Vendor"},"product_type":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only products of this type.","title":"Product Type"},"collection_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only products in this collection id.","title":"Collection Id"},"sku":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only products having a variant with this SKU.","title":"Sku"},"handle":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only the product with this URL handle.","title":"Handle"},"updated_at_min":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only products updated after this ISO 8601 UTC time.","title":"Updated At Min"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return (1 to 50).","title":"Limit"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"since_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Return only records with an id greater than this one (for paging by id).","title":"Since Id"}},"title":"list_productsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/count_products":{"post":{"operationId":"count_products","summary":"Count the products in the store. Use for \"How many products does my Haravan store have\".","description":"Count the products in the store. Use for \"How many products does my Haravan store have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"count_productsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_product":{"post":{"operationId":"get_product","summary":"Get one product by numeric id with its variants (SKU, price, stock level). Use for \"Show Haravan product 1028655526 with","description":"Get one product by numeric id with its variants (SKU, price, stock level). Use for \"Show Haravan product 1028655526 with its variants\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"product_id":{"description":"Numeric id of the product.","title":"Product Id","type":"integer"}},"required":["product_id"],"title":"get_productArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_custom_collections":{"post":{"operationId":"list_custom_collections","summary":"List manually curated product collections with title, handle and publish state. Use for \"What custom collections does my","description":"List manually curated product collections with title, handle and publish state. Use for \"What custom collections does my Haravan store have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"title":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only collections with this title.","title":"Title"},"product_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only collections containing this product id.","title":"Product Id"},"published_status":{"anyOf":[{"enum":["published","unpublished","any"],"type":"string"},{"type":"null"}],"default":"any","description":"published, unpublished or any.","title":"Published Status"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return (1 to 50).","title":"Limit"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_custom_collectionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_smart_collections":{"post":{"operationId":"list_smart_collections","summary":"List rule-based (automated) product collections with title, handle and publish state. Use for \"What smart collections do","description":"List rule-based (automated) product collections with title, handle and publish state. Use for \"What smart collections does my Haravan store have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"title":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only collections with this title.","title":"Title"},"product_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"Only collections containing this product id.","title":"Product Id"},"published_status":{"anyOf":[{"enum":["published","unpublished","any"],"type":"string"},{"type":"null"}],"default":"any","description":"published, unpublished or any.","title":"Published Status"},"limit":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return (1 to 50).","title":"Limit"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_smart_collectionsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_locations":{"post":{"operationId":"list_locations","summary":"List the store's stock and sales locations with address and whether each is the primary location. Use for \"Where are my ","description":"List the store's stock and sales locations with address and whether each is the primary location. Use for \"Where are my Haravan stock locations\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_locationsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_provinces":{"post":{"operationId":"list_provinces","summary":"List the provinces of a country as Haravan codes them (use 704 for Vietnam), for matching addresses on orders. Use for \"","description":"List the provinces of a country as Haravan codes them (use 704 for Vietnam), for matching addresses on orders. Use for \"List the Vietnamese provinces known to Haravan\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"country_id":{"description":"Numeric Haravan country id; 704 is Vietnam.","title":"Country Id","type":"integer"}},"required":["country_id"],"title":"list_provincesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}