{"openapi":"3.1.0","info":{"title":"Tally (BYOK) API","version":"0.1.0","description":"Tally (BYOK) lets an AI assistant read your own Tally data through the Tally API with a key you supply (API key (starts with tly-)). Read-only: 8 tools (get_current_user, list_forms, get_form, list_form_questions, list_form_submissions, get_form_metrics, get_form_drop_off, list_workspaces). 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-tally.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-tally/docs"},"termsOfService":"https://connectorbay.com/byok-tally/terms"},"servers":[{"url":"https://byok-tally.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-tally/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_current_user":{"post":{"operationId":"get_current_user","summary":"Show the Tally user the key belongs to: name, email, organization id and subscription plan (FREE, PRO or BUSINESS). Use ","description":"Show the Tally user the key belongs to: name, email, organization id and subscription plan (FREE, PRO or BUSINESS). Use for \"Which Tally account is my key connected to\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_current_userArguments","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 forms with status (BLANK, DRAFT, PUBLISHED), submission count, closed flag and dates. Up to 500 per page. Use for \"","description":"List forms with status (BLANK, DRAFT, PUBLISHED), submission count, closed flag and dates. Up to 500 per page. Use for \"Which Tally forms do I have and how many submissions has each received\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Forms per page (1 to 500, default 50).","title":"Limit"}},"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_form":{"post":{"operationId":"get_form","summary":"Get one form's name, status, workspace, submission count, closed flag and dates (not its blocks). Use for \"Is Tally form","description":"Get one form's name, status, workspace, submission count, closed flag and dates (not its blocks). Use for \"Is Tally form wMXxEj published and how many submissions does it have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"form_id":{"description":"Form id as returned by list_forms, for example 'wMXxEj'.","maxLength":200,"title":"Form Id","type":"string"}},"required":["form_id"],"title":"get_formArguments","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_form_questions":{"post":{"operationId":"list_form_questions","summary":"List the questions of a form with type, title and number of responses. Use for \"What questions does Tally form wMXxEj as","description":"List the questions of a form with type, title and number of responses. Use for \"What questions does Tally form wMXxEj ask\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"form_id":{"description":"Form id as returned by list_forms, for example 'wMXxEj'.","maxLength":200,"title":"Form Id","type":"string"}},"required":["form_id"],"title":"list_form_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_form_submissions":{"post":{"operationId":"list_form_submissions","summary":"List a form's submissions with completion flag, time and each response's question id and formatted answer. Filter by com","description":"List a form's submissions with completion flag, time and each response's question id and formatted answer. Filter by completed or partial and by date; up to 500 per page. Use for \"Show the latest completed submissions of Tally form wMXxEj\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"form_id":{"description":"Form id as returned by list_forms, for example 'wMXxEj'.","maxLength":200,"title":"Form Id","type":"string"},"filter":{"anyOf":[{"enum":["all","completed","partial"],"type":"string"},{"type":"null"}],"default":"all","description":"Which submissions: all, completed or partial.","title":"Filter"},"start_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only submissions on or after this ISO 8601 date, for example 2026-01-01.","title":"Start Date"},"end_date":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only submissions on or before this ISO 8601 date.","title":"End Date"},"after_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only submissions after this submission id (cursor).","title":"After Id"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"limit":{"anyOf":[{"maximum":500,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Submissions per page (1 to 500, default 50).","title":"Limit"}},"required":["form_id"],"title":"list_form_submissionsArguments","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_form_metrics":{"post":{"operationId":"get_form_metrics","summary":"Get aggregate metrics of a form for a period: visits, starts, completions, completion rate and durations. Use for \"What ","description":"Get aggregate metrics of a form for a period: visits, starts, completions, completion rate and durations. Use for \"What was the completion rate of Tally form wMXxEj over the last 30 days\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"form_id":{"description":"Form id as returned by list_forms, for example 'wMXxEj'.","maxLength":200,"title":"Form Id","type":"string"},"period":{"description":"Time window: today, yesterday, 24h, 7d, 30d, 3m, 6m, 12m or all.","enum":["today","yesterday","24h","7d","30d","3m","6m","12m","all"],"title":"Period","type":"string"}},"required":["form_id","period"],"title":"get_form_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/get_form_drop_off":{"post":{"operationId":"get_form_drop_off","summary":"Get per-question drop-off statistics of a form for a period: views, answers, drops and rates per block, plus overall com","description":"Get per-question drop-off statistics of a form for a period: views, answers, drops and rates per block, plus overall completion figures. Use for \"Where do people abandon Tally form wMXxEj\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"form_id":{"description":"Form id as returned by list_forms, for example 'wMXxEj'.","maxLength":200,"title":"Form Id","type":"string"},"period":{"description":"Time window: today, yesterday, 24h, 7d, 30d, 3m, 6m, 12m or all.","enum":["today","yesterday","24h","7d","30d","3m","6m","12m","all"],"title":"Period","type":"string"}},"required":["form_id","period"],"title":"get_form_drop_offArguments","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_workspaces":{"post":{"operationId":"list_workspaces","summary":"List workspaces with id, name and dates. Use for \"What Tally workspaces do I have\".","description":"List workspaces with id, name and dates. Use for \"What Tally workspaces do I have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_workspacesArguments","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}}}}