{"openapi":"3.1.0","info":{"title":"SmartSurvey (BYOK) API","version":"0.1.0","description":"SmartSurvey (BYOK) lets an AI assistant read your own SmartSurvey data through the SmartSurvey API with a key you supply (SmartSurvey API token (the Basic auth username)). Read-only: 11 tools (list_surveys, get_survey, get_survey_details, list_survey_pages, get_survey_page, list_tracking_links, list_filter_groups, list_survey_exports, list_survey_folders, get_survey_folder, list_themes). The BYOK...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-smartsurvey.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-smartsurvey/docs"},"termsOfService":"https://connectorbay.com/byok-smartsurvey/terms"},"servers":[{"url":"https://byok-smartsurvey.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-smartsurvey/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 the surveys of the account with status, response count, folder and dates; filter by folder (0 for surveys in no fol","description":"List the surveys of the account with status, response count, folder and dates; filter by folder (0 for surveys in no folder). Use for \"Which SmartSurvey surveys are open and how many responses do they have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"SmartSurvey data region of your account: api (UK, the app.smartsurvey.co.uk or .com sign-in), api-eu (app-eu.smartsurvey.com) or api-us (app-us.smartsurvey.com).","enum":["api","api-eu","api-us"],"title":"Region","type":"string"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"1-based page number.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Records per page (1 to 100, default 10).","title":"Page Size"},"folder_id":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Only surveys in this folder id, or 0 for surveys not in any folder (owned surveys only).","title":"Folder Id"}},"required":["region"],"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: title, status, response count, folder, page and question counts, theme and link. Use for \"How many quest","description":"Get one survey: title, status, response count, folder, page and question counts, theme and link. Use for \"How many questions and responses does SmartSurvey survey 123456 have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"SmartSurvey data region of your account: api (UK, the app.smartsurvey.co.uk or .com sign-in), api-eu (app-eu.smartsurvey.com) or api-us (app-us.smartsurvey.com).","enum":["api","api-eu","api-us"],"title":"Region","type":"string"},"survey_id":{"description":"SmartSurvey survey id (the id from list_surveys).","title":"Survey Id","type":"integer"}},"required":["region","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/get_survey_details":{"post":{"operationId":"get_survey_details","summary":"Get a survey with its variables, translations and page list (page questions are summarised; use get_survey_page for thei","description":"Get a survey with its variables, translations and page list (page questions are summarised; use get_survey_page for their text). Use for \"What pages and translations does my SmartSurvey survey have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"SmartSurvey data region of your account: api (UK, the app.smartsurvey.co.uk or .com sign-in), api-eu (app-eu.smartsurvey.com) or api-us (app-us.smartsurvey.com).","enum":["api","api-eu","api-us"],"title":"Region","type":"string"},"survey_id":{"description":"SmartSurvey survey id (the id from list_surveys).","title":"Survey Id","type":"integer"}},"required":["region","survey_id"],"title":"get_survey_detailsArguments","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_pages":{"post":{"operationId":"list_survey_pages","summary":"List the pages of a survey with title, description and position. Use for \"What pages does my SmartSurvey survey have\".","description":"List the pages of a survey with title, description and position. Use for \"What pages does my SmartSurvey survey have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"SmartSurvey data region of your account: api (UK, the app.smartsurvey.co.uk or .com sign-in), api-eu (app-eu.smartsurvey.com) or api-us (app-us.smartsurvey.com).","enum":["api","api-eu","api-us"],"title":"Region","type":"string"},"survey_id":{"description":"SmartSurvey survey id (the id from list_surveys).","title":"Survey Id","type":"integer"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"1-based page number.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Records per page (1 to 100, default 10).","title":"Page Size"}},"required":["region","survey_id"],"title":"list_survey_pagesArguments","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_page":{"post":{"operationId":"get_survey_page","summary":"Get one survey page with its questions (type, title, position, choices) and page logic. Use for \"What questions are on p","description":"Get one survey page with its questions (type, title, position, choices) and page logic. Use for \"What questions are on page 11 of my SmartSurvey survey\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"SmartSurvey data region of your account: api (UK, the app.smartsurvey.co.uk or .com sign-in), api-eu (app-eu.smartsurvey.com) or api-us (app-us.smartsurvey.com).","enum":["api","api-eu","api-us"],"title":"Region","type":"string"},"survey_id":{"description":"SmartSurvey survey id (the id from list_surveys).","title":"Survey Id","type":"integer"},"page_id":{"description":"Page id (the id from list_survey_pages).","title":"Page Id","type":"integer"}},"required":["region","survey_id","page_id"],"title":"get_survey_pageArguments","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_tracking_links":{"post":{"operationId":"list_tracking_links","summary":"List the tracking links (collectors) of a survey with status, response counts and dates. Use for \"Which tracking links d","description":"List the tracking links (collectors) of a survey with status, response counts and dates. Use for \"Which tracking links does my SmartSurvey survey have and how many responses came through each\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"SmartSurvey data region of your account: api (UK, the app.smartsurvey.co.uk or .com sign-in), api-eu (app-eu.smartsurvey.com) or api-us (app-us.smartsurvey.com).","enum":["api","api-eu","api-us"],"title":"Region","type":"string"},"survey_id":{"description":"SmartSurvey survey id (the id from list_surveys).","title":"Survey Id","type":"integer"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"1-based page number.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Records per page (1 to 100, default 10).","title":"Page Size"}},"required":["region","survey_id"],"title":"list_tracking_linksArguments","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_filter_groups":{"post":{"operationId":"list_filter_groups","summary":"List the saved response filter groups of a survey. Use for \"Which saved filters exist on my SmartSurvey survey\".","description":"List the saved response filter groups of a survey. Use for \"Which saved filters exist on my SmartSurvey survey\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"SmartSurvey data region of your account: api (UK, the app.smartsurvey.co.uk or .com sign-in), api-eu (app-eu.smartsurvey.com) or api-us (app-us.smartsurvey.com).","enum":["api","api-eu","api-us"],"title":"Region","type":"string"},"survey_id":{"description":"SmartSurvey survey id (the id from list_surveys).","title":"Survey Id","type":"integer"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"1-based page number.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Records per page (1 to 100, default 10).","title":"Page Size"}},"required":["region","survey_id"],"title":"list_filter_groupsArguments","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_exports":{"post":{"operationId":"list_survey_exports","summary":"List the exports prepared for a survey (name, type, status, size and dates; the files themselves are not downloaded). Us","description":"List the exports prepared for a survey (name, type, status, size and dates; the files themselves are not downloaded). Use for \"What exports exist for my SmartSurvey survey\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"SmartSurvey data region of your account: api (UK, the app.smartsurvey.co.uk or .com sign-in), api-eu (app-eu.smartsurvey.com) or api-us (app-us.smartsurvey.com).","enum":["api","api-eu","api-us"],"title":"Region","type":"string"},"survey_id":{"description":"SmartSurvey survey id (the id from list_surveys).","title":"Survey Id","type":"integer"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"1-based page number.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Records per page (1 to 100, default 10).","title":"Page Size"}},"required":["region","survey_id"],"title":"list_survey_exportsArguments","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_folders":{"post":{"operationId":"list_survey_folders","summary":"List the survey folders of the account and whether surveys can be filed into each. Use for \"What survey folders do I hav","description":"List the survey folders of the account and whether surveys can be filed into each. Use for \"What survey folders do I have in SmartSurvey\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"SmartSurvey data region of your account: api (UK, the app.smartsurvey.co.uk or .com sign-in), api-eu (app-eu.smartsurvey.com) or api-us (app-us.smartsurvey.com).","enum":["api","api-eu","api-us"],"title":"Region","type":"string"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"1-based page number.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Records per page (1 to 100, default 10).","title":"Page Size"}},"required":["region"],"title":"list_survey_foldersArguments","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_folder":{"post":{"operationId":"get_survey_folder","summary":"Get one folder with every survey in it (title, status, responses, dates). Use for \"Which surveys are in my SmartSurvey f","description":"Get one folder with every survey in it (title, status, responses, dates). Use for \"Which surveys are in my SmartSurvey folder 2\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"SmartSurvey data region of your account: api (UK, the app.smartsurvey.co.uk or .com sign-in), api-eu (app-eu.smartsurvey.com) or api-us (app-us.smartsurvey.com).","enum":["api","api-eu","api-us"],"title":"Region","type":"string"},"folder_id":{"description":"Folder id (the id from list_survey_folders).","title":"Folder Id","type":"integer"}},"required":["region","folder_id"],"title":"get_survey_folderArguments","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_themes":{"post":{"operationId":"list_themes","summary":"List the survey themes on the account. Use for \"Which survey themes do I have in SmartSurvey\".","description":"List the survey themes on the account. Use for \"Which survey themes do I have in SmartSurvey\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"region":{"description":"SmartSurvey data region of your account: api (UK, the app.smartsurvey.co.uk or .com sign-in), api-eu (app-eu.smartsurvey.com) or api-us (app-us.smartsurvey.com).","enum":["api","api-eu","api-us"],"title":"Region","type":"string"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"1-based page number.","title":"Page"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"Records per page (1 to 100, default 10).","title":"Page Size"}},"required":["region"],"title":"list_themesArguments","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}}}}