{"openapi":"3.1.0","info":{"title":"SurveySparrow (BYOK) API","version":"0.1.0","description":"SurveySparrow (BYOK) lets an AI assistant read your own SurveySparrow data through the SurveySparrow API with a key you supply (SurveySparrow private app access token). Read-only: 7 tools (list_surveys, get_survey, list_questions, list_responses, get_cx_metrics, list_survey_folders, list_teams). The BYOK key travels with each request, is used for that one call only and is never stored, logged or...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-surveysparrow.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-surveysparrow/docs"},"termsOfService":"https://connectorbay.com/byok-surveysparrow/terms"},"servers":[{"url":"https://byok-surveysparrow.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-surveysparrow/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 your SurveySparrow surveys with type, archived flag, dates and folder. Filter by survey type, folder, archived stat","description":"List your SurveySparrow surveys with type, archived flag, dates and folder. Filter by survey type, folder, archived state or created and updated dates. Use for \"Which SurveySparrow surveys do I have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"survey_type":{"anyOf":[{"enum":["Conversational","ClassicForm","Kiosk","OfflineApp","NPS","NPSChat","CES","CESChat","CSAT","CSATChat","Employee360"],"type":"string"},{"type":"null"}],"default":null,"description":"Only surveys of this type.","title":"Survey Type"},"archived":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":null,"description":"True for only archived surveys, false for only active ones; leave out for both.","title":"Archived"},"survey_folder_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only surveys in this folder ID (from list_survey_folders).","title":"Survey Folder Id"},"created_date_gte":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only surveys created on or after this date (YYYY-MM-DD).","title":"Created Date Gte"},"created_date_lte":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only surveys created on or before this date (YYYY-MM-DD).","title":"Created Date Lte"},"updated_date_gte":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only surveys updated on or after this date (YYYY-MM-DD).","title":"Updated Date Gte"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (1 to 100).","title":"Limit"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"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 SurveySparrow survey by ID: name, type, archived flag, dates and folder. Use for \"Show details of SurveySparrow ","description":"Get one SurveySparrow survey by ID: name, type, archived flag, dates and folder. Use for \"Show details of SurveySparrow survey 1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"SurveySparrow survey ID (a number), from list_surveys.","title":"Id","type":"integer"}},"required":["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_questions":{"post":{"operationId":"list_questions","summary":"List the questions of one SurveySparrow survey with type, position, display-logic flag and section. Use for \"What questi","description":"List the questions of one SurveySparrow survey with type, position, display-logic flag and section. Use for \"What questions are in SurveySparrow survey 1\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"survey_id":{"description":"SurveySparrow survey ID (a number), from list_surveys.","minimum":1,"title":"Survey Id","type":"integer"},"tag_name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only questions with this tag.","title":"Tag Name"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (1 to 100).","title":"Limit"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["survey_id"],"title":"list_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_responses":{"post":{"operationId":"list_responses","summary":"List responses of one SurveySparrow survey with status, language, completion time and the answers given per question. Co","description":"List responses of one SurveySparrow survey with status, language, completion time and the answers given per question. Contact details are not returned (only a contact ID). Use for \"What responses did SurveySparrow survey 1 receive recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"survey_id":{"description":"SurveySparrow survey ID (a number), from list_surveys.","minimum":1,"title":"Survey Id","type":"integer"},"state":{"anyOf":[{"enum":["started","completed","all"],"type":"string"},{"type":"null"}],"default":null,"description":"Which responses: started, completed or all.","title":"State"},"date_gte":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only responses on or after this date (YYYY-MM-DD).","title":"Date Gte"},"date_lte":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only responses on or before this date (YYYY-MM-DD).","title":"Date Lte"},"order_by":{"anyOf":[{"enum":["startTime","id","completedTime"],"type":"string"},{"type":"null"}],"default":"completedTime","description":"Sort by startTime, id or completedTime (default).","title":"Order By"},"order":{"anyOf":[{"enum":["ASC","DESC"],"type":"string"},{"type":"null"}],"default":"DESC","description":"ASC or DESC (default).","title":"Order"},"limit":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many responses to return (1 to 200).","title":"Limit"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"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_cx_metrics":{"post":{"operationId":"get_cx_metrics","summary":"Get the NPS, CSAT or CES metrics of your SurveySparrow customer-experience surveys, for one survey or for all of them, o","description":"Get the NPS, CSAT or CES metrics of your SurveySparrow customer-experience surveys, for one survey or for all of them, optionally within a date range. The answer shape is not documented, so it is returned as the provider sends it. Use for \"What is my NPS in SurveySparrow\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"type":{"description":"Metric type: NPS, CSAT or CES.","enum":["NPS","CSAT","CES"],"title":"Type","type":"string"},"survey_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only this survey ID; leave out for all CX surveys.","title":"Survey Id"},"date_gte":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only data on or after this date (YYYY-MM-DD).","title":"Date Gte"},"date_lte":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only data on or before this date (YYYY-MM-DD).","title":"Date Lte"}},"required":["type"],"title":"get_cx_metricsArguments","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 SurveySparrow survey folders (workspaces) with description, visibility, team IDs and the surveys inside each. Use f","description":"List SurveySparrow survey folders (workspaces) with description, visibility, team IDs and the surveys inside each. Use for \"Which survey folders exist in SurveySparrow\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"enable_subfolders":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to include subfolders, surveys and echoes of each folder.","title":"Enable Subfolders"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (1 to 100).","title":"Limit"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"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/list_teams":{"post":{"operationId":"list_teams","summary":"List SurveySparrow teams (survey or ticket teams) with description, type and round-robin setting. Use for \"Which teams a","description":"List SurveySparrow teams (survey or ticket teams) with description, type and round-robin setting. Use for \"Which teams are set up in SurveySparrow\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"type":{"anyOf":[{"enum":["SURVEY","TICKET"],"type":"string"},{"type":"null"}],"default":null,"description":"Team type: SURVEY or TICKET.","title":"Type"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many records to return (1 to 100).","title":"Limit"},"page":{"anyOf":[{"maximum":100000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_teamsArguments","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}}}}