{"openapi":"3.1.0","info":{"title":"Formfeed (BYOK) API","version":"0.1.0","description":"Formfeed (BYOK) lets an AI assistant read your own Formfeed data through the Formfeed API with a key you supply (Formfeed API key (ff_live_ or ff_test_; reads need the render:read, template:read and account:read scopes)). Read-only: 11 tools (list_renders, get_render, get_batch_job, list_templates, get_template_schema, list_template_channels, get_usage, get_account, get_brand_kit, list_partials,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-formfeed.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-formfeed/docs"},"termsOfService":"https://connectorbay.com/byok-formfeed/terms"},"servers":[{"url":"https://byok-formfeed.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-formfeed/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_renders":{"post":{"operationId":"list_renders","summary":"List the documents rendered in the workspace, newest first, with status, output type, size, page count, units used, the ","description":"List the documents rendered in the workspace, newest first, with status, output type, size, page count, units used, the template and version used, any error, your own meta values and times. Download links are left out. Use for \"Which PDF renders failed recently\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"status":{"anyOf":[{"maxLength":30,"type":"string"},{"type":"null"}],"default":null,"description":"Only renders with this status, for example 'failed' or 'succeeded'.","title":"Status"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return per page (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Paging cursor: pass next_cursor from the previous answer unchanged to get the next page.","title":"Cursor"}},"title":"list_rendersArguments","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_render":{"post":{"operationId":"get_render","summary":"Get one render by its id (starts with rnd_): status, output type, size, pages, units, template and version, error and me","description":"Get one render by its id (starts with rnd_): status, output type, size, pages, units, template and version, error and meta values. The download link is not returned. Use for \"What is the status of render rnd_01J8ZK4M3Q7X\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"render_id":{"description":"Render id (starts with rnd_), from list_renders.","maxLength":64,"title":"Render Id","type":"string"}},"required":["render_id"],"title":"get_renderArguments","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_batch_job":{"post":{"operationId":"get_batch_job","summary":"Get a batch render job by its id (starts with job_): status (queued, processing, completed, partially_failed, failed), h","description":"Get a batch render job by its id (starts with job_): status (queued, processing, completed, partially_failed, failed), how many items there are and how many succeeded or failed. Use for \"Did batch job job_01J8ZK4M3Q finish\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"job_id":{"description":"Batch job id (starts with job_).","maxLength":64,"title":"Job Id","type":"string"}},"required":["job_id"],"title":"get_batch_jobArguments","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 the document templates of the workspace (archived ones are left out). Needs the template:read scope. Use for \"Which","description":"List the document templates of the workspace (archived ones are left out). Needs the template:read scope. Use for \"Which document templates do I have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return per page (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Paging cursor: pass next_cursor from the previous answer unchanged to get the next page.","title":"Cursor"}},"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_schema":{"post":{"operationId":"get_template_schema","summary":"Get the JSON Schema of the data a template expects, for the published version or a chosen version or release channel. An","description":"Get the JSON Schema of the data a template expects, for the published version or a chosen version or release channel. Answers 404 when the template has no stored or inferred schema. Use for \"What data fields does the invoice template need\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"template_id":{"description":"Template slug (for example 'invoice') or template id (starts with tpl_), from list_templates.","maxLength":64,"title":"Template Id","type":"string"},"version":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Version to read: a version number, latest, or a release channel name such as staging. Default is the published version.","title":"Version"}},"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_template_channels":{"post":{"operationId":"list_template_channels","summary":"List a template's release channels (published and named ones such as staging) with the version each points to, canary se","description":"List a template's release channels (published and named ones such as staging) with the version each points to, canary settings, renders of the last 24 hours and the plan's channel limits. Use for \"Which release channels does the invoice template have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"template_id":{"description":"Template slug (for example 'invoice') or template id (starts with tpl_), from list_templates.","maxLength":64,"title":"Template Id","type":"string"}},"required":["template_id"],"title":"list_template_channelsArguments","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_usage":{"post":{"operationId":"get_usage","summary":"Get the workspace's metered usage for a billing period: units included, used, overage used, prepaid overage balance, a d","description":"Get the workspace's metered usage for a billing period: units included, used, overage used, prepaid overage balance, a daily series of units and renders, and units per template. Use for \"How many units have I used this month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"period":{"anyOf":[{"maxLength":7,"type":"string"},{"type":"null"}],"default":null,"description":"Billing period as YYYY-MM; default is the current period.","title":"Period"}},"title":"get_usageArguments","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_account":{"post":{"operationId":"get_account","summary":"Get the workspace, its plan with limits (requests per second, concurrency, page and size limits) and the dates of the cu","description":"Get the workspace, its plan with limits (requests per second, concurrency, page and size limits) and the dates of the current billing period. Needs the account:read scope. Use for \"Which plan is my Formfeed workspace on and what are its limits\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_accountArguments","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_brand_kit":{"post":{"operationId":"get_brand_kit","summary":"Get the organisation's brand kit: name, colours, fonts, font size, logo links, legal footer, default page settings and v","description":"Get the organisation's brand kit: name, colours, fonts, font size, logo links, legal footer, default page settings and version. Use for \"What brand colours and fonts are set up for my documents\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_brand_kitArguments","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_partials":{"post":{"operationId":"list_partials","summary":"List the organisation's shared template partials (reusable fragments such as letterheads) with name, template engine, de","description":"List the organisation's shared template partials (reusable fragments such as letterheads) with name, template engine, description, version and times. Sources are not included. Use for \"Which shared partials do my templates use\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_partialsArguments","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_library_files":{"post":{"operationId":"list_library_files","summary":"List files in the workspace's asset library (images and PDFs used by templates), newest first, optionally under a name p","description":"List files in the workspace's asset library (images and PDFs used by templates), newest first, optionally under a name prefix. Use for \"Which images are in my Formfeed file library\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"prefix":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only files whose library name starts with this prefix, for example 'brand/'.","title":"Prefix"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"How many results to return per page (1 to 100).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Paging cursor: pass next_cursor from the previous answer unchanged to get the next page.","title":"Cursor"}},"title":"list_library_filesArguments","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}}}}