{"openapi":"3.1.0","info":{"title":"Refiner (BYOK) API","version":"0.1.0","description":"Refiner (BYOK) lets an AI assistant read your own Refiner data through the Refiner API with a key you supply (Refiner API key). Read-only: 6 tools (get_account_info, list_forms, get_report, get_view_and_response_counts, list_survey_responses, list_segments). 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 sent to...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-refiner.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-refiner/docs"},"termsOfService":"https://connectorbay.com/byok-refiner/terms"},"servers":[{"url":"https://byok-refiner.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-refiner/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_account_info":{"post":{"operationId":"get_account_info","summary":"Show your Refiner plan and usage counters (monthly tracked users, events, page views and survey responses against the pl","description":"Show your Refiner plan and usage counters (monthly tracked users, events, page views and survey responses against the plan limits) and the environments of the account. Use for \"Which Refiner plan am I on and how much of my monthly limits have I used\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_account_infoArguments","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_forms":{"post":{"operationId":"list_forms","summary":"List the surveys (forms) of the Refiner environment the key belongs to, ordered by name. With include_info on, each surv","description":"List the surveys (forms) of the Refiner environment the key belongs to, ordered by name. With include_info on, each survey also shows when it was published, response and view counts, folder and share link. Use for \"Which surveys do I have in Refiner and how many responses has each collected\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"list":{"anyOf":[{"enum":["all","published","drafts","archived","all_with_archived"],"type":"string"},{"type":"null"}],"default":"all","description":"Which surveys: all, published, drafts, archived or all_with_archived.","title":"List"},"include_info":{"anyOf":[{"maximum":1,"minimum":0,"type":"integer"},{"type":"null"}],"default":1,"description":"1 to include publish dates, response and view counts, folder and share link; 0 for only uuid and name.","title":"Include Info"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_length":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many items per page (1 to 1000).","title":"Page Length"}},"title":"list_formsArguments","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_report":{"post":{"operationId":"get_report","summary":"Get an aggregated survey report for a date range (the last seven days by default): the NPS score with detractor, passive","description":"Get an aggregated survey report for a date range (the last seven days by default): the NPS score with detractor, passive and promoter counts, the CSAT score, the average of rating questions, or the distribution of all answer values. Use for \"What was my NPS over the last 30 days in Refiner\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"type":{"description":"Report type: nps, csat, ratings or distribution.","enum":["nps","csat","ratings","distribution"],"title":"Type","type":"string"},"form_uuids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only count one survey: its UUID from list_forms. Leave out for all surveys.","title":"Form Uuids"},"question_identifiers":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only count the question with this identifier (the answer key used in the survey).","title":"Question Identifiers"},"segment_uuids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only count users in this segment: a UUID from list_segments.","title":"Segment Uuids"},"date_range_start":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only data on or after this date (ISO 8601, for example 2026-01-01 or 2026-01-01 00:00:00).","title":"Date Range Start"},"date_range_end":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only data before this date (ISO 8601, for example 2026-03-31).","title":"Date Range End"}},"required":["type"],"title":"get_reportArguments","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_view_and_response_counts":{"post":{"operationId":"get_view_and_response_counts","summary":"Count how many times Refiner surveys were shown and how many responses were received in a date range (the last seven day","description":"Count how many times Refiner surveys were shown and how many responses were received in a date range (the last seven days by default), optionally for one survey. Use for \"How many survey views and responses did Refiner record last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"type":{"anyOf":[{"const":"count","type":"string"},{"type":"null"}],"default":"count","description":"Report type, always count for this tool.","title":"Type"},"form_uuids":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only count one survey: its UUID from list_forms. Leave out for all surveys.","title":"Form Uuids"},"date_range_start":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only data on or after this date (ISO 8601, for example 2026-01-01 or 2026-01-01 00:00:00).","title":"Date Range Start"},"date_range_end":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only data before this date (ISO 8601, for example 2026-03-31).","title":"Date Range End"}},"title":"get_view_and_response_countsArguments","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_survey_responses":{"post":{"operationId":"list_survey_responses","summary":"List survey responses and views, newest first, with the answers given per question identifier. Respondent names and emai","description":"List survey responses and views, newest first, with the answers given per question identifier. Respondent names and email addresses are left out. Use the response filters to narrow by survey, dates or status. Use for \"What answers did people give in my latest Refiner survey\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"form_uuid":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only responses of this survey: a UUID from list_forms.","title":"Form Uuid"},"include":{"anyOf":[{"enum":["completed","partials","all"],"type":"string"},{"type":"null"}],"default":"completed","description":"Which entries: completed (default), partials (partial and completed) or all (also dismissed views).","title":"Include"},"date_range_start":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only data on or after this date (ISO 8601, for example 2026-01-01 or 2026-01-01 00:00:00).","title":"Date Range Start"},"date_range_end":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only data before this date (ISO 8601, for example 2026-03-31).","title":"Date Range End"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_length":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many items per page (1 to 1000).","title":"Page Length"}},"title":"list_survey_responsesArguments","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_segments":{"post":{"operationId":"list_segments","summary":"List the user segments defined in Refiner, ordered by name, with their UUID and whether the membership is manual. Use fo","description":"List the user segments defined in Refiner, ordered by name, with their UUID and whether the membership is manual. Use for \"Which user segments exist in my Refiner account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"page_length":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many items per page (1 to 1000).","title":"Page Length"}},"title":"list_segmentsArguments","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}}}}