{"openapi":"3.1.0","info":{"title":"Wafeq (BYOK) API","version":"0.1.0","description":"Wafeq (BYOK) lets an AI assistant read your own Wafeq data through the Wafeq API with a key you supply (Wafeq API key). Read-only: 9 tools (get_organization, list_contacts, list_invoices, list_bills, list_payments, list_quotes, list_items, list_accounts, list_tax_rates). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is only ever...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-wafeq.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-wafeq/docs"},"termsOfService":"https://connectorbay.com/byok-wafeq/terms"},"servers":[{"url":"https://byok-wafeq.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-wafeq/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_organization":{"post":{"operationId":"get_organization","summary":"Show the Wafeq organization the key belongs to: names (English and Arabic), base currency, branches, warehouses and user","description":"Show the Wafeq organization the key belongs to: names (English and Arabic), base currency, branches, warehouses and user emails. Use for \"Which Wafeq organization is this key for and what is its base currency\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_organizationArguments","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_contacts":{"post":{"operationId":"list_contacts","summary":"List Wafeq contacts (customers and suppliers) with name, email, phone, address and relationship. Paged. Use for \"Find th","description":"List Wafeq contacts (customers and suppliers) with name, email, phone, address and relationship. Paged. Use for \"Find the Wafeq contact called Al Noor Trading\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"keyword":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search text matched against contact fields.","title":"Keyword"},"external_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records carrying this external identifier set by an integration.","title":"External Id"},"modified_ts_after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records modified after this UTC timestamp, for example 2026-01-01T00:00:00Z.","title":"Modified Ts After"},"modified_ts_before":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records modified before this UTC timestamp.","title":"Modified Ts Before"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records per page.","title":"Page Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number within the result set, starting at 1.","title":"Page"}},"title":"list_contactsArguments","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_invoices":{"post":{"operationId":"list_invoices","summary":"List sales invoices with number, contact, dates, amount, balance, tax and status. Filter by contact, status or date. Use","description":"List sales invoices with number, contact, dates, amount, balance, tax and status. Filter by contact, status or date. Use for \"Which Wafeq invoices still have a balance\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"contact":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records of this contact id (from list_contacts).","title":"Contact"},"status":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Invoice status, using the value names the API returns in the status field.","title":"Status"},"invoice_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only invoices dated exactly this day, YYYY-MM-DD.","title":"Invoice Date"},"modified_ts_after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records modified after this UTC timestamp, for example 2026-01-01T00:00:00Z.","title":"Modified Ts After"},"modified_ts_before":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records modified before this UTC timestamp.","title":"Modified Ts Before"},"external_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records carrying this external identifier set by an integration.","title":"External Id"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records per page.","title":"Page Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number within the result set, starting at 1.","title":"Page"}},"title":"list_invoicesArguments","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_bills":{"post":{"operationId":"list_bills","summary":"List supplier bills with number, contact, dates, amount, balance, tax and status. Use for \"Which Wafeq supplier bills ar","description":"List supplier bills with number, contact, dates, amount, balance, tax and status. Use for \"Which Wafeq supplier bills are due this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"contact":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records of this contact id (from list_contacts).","title":"Contact"},"status":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Bill status as the API names it.","title":"Status"},"bill_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only bills dated exactly this day, YYYY-MM-DD.","title":"Bill Date"},"bill_due_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only bills due exactly this day, YYYY-MM-DD.","title":"Bill Due Date"},"modified_ts_after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records modified after this UTC timestamp, for example 2026-01-01T00:00:00Z.","title":"Modified Ts After"},"modified_ts_before":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records modified before this UTC timestamp.","title":"Modified Ts Before"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records per page.","title":"Page Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number within the result set, starting at 1.","title":"Page"}},"title":"list_billsArguments","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_payments":{"post":{"operationId":"list_payments","summary":"List recorded payments with date, amount, contact, payment type, fees and the account they went through. Use for \"What p","description":"List recorded payments with date, amount, contact, payment type, fees and the account they went through. Use for \"What payments did Wafeq record on 2026-03-01\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"contact":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records of this contact id (from list_contacts).","title":"Contact"},"date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only payments made on this day, YYYY-MM-DD.","title":"Date"},"reference":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only payments with this reference text.","title":"Reference"},"modified_ts_after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records modified after this UTC timestamp, for example 2026-01-01T00:00:00Z.","title":"Modified Ts After"},"modified_ts_before":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records modified before this UTC timestamp.","title":"Modified Ts Before"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records per page.","title":"Page Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number within the result set, starting at 1.","title":"Page"}},"title":"list_paymentsArguments","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_quotes":{"post":{"operationId":"list_quotes","summary":"List sales quotes with number, contact, date, amount, tax and status. Use for \"What open quotes do I have in Wafeq\".","description":"List sales quotes with number, contact, date, amount, tax and status. Use for \"What open quotes do I have in Wafeq\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"contact":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records of this contact id (from list_contacts).","title":"Contact"},"status":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Quote status as the API names it.","title":"Status"},"quote_date":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only quotes dated exactly this day, YYYY-MM-DD.","title":"Quote Date"},"modified_ts_after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records modified after this UTC timestamp, for example 2026-01-01T00:00:00Z.","title":"Modified Ts After"},"modified_ts_before":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records modified before this UTC timestamp.","title":"Modified Ts Before"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records per page.","title":"Page Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number within the result set, starting at 1.","title":"Page"}},"title":"list_quotesArguments","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_items":{"post":{"operationId":"list_items","summary":"List products and services with SKU, price, cost, stock on hand and whether inventory is tracked. Use for \"Which Wafeq i","description":"List products and services with SKU, price, cost, stock on hand and whether inventory is tracked. Use for \"Which Wafeq items are tracked in inventory and how many are on hand\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"modified_ts_after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records modified after this UTC timestamp, for example 2026-01-01T00:00:00Z.","title":"Modified Ts After"},"modified_ts_before":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records modified before this UTC timestamp.","title":"Modified Ts Before"},"external_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only records carrying this external identifier set by an integration.","title":"External Id"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records per page.","title":"Page Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number within the result set, starting at 1.","title":"Page"}},"title":"list_itemsArguments","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_accounts":{"post":{"operationId":"list_accounts","summary":"List the chart of accounts with code, English and Arabic names, classification and whether posting is allowed. Use for \"","description":"List the chart of accounts with code, English and Arabic names, classification and whether posting is allowed. Use for \"Show my Wafeq revenue accounts\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"classification":{"anyOf":[{"enum":["ASSET","EQUITY","EXPENSE","LIABILITY","REVENUE"],"type":"string"},{"type":"null"}],"default":null,"description":"Account class.","title":"Classification"},"is_system":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for system accounts only, false to hide them.","title":"Is System"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records per page.","title":"Page Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number within the result set, starting at 1.","title":"Page"}},"title":"list_accountsArguments","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_tax_rates":{"post":{"operationId":"list_tax_rates","summary":"List tax rates (VAT and similar) with name, percentage rate and tax type. Use for \"What VAT rates are set up in Wafeq\".","description":"List tax rates (VAT and similar) with name, percentage rate and tax type. Use for \"What VAT rates are set up in Wafeq\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"tax_type":{"anyOf":[{"enum":["OUT_OF_SCOPE","PURCHASES","REVERSE_CHARGE","SALES"],"type":"string"},{"type":"null"}],"default":null,"description":"Tax type.","title":"Tax Type"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":25,"description":"How many records per page.","title":"Page Size"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number within the result set, starting at 1.","title":"Page"}},"title":"list_tax_ratesArguments","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}}}}