{"openapi":"3.1.0","info":{"title":"Doofinder (BYOK) API","version":"0.1.0","description":"Doofinder (BYOK) lets an AI assistant read your own Doofinder data through the Doofinder API with a key you supply (Doofinder API key (account owner's key)). Read-only: 11 tools (list_search_engines, get_search_engine, list_indices, get_index, count_items, get_item, scroll_items, get_search_stats, get_top_searches, get_click_stats, get_session_stats). The BYOK key travels with each request, is...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-doofinder.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-doofinder/docs"},"termsOfService":"https://connectorbay.com/byok-doofinder/terms"},"servers":[{"url":"https://byok-doofinder.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-doofinder/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/list_search_engines":{"post":{"operationId":"list_search_engines","summary":"List the account's search engines with hashid, name, status, language, currency, platform and site URL. Use for \"Which D","description":"List the account's search engines with hashid, name, status, language, currency, platform and site URL. Use for \"Which Doofinder search engines do I have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search_zone":{"description":"Your Doofinder search zone: eu1, us1 or ap1 (the prefix of your API key).","enum":["eu1","us1","ap1"],"title":"Search Zone","type":"string"}},"required":["search_zone"],"title":"list_search_enginesArguments","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_search_engine":{"post":{"operationId":"get_search_engine","summary":"Get one search engine by hashid with status, language, currency, platform and site URL. Use for \"Show details of Doofind","description":"Get one search engine by hashid with status, language, currency, platform and site URL. Use for \"Show details of Doofinder search engine d8fdeab7fce96a19d3fc7b0ca7a1e98b\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search_zone":{"description":"Your Doofinder search zone: eu1, us1 or ap1 (the prefix of your API key).","enum":["eu1","us1","ap1"],"title":"Search Zone","type":"string"},"hashid":{"description":"Search engine id (hashid) from list_search_engines.","maxLength":200,"title":"Hashid","type":"string"}},"required":["search_zone","hashid"],"title":"get_search_engineArguments","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_indices":{"post":{"operationId":"list_indices","summary":"List the indices of a search engine with name, preset (generic, product, page, category) and options. Use for \"What indi","description":"List the indices of a search engine with name, preset (generic, product, page, category) and options. Use for \"What indices does this Doofinder search engine have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search_zone":{"description":"Your Doofinder search zone: eu1, us1 or ap1 (the prefix of your API key).","enum":["eu1","us1","ap1"],"title":"Search Zone","type":"string"},"hashid":{"description":"Search engine id (hashid) from list_search_engines.","maxLength":200,"title":"Hashid","type":"string"}},"required":["search_zone","hashid"],"title":"list_indicesArguments","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_index":{"post":{"operationId":"get_index","summary":"Get one index of a search engine: name, preset, options and data sources. Use for \"Show the product index of my Doofinde","description":"Get one index of a search engine: name, preset, options and data sources. Use for \"Show the product index of my Doofinder search engine\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search_zone":{"description":"Your Doofinder search zone: eu1, us1 or ap1 (the prefix of your API key).","enum":["eu1","us1","ap1"],"title":"Search Zone","type":"string"},"hashid":{"description":"Search engine id (hashid) from list_search_engines.","maxLength":200,"title":"Hashid","type":"string"},"index_name":{"description":"Index name, for example product.","maxLength":200,"title":"Index Name","type":"string"}},"required":["search_zone","hashid","index_name"],"title":"get_indexArguments","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_items":{"post":{"operationId":"count_items","summary":"Count the items in an index. Use for \"How many products are indexed in my Doofinder product index\".","description":"Count the items in an index. Use for \"How many products are indexed in my Doofinder product index\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search_zone":{"description":"Your Doofinder search zone: eu1, us1 or ap1 (the prefix of your API key).","enum":["eu1","us1","ap1"],"title":"Search Zone","type":"string"},"hashid":{"description":"Search engine id (hashid) from list_search_engines.","maxLength":200,"title":"Hashid","type":"string"},"index_name":{"description":"Index name, for example product.","maxLength":200,"title":"Index Name","type":"string"}},"required":["search_zone","hashid","index_name"],"title":"count_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/get_item":{"post":{"operationId":"get_item","summary":"Get one indexed item by id: title, link, image, best price and grouping. Use for \"Show indexed Doofinder item SKU-1001\".","description":"Get one indexed item by id: title, link, image, best price and grouping. Use for \"Show indexed Doofinder item SKU-1001\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search_zone":{"description":"Your Doofinder search zone: eu1, us1 or ap1 (the prefix of your API key).","enum":["eu1","us1","ap1"],"title":"Search Zone","type":"string"},"hashid":{"description":"Search engine id (hashid) from list_search_engines.","maxLength":200,"title":"Hashid","type":"string"},"index_name":{"description":"Index name, for example product.","maxLength":200,"title":"Index Name","type":"string"},"item_id":{"description":"Item id inside the index.","maxLength":200,"title":"Item Id","type":"string"}},"required":["search_zone","hashid","index_name","item_id"],"title":"get_itemArguments","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/scroll_items":{"post":{"operationId":"scroll_items","summary":"Page through the items of an index, up to 100 per page; pass the returned scroll_id to get the next page. Use for \"List ","description":"Page through the items of an index, up to 100 per page; pass the returned scroll_id to get the next page. Use for \"List the first 20 items in my Doofinder product index\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search_zone":{"description":"Your Doofinder search zone: eu1, us1 or ap1 (the prefix of your API key).","enum":["eu1","us1","ap1"],"title":"Search Zone","type":"string"},"hashid":{"description":"Search engine id (hashid) from list_search_engines.","maxLength":200,"title":"Hashid","type":"string"},"index_name":{"description":"Index name, for example product.","maxLength":200,"title":"Index Name","type":"string"},"rpp":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Items per page (1 to 100).","title":"Rpp"},"scroll_id":{"anyOf":[{"maxLength":300,"type":"string"},{"type":"null"}],"default":null,"description":"scroll_id from the previous page to continue the scroll.","title":"Scroll Id"},"group_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only items of this variant group id.","title":"Group Id"}},"required":["search_zone","hashid","index_name"],"title":"scroll_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/get_search_stats":{"post":{"operationId":"get_search_stats","summary":"Count searches per day in a period, for one search engine or all of them. Use for \"How many searches did my Doofinder sh","description":"Count searches per day in a period, for one search engine or all of them. Use for \"How many searches did my Doofinder shop get last month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search_zone":{"description":"Your Doofinder search zone: eu1, us1 or ap1 (the prefix of your API key).","enum":["eu1","us1","ap1"],"title":"Search Zone","type":"string"},"from_date":{"description":"Start of the period, as YYYYMMDD or a Unix timestamp.","maxLength":12,"title":"From Date","type":"string"},"to_date":{"description":"End of the period, as YYYYMMDD or a Unix timestamp.","maxLength":12,"title":"To Date","type":"string"},"search_engine":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Limit to one search engine (hashid); all engines of the account when omitted.","title":"Search Engine"},"device":{"anyOf":[{"enum":["desktop","mobile"],"type":"string"},{"type":"null"}],"default":null,"description":"Only desktop or mobile traffic.","title":"Device"},"tz":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":"Etc/UTC","description":"Time zone name for the dates, for example Europe/Madrid.","title":"Tz"}},"required":["search_zone","from_date","to_date"],"title":"get_search_statsArguments","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_top_searches":{"post":{"operationId":"get_top_searches","summary":"List the most common search terms in a period with counts; can show only searches that returned no results. Use for \"Wha","description":"List the most common search terms in a period with counts; can show only searches that returned no results. Use for \"What are the top searches with no results in Doofinder this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search_zone":{"description":"Your Doofinder search zone: eu1, us1 or ap1 (the prefix of your API key).","enum":["eu1","us1","ap1"],"title":"Search Zone","type":"string"},"from_date":{"description":"Start of the period, as YYYYMMDD or a Unix timestamp.","maxLength":12,"title":"From Date","type":"string"},"to_date":{"description":"End of the period, as YYYYMMDD or a Unix timestamp.","maxLength":12,"title":"To Date","type":"string"},"search_engine":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Limit to one search engine (hashid); all engines of the account when omitted.","title":"Search Engine"},"device":{"anyOf":[{"enum":["desktop","mobile"],"type":"string"},{"type":"null"}],"default":null,"description":"Only desktop or mobile traffic.","title":"Device"},"tz":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":"Etc/UTC","description":"Time zone name for the dates, for example Europe/Madrid.","title":"Tz"},"no_results":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True to show only searches that returned zero results.","title":"No Results"}},"required":["search_zone","from_date","to_date"],"title":"get_top_searchesArguments","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_click_stats":{"post":{"operationId":"get_click_stats","summary":"Count clicks on search results per day in a period. Use for \"How many clicks did Doofinder results get last week\".","description":"Count clicks on search results per day in a period. Use for \"How many clicks did Doofinder results get last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search_zone":{"description":"Your Doofinder search zone: eu1, us1 or ap1 (the prefix of your API key).","enum":["eu1","us1","ap1"],"title":"Search Zone","type":"string"},"from_date":{"description":"Start of the period, as YYYYMMDD or a Unix timestamp.","maxLength":12,"title":"From Date","type":"string"},"to_date":{"description":"End of the period, as YYYYMMDD or a Unix timestamp.","maxLength":12,"title":"To Date","type":"string"},"search_engine":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Limit to one search engine (hashid); all engines of the account when omitted.","title":"Search Engine"},"tz":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":"Etc/UTC","description":"Time zone name for the dates, for example Europe/Madrid.","title":"Tz"}},"required":["search_zone","from_date","to_date"],"title":"get_click_statsArguments","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_session_stats":{"post":{"operationId":"get_session_stats","summary":"Count unique search sessions per day in a period. Use for \"How many search sessions did my Doofinder shop have last mont","description":"Count unique search sessions per day in a period. Use for \"How many search sessions did my Doofinder shop have last month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search_zone":{"description":"Your Doofinder search zone: eu1, us1 or ap1 (the prefix of your API key).","enum":["eu1","us1","ap1"],"title":"Search Zone","type":"string"},"from_date":{"description":"Start of the period, as YYYYMMDD or a Unix timestamp.","maxLength":12,"title":"From Date","type":"string"},"to_date":{"description":"End of the period, as YYYYMMDD or a Unix timestamp.","maxLength":12,"title":"To Date","type":"string"},"search_engine":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Limit to one search engine (hashid); all engines of the account when omitted.","title":"Search Engine"},"tz":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":"Etc/UTC","description":"Time zone name for the dates, for example Europe/Madrid.","title":"Tz"}},"required":["search_zone","from_date","to_date"],"title":"get_session_statsArguments","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}}}}