https://apitemplate.io/docs/assets/js/297caa80.a7ba1152.js

1"use strict";(self.webpackChunkdocs_site=self.webpackChunkdocs_site||[]).push([["3109"],{7281(e,t,n){n.r(t),n.d(t,{metadata:()=>i,default:()=>h,frontMatter:()=>a,contentTitle:()=>l,toc:()=>o,assets:()=>d});var i=JSON.parse('{"id":"integrations/rest-api","title":"REST API Reference","description":"APITemplate.io REST API guide \u2014 authentication, regional endpoints, rate limits, PDF and image generation endpoints, sync/async modes, SDKs, and response format.","source":"@site/docs/integrations/rest-api.md","sourceDirName":"integrations","slug":"/integrations/rest-api","permalink":"/docs/integrations/rest-api","draft":false,"unlisted":false,"tags":[],"version":"current","sidebarPosition":1,"frontMatter":{"sidebar_position":1,"title":"REST API Reference","description":"APITemplate.io REST API guide \u2014 authentication, regional endpoints, rate limits, PDF and image generation endpoints, sync/async modes, SDKs, and response format.","keywords":["REST API","API reference","PDF API","image API","API authentication","regional endpoints","rate limits","async API","API SDK"]},"sidebar":"docsSidebar","previous":{"title":"Integrations Overview","permalink":"/docs/integrations/overview"},"next":{"title":"Zapier Integration","permalink":"/docs/integrations/zapier"}}'),s=n(4848),r=n(8453);let a={sidebar_position:1,title:"REST API Reference",description:"APITemplate.io REST API guide \u2014 authentication, regional endpoints, rate limits, PDF and image generation endpoints, sync/async modes, SDKs, and response format.",keywords:["REST API","API reference","PDF API","image API","API authentication","regional endpoints","rate limits","async API","API SDK"]},l="REST API",d={},o=[{value:"Base URL",id:"base-url",level:2},{value:"Regional endpoints",id:"regional-endpoints",level:2},{value:"Rate limiting",id:"rate-limiting",level:2},{value:"IP whitelisting",id:"ip-whitelisting",level:2},{value:"Authentication",id:"authentication",level:2},{value:"Key endpoints",id:"key-endpoints",level:2},{value:"Create a PDF from a template",id:"create-a-pdf-from-a-template",level:3},{value:"Create a PDF from HTML",id:"create-a-pdf-from-html",level:3},{value:"Create a PDF from a URL",id:"create-a-pdf-from-a-url",level:3},{value:"Create an image",id:"create-an-image",level:3},{value:"List templates",id:"list-templates",level:3},{value:"Synchronous vs asynchronous",id:"synchronous-vs-asynchronous",level:2},{value:"Response format",id:"response-format",level:2},{value:"SDKs",id:"sdks",level:2},{value:"Full API reference",id:"full-api-reference",level:2}];function c(e){let t={a:"a",admonition:"admonition",code:"code",h1:"h1",h2:"h2",h3:"h3",header:"header",li:"li",p:"p",pre:"pre",strong:"strong",table:"table",tbody:"tbody",td:"td",th:"th",thead:"thead",tr:"tr",ul:"ul",...(0,r.R)(),...e.components};return(0,s.jsxs)(s.Fragment,{children:[(0,s.jsx)(t.header,{children:(0,s.jsx)(t.h1,{id:"rest-api",children:"REST API"})}),"\n",(0,s.jsx)(t.p,{children:"The REST API is the most flexible way to integrate APITemplate.io into your application. It supports PDF generation, image generation, and template management."}),"\n",(0,s.jsx)(t.h2,{id:"base-url",children:"Base URL"}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{children:"https://rest.apitemplate.io/v2/\n"})}),"\n",(0,s.jsx)(t.h2,{id:"regional-endpoints",children:"Regional endpoints"}),"\n",(0,s.jsx)(t.p,{children:"A regional API endpoint is intended for customers in the same region. The data for the requests and generated PDFs/images are processed and stored within the region. Choose the endpoint closest to your users or the one that meets your data residency requirements."}),"\n",(0,s.jsx)(t.p,{children:(0,s.jsx)(t.strong,{children:"Primary regions:"})}),"\n",(0,s.jsxs)(t.table,{children:[(0,s.jsx)(t.thead,{children:(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.th,{children:"Region"}),(0,s.jsx)(t.th,{children:"Endpoint"}),(0,s.jsx)(t.th,{children:"Max Timeout"}),(0,s.jsx)(t.th,{children:"Max Payload Size"})]})}),(0,s.jsxs)(t.tbody,{children:[(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{children:"Default (Singapore)"}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.code,{children:"https://rest.apitemplate.io"})}),(0,s.jsx)(t.td,{children:"100s"}),(0,s.jsx)(t.td,{children:"4 MB"})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{children:"Europe (Frankfurt)"}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.code,{children:"https://rest-de.apitemplate.io"})}),(0,s.jsx)(t.td,{children:"100s"}),(0,s.jsx)(t.td,{children:"4 MB"})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{children:"US East (N. Virginia)"}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.code,{children:"https://rest-us.apitemplate.io"})}),(0,s.jsx)(t.td,{children:"100s"}),(0,s.jsx)(t.td,{children:"4 MB"})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{children:"Australia (Sydney)"}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.code,{children:"https://rest-au.apitemplate.io"})}),(0,s.jsx)(t.td,{children:"30s"}),(0,s.jsx)(t.td,{children:"6 MB"})]})]})]}),"\n",(0,s.jsx)(t.p,{children:(0,s.jsx)(t.strong,{children:"Alternative regions:"})}),"\n",(0,s.jsx)(t.p,{children:"Alternative endpoints offer a higher payload size limit with a shorter timeout, useful for large requests that generate quickly."}),"\n",(0,s.jsxs)(t.table,{children:[(0,s.jsx)(t.thead,{children:(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.th,{children:"Region"}),(0,s.jsx)(t.th,{children:"Endpoint"}),(0,s.jsx)(t.th,{children:"Max Timeout"}),(0,s.jsx)(t.th,{children:"Max Payload Size"})]})}),(0,s.jsxs)(t.tbody,{children:[(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{children:"Default (Singapore)"}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.code,{children:"https://rest-alt.apitemplate.io"})}),(0,s.jsx)(t.td,{children:"30s"}),(0,s.jsx)(t.td,{children:"6 MB"})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{children:"Europe (Frankfurt)"}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.code,{children:"https://rest-alt-de.apitemplate.io"})}),(0,s.jsx)(t.td,{children:"30s"}),(0,s.jsx)(t.td,{children:"6 MB"})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{children:"US East (N. Virginia)"}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.code,{children:"https://rest-alt-us.apitemplate.io"})}),(0,s.jsx)(t.td,{children:"30s"}),(0,s.jsx)(t.td,{children:"6 MB"})]})]})]}),"\n",(0,s.jsx)(t.admonition,{title:"Payload size",type:"note",children:(0,s.jsxs)(t.ul,{children:["\n",(0,s.jsx)(t.li,{children:"Payload size applies to both request and response."}),"\n",(0,s.jsxs)(t.li,{children:["If ",(0,s.jsx)(t.code,{children:"export_type"})," is set to ",(0,s.jsx)(t.code,{children:"json"}),", the output file is stored on AWS S3 and is not subject to the payload size limitation."]}),"\n",(0,s.jsxs)(t.li,{children:["If ",(0,s.jsx)(t.code,{children:"export_type"})," is set to ",(0,s.jsx)(t.code,{children:"file"}),", which returns binary data of the generated PDF, the file size is limited to 6 MB or 4 MB depending on the region."]}),"\n"]})}),"\n",(0,s.jsxs)(t.p,{children:["Other regions are available on request \u2014 contact ",(0,s.jsx)(t.a,{href:"mailto:[email protected]",children:"[email protected]"})," for more information."]}),"\n",(0,s.jsx)(t.h2,{id:"rate-limiting",children:"Rate limiting"}),"\n",(0,s.jsx)(t.p,{children:"The API enforces IP-based rate limits to ensure fair usage and maintain optimal performance:"}),"\n",(0,s.jsxs)(t.ul,{children:["\n",(0,s.jsxs)(t.li,{children:[(0,s.jsx)(t.strong,{children:"100 requests per 10 seconds"})," per IP address"]}),"\n",(0,s.jsxs)(t.li,{children:[(0,s.jsx)(t.strong,{children:"100 concurrent synchronous PDF-generation requests"})," per user account"]}),"\n"]}),"\n",(0,s.jsxs)(t.p,{children:["If you exceed these limits, you'll receive an ",(0,s.jsx)(t.strong,{children:"HTTP 429"}

1)," response, indicating that you've hit the rate cap. Pause briefly before retrying."]}),"\n",(0,s.jsx)(t.admonition,{type:"tip",children:(0,s.jsxs)(t.p,{children:["For high-volume workloads, consider using ",(0,s.jsx)(t.a,{href:"#synchronous-vs-asynchronous",children:"asynchronous generation"})," to avoid hitting concurrency limits."]})}),"\n",(0,s.jsx)(t.h2,{id:"ip-whitelisting",children:"IP whitelisting"}),"\n",(0,s.jsx)(t.p,{children:"To ensure APITemplate.io's PDF and image generation services can retrieve any geo-restricted assets you host (e.g. images, stylesheets, fonts behind a firewall or CDN), whitelist the following outbound IP addresses:"}),"\n",(0,s.jsxs)(t.table,{children:[(0,s.jsx)(t.thead,{children:(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.th,{children:"Region"}),(0,s.jsx)(t.th,{children:"IP Address"})]})}),(0,s.jsxs)(t.tbody,{children:[(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{children:"Singapore"}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.code,{children:"54.169.31.181/32"})})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{children:"US"}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.code,{children:"52.21.225.83/32"})})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{children:"Germany"}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.code,{children:"35.159.181.52/32"})})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{children:"Australia"}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.code,{children:"3.105.245.173/32"})})]})]})]}),"\n",(0,s.jsx)(t.p,{children:"Once whitelisted, the services will be able to access your protected resources without interruption."}),"\n",(0,s.jsx)(t.h2,{id:"authentication",children:"Authentication"}),"\n",(0,s.jsxs)(t.p,{children:["Include your API key in the ",(0,s.jsx)(t.code,{children:"X-API-KEY"})," header:"]}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-bash",children:'curl -H "X-API-KEY: YOUR_API_KEY" https://rest.apitemplate.io/v2/list-templates\n'})}),"\n",(0,s.jsx)(t.h2,{id:"key-endpoints",children:"Key endpoints"}),"\n",(0,s.jsx)(t.h3,{id:"create-a-pdf-from-a-template",children:"Create a PDF from a template"}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-bash",children:'curl -X POST "https://rest.apitemplate.io/v2/create-pdf?template_id=TEMPLATE_ID" \\\n  -H "X-API-KEY: YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{"company_name": "Acme Corp", "amount": "$500"}\'\n'})}),"\n",(0,s.jsx)(t.h3,{id:"create-a-pdf-from-html",children:"Create a PDF from HTML"}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-bash",children:'curl -X POST "https://rest.apitemplate.io/v2/create-pdf-from-html" \\\n  -H "X-API-KEY: YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{\n    "body": "<h1>Hello World</h1><p>This is a PDF from HTML.</p>",\n    "css": "h1 { color: blue; }",\n    "settings": {\n      "paper_size": "A4",\n      "orientation": "Portrait"\n    }\n  }\'\n'})}),"\n",(0,s.jsx)(t.h3,{id:"create-a-pdf-from-a-url",children:"Create a PDF from a URL"}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-bash",children:'curl -X POST "https://rest.apitemplate.io/v2/create-pdf-from-url" \\\n  -H "X-API-KEY: YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{"url": "https://example.com/my-page"}\'\n'})}),"\n",(0,s.jsx)(t.h3,{id:"create-an-image",children:"Create an image"}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-bash",children:'curl -X POST "https://rest.apitemplate.io/v2/create-image?template_id=TEMPLATE_ID" \\\n  -H "X-API-KEY: YOUR_API_KEY" \\\n  -H "Content-Type: application/json" \\\n  -d \'{\n    "overrides": [\n      {"name": "title", "text": "Hello World"}\n    ]\n  }\'\n'})}),"\n",(0,s.jsx)(t.h3,{id:"list-templates",children:"List templates"}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-bash",children:'curl "https://rest.apitemplate.io/v2/list-templates" \\\n  -H "X-API-KEY: YOUR_API_KEY"\n'})}),"\n",(0,s.jsx)(t.h2,{id:"synchronous-vs-asynchronous",children:"Synchronous vs asynchronous"}),"\n",(0,s.jsxs)(t.p,{children:["By default, API calls are ",(0,s.jsx)(t.strong,{children:"synchronous"})," \u2014 you get the result immediately. For large or batch jobs, use ",(0,s.jsx)(t.strong,{children:"asynchronous"})," generation:"]}),"\n",(0,s.jsxs)(t.ul,{children:["\n",(0,s.jsxs)(t.li,{children:["Add ",(0,s.jsx)(t.code,{children:"&async=true"})," to your request"]}),"\n",(0,s.jsxs)(t.li,{children:["You'll get a ",(0,s.jsx)(t.code,{children:"transaction_ref"})," in the response"]}),"\n",(0,s.jsxs)(t.li,{children:["Set up a ",(0,s.jsx)(t.strong,{children:"webhook"})," to get notified when the job is done"]}),"\n"]}),"\n",(0,s.jsx)(t.h2,{id:"response-format",children:"Response format"}),"\n",(0,s.jsxs)(t.p,{children:["Successful responses return JSON with a ",(0,s.jsx)(t.code,{children:"download_url"}),":"]}),"\n",(0,s.jsx)(t.pre,{children:(0,s.jsx)(t.code,{className:"language-json",children:'{\n  "download_url": "https://rest.apitemplate.io/v2/get-pdf/...",\n  "download_url_png": "https://rest.apitemplate.io/v2/get-image/...",\n  "status": "success",\n  "template_id": "abc123",\n  "transaction_ref": "def456"\n}\n'})}),"\n",(0,s.jsx)(t.h2,{id:"sdks",children:"SDKs"}),"\n",(0,s.jsx)(t.p,{children:"Official client libraries are available for multiple languages:"}),"\n",(0,s.jsxs)(t.table,{children:[(0,s.jsx)(t.thead,{children:(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.th,{children:"Language"}),(0,s.jsx)(t.th,{children:"Repository"})]})}),(0,s.jsxs)(t.tbody,{children:[(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{children:"Python"}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.a,{href:"https://github.com/APITemplate-io/apitemplateio-python",children:"apitemplateio-python"})})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{children:"JavaScript"}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.a,{href:"https://github.com/APITemplate-io/apitemplateio-javascript",children:"apitemplateio-javascript"})})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{children:"PHP"}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.a,{href:"https://github.com/APITemplate-io/apitemplateio-php",children:"apitemplateio-php"})})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{children:"C#"}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.a,{href:"https://github.com/APITemplate-io/apitemplateio-csharp",children:"apitemplateio-csharp"})})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{children:"Java"}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.a,{href:"https://github.com/APITemplate-io/apitemplateio-java",children:"apitemplateio-java"})})]}),(0,s.jsxs)(t.tr,{children:[(0,s.jsx)(t.td,{children:"UiPath"}),(0,s.jsx)(t.td,{children:(0,s.jsx)(t.a,{href:"https://github.com/APITemplate-io/UIPath-Integration",children:"UIPath-Integration"})})]})]})]}),"\n",(0,s.jsx)(t.h2,{id:"full-api-reference",children:"Full API reference"}),"\n",(0,s.jsxs)(t.p,{children:["For the complete list of endpoints, parameters, and examples, see the ",(0,s.jsx)(t.a,{href:"https://apitemplate.io/apiv2/",children:"API Reference v2"}),"."]}),"\n",(0,s.jsxs)(t.p,{children:["You can also access the ",(0,s.jsx)(t.a,{href:"https://apitemplateio.s3.ap-southeast-1.amazonaws.com/redoc_apiv2/apitemplateiov2_api.yaml",children:"OpenAPI specification (YAML)"})," directly for use with tools like Postman, Swagger UI, or code generators."]})]})}function h(e={}){let{wrapper:t}={...(0,r.R)(),...e.components};return t?(0,s.jsx)(t,{...e,children:(0,s.jsx)(c,{...e})}):c(e)}},8453(e,t,n){n.d(t,{R:()=>a,x:()=>l});var i=n(6540);let s={},r=i.createContext(s);function a(e){let t=i.useContext(r);return i.useMemo(function(){return"function"==typeof e?e(t):{...t,...e}},[t,e])}function l(e){let t;return t=e.disableParentContext?"function"==typeof e.components?e.components(s):e.components||s:a(e.components),i.createElement(r.Provider,{value:t},e.children)}}}]);