{"openapi":"3.1.0","info":{"title":"DocSpring (BYOK) API","version":"0.1.0","description":"DocSpring (BYOK) lets an AI assistant read your own DocSpring data through the DocSpring API with a key you supply (API token ID). Read-only: 10 tools (test_authentication, list_templates, get_template, get_template_schema, list_folders, list_submissions, list_template_submissions, list_combined_submissions, list_webhooks, get_webhook). The BYOK key travels with each request, is used for that one...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-docspring.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-docspring/docs"},"termsOfService":"https://connectorbay.com/byok-docspring/terms"},"servers":[{"url":"https://byok-docspring.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-docspring/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/test_authentication":{"post":{"operationId":"test_authentication","summary":"Check that the API token ID and secret are valid; returns a status of success or an error message. Use for \"Are my DocSp","description":"Check that the API token ID and secret are valid; returns a status of success or an error message. Use for \"Are my DocSpring API credentials working\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"test_authenticationArguments","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_templates":{"post":{"operationId":"list_templates","summary":"List PDF and HTML templates with type, folder, page count, lock state and version; searchable by name and filterable by ","description":"List PDF and HTML templates with type, folder, page count, lock state and version; searchable by name and filterable by folder. Use for \"Which DocSpring templates do I have in my account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"query":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Search templates by name.","title":"Query"},"parent_folder_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only templates in this folder id, for example 'fld_1234567890abcdef01'.","title":"Parent Folder Id"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"per_page":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Results per page (1 to 50).","title":"Per Page"}},"title":"list_templatesArguments","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_template":{"post":{"operationId":"get_template","summary":"Get one template's settings: type, folder, page count, expiry rules, public web form flag and version information. Use f","description":"Get one template's settings: type, folder, page count, expiry rules, public web form flag and version information. Use for \"Show the settings of DocSpring template tpl_1234567890abcdef02\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"template_id":{"description":"DocSpring template id, for example 'tpl_1234567890abcdef02'.","maxLength":200,"title":"Template Id","type":"string"}},"required":["template_id"],"title":"get_templateArguments","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_template_schema":{"post":{"operationId":"get_template_schema","summary":"Get the JSON schema that describes the fields a template accepts when a PDF is generated. Use for \"What data fields does","description":"Get the JSON schema that describes the fields a template accepts when a PDF is generated. Use for \"What data fields does DocSpring template tpl_1234567890abcdef02 expect\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"template_id":{"description":"DocSpring template id, for example 'tpl_1234567890abcdef02'.","maxLength":200,"title":"Template Id","type":"string"}},"required":["template_id"],"title":"get_template_schemaArguments","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_folders":{"post":{"operationId":"list_folders","summary":"List template folders with id, name, path and parent folder; filterable by parent folder. Use for \"How are my DocSpring ","description":"List template folders with id, name, path and parent folder; filterable by parent folder. Use for \"How are my DocSpring templates organised into folders\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"parent_folder_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only folders directly inside this folder id.","title":"Parent Folder Id"}},"title":"list_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_submissions":{"post":{"operationId":"list_submissions","summary":"List PDF submissions across all templates with processing state, expiry and template id (the submitted data is not reque","description":"List PDF submissions across all templates with processing state, expiry and template id (the submitted data is not requested). Use for \"Which DocSpring PDFs were generated recently and did any fail\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"How many submissions to return per page (the API default applies when omitted).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from next_cursor of the previous page, to fetch the next page.","title":"Cursor"},"created_after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only submissions created after this ISO 8601 time, for example 2026-01-01T00:00:00Z.","title":"Created After"},"created_before":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only submissions created before this ISO 8601 time.","title":"Created Before"},"type":{"anyOf":[{"enum":["test","live"],"type":"string"},{"type":"null"}],"default":null,"description":"Filter by submission type: test or live.","title":"Type"}},"title":"list_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/list_template_submissions":{"post":{"operationId":"list_template_submissions","summary":"List the submissions of one template with processing state and expiry (the submitted data is not requested). Use for \"Ho","description":"List the submissions of one template with processing state and expiry (the submitted data is not requested). Use for \"How many submissions does DocSpring template tpl_1234567890abcdef02 have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"template_id":{"description":"DocSpring template id, for example 'tpl_1234567890abcdef02'.","maxLength":200,"title":"Template Id","type":"string"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"How many submissions to return per page (the API default applies when omitted).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor from next_cursor of the previous page, to fetch the next page.","title":"Cursor"},"created_after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only submissions created after this ISO 8601 time, for example 2026-01-01T00:00:00Z.","title":"Created After"},"created_before":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only submissions created before this ISO 8601 time.","title":"Created Before"},"type":{"anyOf":[{"enum":["test","live"],"type":"string"},{"type":"null"}],"default":null,"description":"Filter by submission type: test or live.","title":"Type"}},"required":["template_id"],"title":"list_template_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/list_combined_submissions":{"post":{"operationId":"list_combined_submissions","summary":"List combined (merged) PDF jobs with state, expiry, processing time and the ids of the submissions merged. Use for \"What","description":"List combined (merged) PDF jobs with state, expiry, processing time and the ids of the submissions merged. Use for \"What combined PDFs has DocSpring produced\".","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"},"per_page":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Results per page (1 to 50).","title":"Per Page"}},"title":"list_combined_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/list_webhooks":{"post":{"operationId":"list_webhooks","summary":"List webhooks with event types, mode, scope (templates, folders, tokens), failure counters and disabled state; the secre","description":"List webhooks with event types, mode, scope (templates, folders, tokens), failure counters and disabled state; the secret and headers are not returned. Use for \"Which DocSpring webhooks are configured and are any failing\".","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"},"per_page":{"anyOf":[{"maximum":50,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Results per page (1 to 50).","title":"Per Page"},"event_type":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only webhooks subscribed to this event type.","title":"Event Type"},"mode":{"anyOf":[{"enum":["test","live"],"type":"string"},{"type":"null"}],"default":null,"description":"Filter by mode: test or live.","title":"Mode"},"template_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only webhooks scoped to this template id.","title":"Template Id"},"folder_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only webhooks scoped to this folder id.","title":"Folder Id"}},"title":"list_webhooksArguments","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_webhook":{"post":{"operationId":"get_webhook","summary":"Get one webhook's event types, mode, scope, failure counters and disabled state (secret and headers are not returned). U","description":"Get one webhook's event types, mode, scope, failure counters and disabled state (secret and headers are not returned). Use for \"Is DocSpring webhook whk_1234567890abcdef01 enabled\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"webhook_id":{"description":"DocSpring webhook id, for example 'whk_1234567890abcdef01'.","maxLength":200,"title":"Webhook Id","type":"string"}},"required":["webhook_id"],"title":"get_webhookArguments","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}}}}