{"openapi":"3.1.0","info":{"title":"SurveyHero (BYOK) API","version":"0.1.0","description":"SurveyHero (BYOK) lets an AI assistant read your own SurveyHero data through the SurveyHero API with a key you supply (SurveyHero API key username). Read-only: 8 tools (list_surveys, get_survey, list_survey_questions, list_collectors, get_collector, list_languages, list_responses, get_survey_report). The BYOK key travels with each request, is used for that one call only and is never stored,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-surveyhero.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-surveyhero/docs"},"termsOfService":"https://connectorbay.com/byok-surveyhero/terms"},"servers":[{"url":"https://byok-surveyhero.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-surveyhero/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_surveys":{"post":{"operationId":"list_surveys","summary":"List all surveys you can access (yours and shared ones) with title, creation date, and counts of questions, collectors a","description":"List all surveys you can access (yours and shared ones) with title, creation date, and counts of questions, collectors and responses. Use for \"Which surveys do I have in SurveyHero and how many responses did each get\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_surveysArguments","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_survey":{"post":{"operationId":"get_survey","summary":"Get one survey with title, creation date, number of elements, questions, collectors, responses and webhooks, and whether","description":"Get one survey with title, creation date, number of elements, questions, collectors, responses and webhooks, and whether it is anonymous. Use for \"Show SurveyHero survey 53635\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"survey_id":{"description":"Survey id (integer) from list_surveys.","title":"Survey Id","type":"integer"}},"required":["survey_id"],"title":"get_surveyArguments","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_questions":{"post":{"operationId":"list_survey_questions","summary":"List the questions of a survey in order with id, question text, description and question type (rating scale, choice list","description":"List the questions of a survey in order with id, question text, description and question type (rating scale, choice list, input and so on). Use for \"What questions are in SurveyHero survey 53635\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"survey_id":{"description":"Survey id (integer) from list_surveys.","title":"Survey Id","type":"integer"},"lang":{"anyOf":[{"maxLength":10,"type":"string"},{"type":"null"}],"default":null,"description":"Language code for a multilingual survey, for example de (default: the survey's main language). See list_languages.","title":"Lang"}},"required":["survey_id"],"title":"list_survey_questionsArguments","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_collectors":{"post":{"operationId":"list_collectors","summary":"List the collectors of a survey (survey link, email invite, iframe, popup and so on) with name, creation date, status an","description":"List the collectors of a survey (survey link, email invite, iframe, popup and so on) with name, creation date, status and type. Use for \"How is SurveyHero survey 53635 being collected\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"survey_id":{"description":"Survey id (integer) from list_surveys.","title":"Survey Id","type":"integer"}},"required":["survey_id"],"title":"list_collectorsArguments","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_collector":{"post":{"operationId":"get_collector","summary":"Get one collector with name, status, type, response count and (for a survey link) the public URL. Use for \"Show SurveyHe","description":"Get one collector with name, status, type, response count and (for a survey link) the public URL. Use for \"Show SurveyHero collector 99583 of survey 53635\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"survey_id":{"description":"Survey id (integer) from list_surveys.","title":"Survey Id","type":"integer"},"collector_id":{"description":"Collector id (integer) from list_collectors.","title":"Collector Id","type":"integer"}},"required":["survey_id","collector_id"],"title":"get_collectorArguments","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_languages":{"post":{"operationId":"list_languages","summary":"List the languages of a survey with code and whether each is the default and active. Use for \"Which languages does Surve","description":"List the languages of a survey with code and whether each is the default and active. Use for \"Which languages does SurveyHero survey 53635 support\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"survey_id":{"description":"Survey id (integer) from list_surveys.","title":"Survey Id","type":"integer"}},"required":["survey_id"],"title":"list_languagesArguments","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_responses":{"post":{"operationId":"list_responses","summary":"List the responses of a survey, newest first, with collector, start and last update times, completion status, language a","description":"List the responses of a survey, newest first, with collector, start and last update times, completion status, language and device. Emails, IP addresses and answers are not returned. Use for \"How many responses did SurveyHero survey 53635 get this week and how many are complete\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"survey_id":{"description":"Survey id (integer) from list_surveys.","title":"Survey Id","type":"integer"},"status":{"anyOf":[{"enum":["completed","incomplete"],"type":"string"},{"type":"null"}],"default":null,"description":"Only completed or incomplete responses.","title":"Status"},"started_on_from":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only responses started at or after this ISO 8601 time, for example 2026-10-01T00:00:00+00:00.","title":"Started On From"},"started_on_to":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only responses started at or before this ISO 8601 time.","title":"Started On To"},"last_updated_on_from":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only responses last updated at or after this ISO 8601 time.","title":"Last Updated On From"},"last_updated_on_to":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only responses last updated at or before this ISO 8601 time.","title":"Last Updated On To"},"collector_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only responses from this collector (integer).","title":"Collector Id"}},"required":["survey_id"],"title":"list_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/get_survey_report":{"post":{"operationId":"get_survey_report","summary":"Get the tabulated results of a survey: for each question the number of responses and the counts and percentages per choi","description":"Get the tabulated results of a survey: for each question the number of responses and the counts and percentages per choice. Free-text answers are not returned. Use for \"What were the results of SurveyHero survey 53635\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"survey_id":{"description":"Survey id (integer) from list_surveys.","title":"Survey Id","type":"integer"}},"required":["survey_id"],"title":"get_survey_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}}}}