{ "openapi": "3.0.3", "info": { "title": "Docamatic API", "description": "REST API for generating PDFs and images, writing to PDFs, merging files, encrypting documents, and checking account usage.", "version": "1.0.0", "license": { "name": "Proprietary", "url": "https://docamatic.com/terms-of-service" } }, "servers": [ { "url": "https://docamatic.com/api/v1", "description": "Production" } ], "tags": [ { "name": "Documents", "description": "Endpoints that generate, modify, merge, encrypt, and delete documents." }, { "name": "Account", "description": "Endpoints that return account profile and credit usage." }, { "name": "Templates", "description": "Endpoints for template-driven document generation and template metadata." } ], "security": [ { "BearerAuth": [] } ], "paths": { "/pdf": { "post": { "tags": [ "Documents" ], "summary": "Generate a PDF from URL or HTML", "operationId": "createPdf", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PdfRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/DocumentGenerated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "408": { "$ref": "#/components/responses/RequestTimeout" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/template": { "post": { "tags": [ "Templates" ], "summary": "Generate a PDF or image from a template", "operationId": "createFromTemplate", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TemplateRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/DocumentGenerated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "408": { "$ref": "#/components/responses/RequestTimeout" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/image": { "post": { "tags": [ "Documents" ], "summary": "Generate an image or screenshot from URL or HTML", "operationId": "createImage", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/DocumentGenerated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "408": { "$ref": "#/components/responses/RequestTimeout" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/screenshot": { "post": { "tags": [ "Documents" ], "summary": "Alias for /image", "description": "Undocumented alias for the /image endpoint. Accepts the same request body and returns the same response.", "operationId": "createScreenshot", "x-internal": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImageRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/DocumentGenerated" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/write": { "post": { "tags": [ "Documents" ], "summary": "Write text, images, QR codes, and barcodes to an existing PDF", "operationId": "writeToPdf", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WriteRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/DocumentGenerated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "408": { "$ref": "#/components/responses/RequestTimeout" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/merge": { "post": { "tags": [ "Documents" ], "summary": "Merge multiple PDFs into one document", "operationId": "mergePdfs", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MergeRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/DocumentGenerated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "408": { "$ref": "#/components/responses/RequestTimeout" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/encrypt": { "post": { "tags": [ "Documents" ], "summary": "Password-protect an existing PDF", "operationId": "encryptPdf", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EncryptRequest" } } } }, "responses": { "200": { "$ref": "#/components/responses/DocumentGenerated" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "405": { "$ref": "#/components/responses/MethodNotAllowed" }, "408": { "$ref": "#/components/responses/RequestTimeout" }, "415": { "$ref": "#/components/responses/UnsupportedMediaType" }, "422": { "$ref": "#/components/responses/ValidationError" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/delete": { "delete": { "tags": [ "Documents" ], "summary": "Delete a document from storage", "description": "Deletes a file from Docamatic storage. All files are also automatically deleted after the configured storage period.", "operationId": "deleteDocument", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteRequest" } } } }, "responses": { "200": { "description": "Delete successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteResponse" }, "example": { "message": "Delete successful", "url": "https://docamatic.s3.eu-west-1.amazonaws.com/ty372j6F/12042019/8a953f9c-6a97-4453-ba49-092c7f8a28f5.pdf", "success": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "422": { "$ref": "#/components/responses/ValidationError" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/credits": { "get": { "tags": [ "Account" ], "summary": "Get API usage summary for the current billing period", "operationId": "getCredits", "responses": { "200": { "description": "Current credit usage", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditsResponse" }, "example": { "production": { "limit": 1000, "used": 250, "remaining": 750 }, "test": { "limit": 1000, "used": 0, "remaining": 1000 }, "period_start": "2019-12-30 00:00:00", "period_end": "2020-01-30 23:59:59" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } } }, "/me": { "get": { "tags": [ "Account" ], "summary": "Get authenticated user profile", "description": "Returns profile information for the authenticated user.", "operationId": "getMe", "x-internal": true, "responses": { "200": { "description": "Authenticated user profile", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MeResponse" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/documents": { "get": { "tags": [ "Documents" ], "summary": "List stored documents", "description": "Returns a list of documents stored for the authenticated user.", "operationId": "listDocuments", "x-internal": true, "responses": { "200": { "description": "Document list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentItem" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/templates": { "get": { "tags": [ "Templates" ], "summary": "List templates available to the user", "operationId": "listTemplates", "x-internal": true, "responses": { "200": { "description": "Template list", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateItem" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "Pass your Docamatic API key as a Bearer token in the Authorization header." } }, "responses": { "DocumentGenerated": { "description": "Document generated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentResponse" }, "example": { "document": "https://docamatic.s3.eu-west-1.amazonaws.com/prod/34e1e099-e58d-887c-955d-82c0cbbeefde/464f5c96-174b-4a24-a1d5-fc84a2861fxr.pdf", "size": "85.79 KB", "success": true, "transaction_id": "464f5c96-174b-4a24-a1d5-fc84a2861fxr" } } } }, "BadRequest": { "description": "Bad request — the request was invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Unauthorized": { "description": "Unauthorized — user does not have permission", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Unauthenticated." } } } }, "Forbidden": { "description": "Forbidden — request not authenticated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "MethodNotAllowed": { "description": "Method Not Allowed — incorrect HTTP method provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "RequestTimeout": { "description": "Request Timeout — the request timed out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "UnsupportedMediaType": { "description": "Unsupported Media Type — response is not valid JSON", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "ValidationError": { "description": "Unprocessable Entity — valid JSON but an error was encountered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationError" } } } }, "RateLimited": { "description": "Too Many Requests — client has exceeded 120 requests per minute", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "message": "Too Many Requests" } } } }, "InternalServerError": { "description": "Internal Server Error — please try again or contact support", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "Unit": { "type": "string", "description": "Unit of measurement.", "enum": [ "px", "in", "cm", "mm" ] }, "PaperFormat": { "type": "string", "description": "Paper format. Takes priority over width/height when set.", "enum": [ "Letter", "Legal", "Tabloid", "Ledger", "A0", "A1", "A2", "A3", "A4", "A5" ] }, "TemplateName": { "type": "string", "description": "A valid Docamatic template name. See https://docamatic.com/templates for previews and example requests.", "enum": [ "invoice1", "packing_slip1", "returns_form", "invoice5", "invoice4", "invoice3", "quotation2", "commercial_invoice", "shipping_label_4x6", "barcode_label", "qr_label", "conference_badge", "shipping_label_4x3" ] }, "EmailOptions": { "type": "object", "description": "Options for emailing the generated document.", "properties": { "to": { "type": "string", "format": "email", "description": "Recipient email address." }, "cc": { "type": "string", "format": "email", "description": "CC email address." }, "bcc": { "type": "string", "format": "email", "description": "BCC email address." }, "subject": { "type": "string", "description": "Email subject line." }, "body": { "type": "string", "description": "Email body text." }, "filename": { "type": "string", "maxLength": 80, "description": "Filename for the attached document." } }, "additionalProperties": false }, "S3Options": { "type": "object", "description": "Options for saving the generated document directly to your own Amazon S3 bucket. Your bucket policy must grant Docamatic write permissions.", "required": [ "region", "bucket" ], "properties": { "region": { "type": "string", "description": "AWS region where your bucket is located (e.g. us-east-1).", "pattern": "^[a-z]{2}-[a-z]+-[0-9]{1}$" }, "bucket": { "type": "string", "maxLength": 255, "description": "S3 bucket name. Must not be 'docamatic'." }, "path": { "type": "string", "maxLength": 255, "description": "Optional path prefix within the bucket (e.g. 'invoices')." } }, "additionalProperties": false }, "BasicAuthOptions": { "type": "object", "description": "Credentials for basic HTTP authentication on a protected source URL.", "required": [ "username", "password" ], "properties": { "username": { "type": "string" }, "password": { "type": "string" } }, "additionalProperties": false }, "PdfRequest": { "type": "object", "required": [ "source" ], "properties": { "source": { "type": "string", "description": "A valid URL or HTML string to generate the PDF from." }, "media": { "type": "string", "enum": [ "screen", "print" ], "default": "screen", "description": "Generate the PDF using screen or print CSS media rules." }, "format": { "allOf": [ { "$ref": "#/components/schemas/PaperFormat" } ], "default": "Letter", "description": "Paper format. Takes priority over width/height when set." }, "margin_top": { "type": "number", "minimum": 0, "description": "Top paper margin. Unit is controlled by margin_unit." }, "margin_right": { "type": "number", "minimum": 0, "description": "Right paper margin. Unit is controlled by margin_unit." }, "margin_bottom": { "type": "number", "minimum": 0, "description": "Bottom paper margin. Unit is controlled by margin_unit." }, "margin_left": { "type": "number", "minimum": 0, "description": "Left paper margin. Unit is controlled by margin_unit." }, "margin_unit": { "allOf": [ { "$ref": "#/components/schemas/Unit" } ], "default": "cm", "description": "Unit of measurement for margin values." }, "width": { "type": "number", "description": "Paper width. Ignored if format is set." }, "height": { "type": "number", "description": "Paper height. Ignored if format is set." }, "unit": { "allOf": [ { "$ref": "#/components/schemas/Unit" } ], "default": "cm", "description": "Unit of measurement for width and height." }, "landscape": { "type": "boolean", "default": false, "description": "Set to true for landscape orientation." }, "test": { "type": "boolean", "default": false, "description": "Create a test document that does not consume production credits. The document will have a 'sample' watermark." }, "encode": { "type": "boolean", "default": false, "description": "Return the document as a base64 encoded string. Documents over 4MB cannot be returned as base64 — a URL will be returned instead." }, "webhook": { "type": "string", "format": "uri", "description": "A valid URL to receive a POST request with the result once the document has been generated. Your endpoint must return a 200 status code." }, "zoom": { "type": "number", "minimum": 0.1, "maximum": 2, "default": 1, "description": "Scale of the webpage rendering. Must be between 0.1 and 2." }, "disable_backgrounds": { "type": "boolean", "default": false, "description": "Suppress background graphics in the generated PDF." }, "grayscale": { "type": "boolean", "default": false, "description": "Generate the document in grayscale." }, "delay": { "type": "integer", "minimum": 100, "maximum": 9000, "description": "Delay in milliseconds before capturing the page." }, "header_template": { "type": "string", "description": "HTML template for the print header. Use CSS classes date, title, url, pageNumber, totalPages to inject dynamic values." }, "footer_template": { "type": "string", "description": "HTML template for the print footer. Uses the same format as header_template." }, "header_footer": { "type": "boolean", "description": "Enable display of header and footer." }, "page_numbers": { "type": "boolean", "default": false, "description": "Insert page numbers into the footer of each page. Ignored if footer_template is set." }, "css": { "type": "string", "description": "A valid URL pointing to a CSS file or a CSS string to inject before generation. If a URL, it must be publicly accessible." }, "prefer_css_page_size": { "type": "boolean", "default": false, "description": "Give CSS @page size declarations priority over width/height/format options." }, "page_ranges": { "type": "string", "description": "Page ranges to print, e.g. '1-5, 8, 11-13'. Defaults to all pages." }, "accept_cookie_warning": { "type": "boolean", "default": true, "description": "Attempt to automatically accept cookie consent notifications before generating the document. See click_elements for manual targeting." }, "click_elements": { "type": "array", "items": { "type": "string" }, "description": "Click button or link elements before generation. Specify elements by CSS class name or text value, e.g. [\"Accept\", \".cookie-btn\"]." }, "name": { "type": "string", "maxLength": 255, "default": "Document", "description": "A descriptive name for your document, visible in the dashboard." }, "auth": { "$ref": "#/components/schemas/BasicAuthOptions" }, "email": { "$ref": "#/components/schemas/EmailOptions" }, "s3": { "$ref": "#/components/schemas/S3Options" } }, "additionalProperties": false }, "TemplateRequest": { "type": "object", "required": [ "template", "data" ], "properties": { "template": { "allOf": [ { "$ref": "#/components/schemas/TemplateName" } ], "description": "A valid template name. See https://docamatic.com/templates." }, "data": { "type": "object", "additionalProperties": true, "description": "Data to pass to the template. All fields are optional — see individual template pages for example requests." }, "lines": { "description": "Line items array, commonly used by Zapier integrations.", "oneOf": [ { "type": "array", "items": { "type": "object", "additionalProperties": true } }, { "type": "object", "additionalProperties": true } ] }, "file_type": { "type": "string", "enum": [ "pdf", "png", "jpg", "webp" ], "default": "pdf", "description": "Output file format." }, "format": { "allOf": [ { "$ref": "#/components/schemas/PaperFormat" } ], "default": "Letter", "description": "Paper format. Ignored if the template has a fixed size." }, "width": { "type": "number", "description": "Document width. Ignored if format is set or the template has a fixed size." }, "height": { "type": "number", "description": "Document height. Ignored if format is set or the template has a fixed size." }, "unit": { "allOf": [ { "$ref": "#/components/schemas/Unit" } ], "default": "cm", "description": "Unit of measurement for width and height." }, "landscape": { "type": "boolean", "default": false, "description": "Set to true for landscape orientation." }, "test": { "type": "boolean", "default": false, "description": "Create a test document that does not consume production credits. The document will have a 'sample' watermark." }, "encode": { "type": "boolean", "default": false, "description": "Return the document as a base64 encoded string. Documents over 4MB cannot be returned as base64 — a URL will be returned instead." }, "webhook": { "type": "string", "format": "uri", "description": "A valid URL to receive a POST request with the result once the document has been generated. Your endpoint must return a 200 status code." }, "quality": { "type": "number", "minimum": 1, "maximum": 3, "default": 1, "description": "A float value between 1 and 3. Higher values produce better quality but larger file sizes." }, "grayscale": { "type": "boolean", "default": false, "description": "Generate the document in grayscale." }, "page_numbers": { "type": "boolean", "default": false, "description": "Insert page numbers into the footer of each page. Only applies when generating as a PDF." }, "name": { "type": "string", "description": "A descriptive name for your document, visible in the dashboard." }, "font": { "type": "string", "maxLength": 150, "default": "Roboto", "description": "A Google Font name (must match exactly). Browse fonts at https://fonts.google.com. Examples: Lato, Open Sans, Nunito." }, "font_size": { "type": "number", "minimum": 0.5, "maximum": 1.4, "default": 0.8, "description": "Base font size scalar. Valid range is 0.5 to 1.4." }, "font_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "default": "#000000", "description": "Hex color code for the font color, e.g. #000000." }, "email": { "$ref": "#/components/schemas/EmailOptions" }, "s3": { "$ref": "#/components/schemas/S3Options" } }, "additionalProperties": false }, "ImageRequest": { "type": "object", "required": [ "source" ], "properties": { "source": { "type": "string", "description": "A valid URL or HTML string to generate the image from." }, "file_type": { "type": "string", "enum": [ "png", "jpg", "webp" ], "default": "png", "description": "Output image format." }, "media": { "type": "string", "enum": [ "screen", "print" ], "default": "screen", "description": "Generate the image using screen or print CSS media rules." }, "width": { "type": "number", "default": 1440, "description": "Image width. Unit is controlled by the unit parameter." }, "height": { "type": "number", "default": 900, "description": "Image height. Unit is controlled by the unit parameter." }, "unit": { "allOf": [ { "$ref": "#/components/schemas/Unit" } ], "default": "px", "description": "Unit of measurement for width and height." }, "mobile": { "type": "boolean", "default": false, "description": "Whether to take the meta viewport tag into account (simulates a mobile device)." }, "landscape": { "type": "boolean", "default": false, "description": "Set to true for landscape viewport orientation." }, "full_page": { "type": "boolean", "default": false, "description": "When true, captures the full scrollable page rather than just the visible viewport." }, "test": { "type": "boolean", "default": false, "description": "Create a test image that does not consume production credits. The image will have a 'sample' watermark." }, "encode": { "type": "boolean", "default": false, "description": "Return the image as a base64 encoded string. Images over 4MB cannot be returned as base64 — a URL will be returned instead." }, "webhook": { "type": "string", "format": "uri", "description": "A valid URL to receive a POST request with the result once the image has been generated. Your endpoint must return a 200 status code." }, "quality": { "type": "number", "minimum": 1, "maximum": 3, "default": 1, "description": "A float value between 1 and 3. Higher values produce better quality but larger file sizes." }, "clip": { "type": "object", "description": "Defines a clipping region of the page to capture.", "required": [ "x", "y", "width", "height" ], "properties": { "x": { "type": "number", "minimum": 0, "description": "X-coordinate of the top-left corner of the clip area." }, "y": { "type": "number", "minimum": 0, "description": "Y-coordinate of the top-left corner of the clip area." }, "width": { "type": "number", "minimum": 1, "description": "Width of the clipping area." }, "height": { "type": "number", "minimum": 1, "description": "Height of the clipping area." }, "unit": { "$ref": "#/components/schemas/Unit" } }, "additionalProperties": false }, "grayscale": { "type": "boolean", "default": false, "description": "Generate the image in grayscale." }, "css": { "type": "string", "description": "A valid URL pointing to a CSS file or a CSS string to inject before generation. If a URL, it must be publicly accessible." }, "delay": { "type": "integer", "minimum": 100, "maximum": 9000, "description": "Delay in milliseconds before capturing the page." }, "accept_cookie_warning": { "type": "boolean", "default": true, "description": "Attempt to automatically accept cookie consent notifications before generating the image. See click_elements for manual targeting." }, "click_elements": { "type": "array", "items": { "type": "string" }, "description": "Click button or link elements before generation. Specify elements by CSS class name or text value, e.g. [\"Accept\", \".cookie-btn\"]." }, "name": { "type": "string", "default": "Untitled Document", "description": "A descriptive name for your image, visible in the dashboard." }, "auth": { "$ref": "#/components/schemas/BasicAuthOptions" }, "email": { "$ref": "#/components/schemas/EmailOptions" }, "s3": { "$ref": "#/components/schemas/S3Options" } }, "additionalProperties": false }, "WriteRequest": { "type": "object", "required": [ "source" ], "properties": { "source": { "type": "string", "description": "A URL pointing to an existing PDF, or a base64-encoded PDF string." }, "encoding": { "type": "string", "enum": [ "utf8", "windows-1252", "cp1252" ], "description": "Text encoding to use when writing." }, "text": { "type": "array", "description": "One or more text strings to add to the PDF.", "items": { "$ref": "#/components/schemas/WriteTextItem" } }, "cells": { "type": "array", "description": "One or more text cells that support line breaks and alignment.", "items": { "$ref": "#/components/schemas/WriteCellItem" } }, "images": { "type": "array", "description": "One or more images to add to the PDF.", "items": { "$ref": "#/components/schemas/WriteImageItem" } }, "barcodes": { "type": "array", "description": "One or more barcodes to add to the PDF.", "items": { "$ref": "#/components/schemas/WriteBarcodeItem" } }, "qr_codes": { "type": "array", "description": "One or more QR codes to add to the PDF.", "items": { "$ref": "#/components/schemas/WriteQrCodeItem" } }, "test": { "type": "boolean", "default": false, "description": "Create a test document that does not consume production credits. The document will have a 'sample' watermark." }, "encode": { "type": "boolean", "default": false, "description": "Return the document as a base64 encoded string. Documents over 4MB cannot be returned as base64 — a URL will be returned instead." }, "webhook": { "type": "string", "format": "uri", "description": "A valid URL to receive a POST request with the result. Your endpoint must return a 200 status code." }, "page_numbers": { "type": "boolean", "default": false, "description": "Insert page numbers into the footer of each page." }, "name": { "type": "string", "default": "Untitled Document", "description": "A descriptive name for your document, visible in the dashboard." }, "email": { "$ref": "#/components/schemas/EmailOptions" }, "s3": { "$ref": "#/components/schemas/S3Options" } }, "additionalProperties": false }, "WriteTextItem": { "type": "object", "properties": { "text_value": { "type": "string", "minLength": 1, "description": "The text string to write to the PDF." }, "text_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "Hex color code for the text, e.g. #cb4335." }, "font": { "type": "string", "description": "Font family. Supports: Arial, Courier, Helvetica, Times, PassionsConflict, ArchivoBlack. Defaults to Arial." }, "font_size": { "type": "number", "minimum": 0, "maximum": 200, "default": 11, "description": "Font size in points." }, "font_style": { "type": "string", "pattern": "^[bBiIuU]{1,3}$", "maxLength": 3, "description": "Font style flags: B (bold), I (italic), U (underline). Combine as needed, e.g. 'BUI'." }, "text_x": { "type": "number", "minimum": 0, "maximum": 9999, "description": "X coordinate for the text position in mm." }, "text_y": { "type": "number", "minimum": 0, "maximum": 9999, "description": "Y coordinate for the text position in mm." }, "text_page_number": { "type": "integer", "minimum": 0, "maximum": 999, "description": "Page number to write the text to. If omitted, text is written to all pages." } }, "additionalProperties": false }, "WriteCellItem": { "type": "object", "required": [ "height" ], "properties": { "width": { "type": "number", "minimum": 0, "maximum": 9999, "description": "Cell width. Defaults to the right margin of the page." }, "height": { "type": "number", "minimum": 0, "maximum": 9999, "description": "Cell height (required)." }, "align": { "type": "string", "enum": [ "L", "C", "R", "J", "l", "c", "r", "j" ], "default": "J", "description": "Text alignment: L (left), C (center), R (right), J (justified)." }, "text_value": { "type": "string", "minLength": 1, "description": "The text string to write. Supports line breaks with \\n." }, "text_color": { "type": "string", "pattern": "^#[0-9A-Fa-f]{6}$", "description": "Hex color code for the text, e.g. #cb4335." }, "font": { "type": "string", "description": "Font family. Supports: Arial, Courier, Helvetica, Times, PassionsConflict, ArchivoBlack. Defaults to Arial." }, "font_size": { "type": "number", "minimum": 0, "maximum": 200, "default": 11, "description": "Font size in points." }, "font_style": { "type": "string", "pattern": "^[bBiIuU]{1,3}$", "maxLength": 3, "description": "Font style flags: B (bold), I (italic), U (underline). Combine as needed, e.g. 'BUI'." }, "border": { "type": "number", "minimum": 0, "maximum": 10, "description": "Cell border thickness, e.g. 0.5." }, "cell_x": { "type": "number", "minimum": 0, "maximum": 9999, "description": "X coordinate for the cell position in mm." }, "cell_y": { "type": "number", "minimum": 0, "maximum": 9999, "description": "Y coordinate for the cell position in mm." }, "cell_page_number": { "type": "integer", "minimum": 0, "maximum": 999, "description": "Page number to add the cell to. If omitted, the cell is added to all pages." } }, "additionalProperties": false }, "WriteImageItem": { "type": "object", "properties": { "image_url": { "type": "string", "format": "uri", "description": "URL of the image to embed in the PDF. Must be publicly accessible." }, "image_width": { "type": "number", "description": "Width of the image in mm." }, "image_height": { "type": "number", "description": "Height of the image in mm." }, "image_x": { "type": "number", "minimum": 0, "maximum": 9999, "description": "X coordinate for the image position in mm." }, "image_y": { "type": "number", "minimum": 0, "maximum": 9999, "description": "Y coordinate for the image position in mm." }, "image_page_number": { "type": "integer", "minimum": 0, "maximum": 999, "description": "Page number to add the image to. If omitted, the image is added to all pages." } }, "additionalProperties": false }, "WriteBarcodeItem": { "type": "object", "properties": { "barcode_value": { "type": "string", "description": "The string value to encode in the barcode, e.g. '901193283'." }, "barcode_width": { "type": "number", "description": "Width of the barcode in mm." }, "barcode_height": { "type": "number", "description": "Height of the barcode in mm." }, "barcode_x": { "type": "number", "minimum": 0, "maximum": 9999, "description": "X coordinate for the barcode position in mm." }, "barcode_y": { "type": "number", "minimum": 0, "maximum": 9999, "description": "Y coordinate for the barcode position in mm." }, "barcode_page_number": { "type": "integer", "minimum": 0, "maximum": 999, "description": "Page number to add the barcode to. If omitted, the barcode is added to all pages." } }, "additionalProperties": false }, "WriteQrCodeItem": { "type": "object", "properties": { "qr_code_value": { "type": "string", "description": "The string value to encode in the QR code, e.g. 'https://google.com'." }, "qr_code_size": { "type": "number", "description": "Size of the QR code in mm." }, "qr_code_x": { "type": "number", "minimum": 0, "maximum": 9999, "description": "X coordinate for the QR code position in mm." }, "qr_code_y": { "type": "number", "minimum": 0, "maximum": 9999, "description": "Y coordinate for the QR code position in mm." }, "qr_code_page_number": { "type": "integer", "minimum": 0, "maximum": 999, "description": "Page number to add the QR code to. If omitted, the QR code is added to all pages." } }, "additionalProperties": false }, "MergeRequest": { "type": "object", "required": [ "files" ], "properties": { "files": { "type": "array", "minItems": 2, "maxItems": 100, "items": { "type": "string", "description": "A URL pointing to a PDF or a base64-encoded PDF string." }, "description": "An array of PDF URLs or base64 strings to merge. Minimum 2 files required." }, "test": { "type": "boolean", "default": false, "description": "Create a test document that does not consume production credits. The document will have a 'sample' watermark." }, "encode": { "type": "boolean", "default": false, "description": "Return the document as a base64 encoded string. Documents over 4MB cannot be returned as base64 — a URL will be returned instead." }, "webhook": { "type": "string", "format": "uri", "description": "A valid URL to receive a POST request with the result. Your endpoint must return a 200 status code." }, "name": { "type": "string", "default": "Untitled Document", "description": "A descriptive name for your document, visible in the dashboard." }, "email": { "$ref": "#/components/schemas/EmailOptions" }, "s3": { "$ref": "#/components/schemas/S3Options" } }, "additionalProperties": false }, "EncryptRequest": { "type": "object", "required": [ "source", "password" ], "properties": { "source": { "type": "string", "description": "A URL pointing to an existing PDF, or a base64-encoded PDF string." }, "password": { "type": "string", "maxLength": 60, "description": "The password to set on the PDF. When test is true, the password is always 'docamatic_sample'." }, "encryption": { "type": "string", "enum": [ "AES_128", "aes_128", "AES_256", "aes_256" ], "default": "AES_256", "description": "Encryption strength. AES_128 requires Acrobat 7+; AES_256 requires Acrobat X+." }, "test": { "type": "boolean", "default": false, "description": "Create a test document that does not consume production credits. Password will always be 'docamatic_sample'." }, "encode": { "type": "boolean", "default": false, "description": "Return the document as a base64 encoded string. Documents over 4MB cannot be returned as base64 — a URL will be returned instead." }, "webhook": { "type": "string", "format": "uri", "description": "A valid URL to receive a POST request with the result. Your endpoint must return a 200 status code." }, "name": { "type": "string", "default": "Untitled Document", "description": "A descriptive name for your document, visible in the dashboard." }, "email": { "$ref": "#/components/schemas/EmailOptions" }, "s3": { "$ref": "#/components/schemas/S3Options" } }, "additionalProperties": false }, "DeleteRequest": { "type": "object", "required": [ "transaction_id" ], "properties": { "transaction_id": { "type": "string", "format": "uuid", "description": "The transaction_id returned when the document was generated." } }, "additionalProperties": false }, "DocumentResponse": { "type": "object", "properties": { "success": { "type": "boolean", "description": "Whether the request was successful." }, "document": { "type": "string", "description": "A URL to the generated document, or a base64-encoded string if encode was true." }, "size": { "type": "string", "description": "Human-readable file size of the generated document, e.g. '85.79 KB'." }, "transaction_id": { "type": "string", "description": "Unique identifier for the transaction. Used to delete the document or locate it in the dashboard." }, "message": { "type": "string" }, "url": { "type": "string", "format": "uri" } }, "additionalProperties": true }, "DeleteResponse": { "type": "object", "required": [ "message", "success" ], "properties": { "message": { "type": "string", "example": "Delete successful" }, "url": { "type": "string", "format": "uri", "nullable": true, "description": "URL of the document that was deleted." }, "success": { "type": "boolean" } }, "additionalProperties": false }, "CreditsResponse": { "type": "object", "description": "Summary of API usage for the current billing period.", "properties": { "production": { "type": "object", "description": "Production credit usage.", "properties": { "limit": { "type": "integer", "description": "Total production credits available in the billing period." }, "used": { "type": "integer", "description": "Production credits consumed so far." }, "remaining": { "type": "integer", "description": "Production credits remaining." } }, "additionalProperties": false }, "test": { "type": "object", "description": "Test credit usage.", "properties": { "limit": { "type": "integer", "description": "Total test credits available in the billing period." }, "used": { "type": "integer", "description": "Test credits consumed so far." }, "remaining": { "type": "integer", "description": "Test credits remaining." } }, "additionalProperties": false }, "period_start": { "type": "string", "description": "Start of the current billing period (YYYY-MM-DD HH:MM:SS).", "example": "2019-12-30 00:00:00" }, "period_end": { "type": "string", "description": "End of the current billing period (YYYY-MM-DD HH:MM:SS).", "example": "2020-01-30 23:59:59" } }, "additionalProperties": true }, "MeResponse": { "type": "object", "required": [ "name", "email", "plan", "subscribed", "limit" ], "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "plan": { "type": "string" }, "subscribed": { "type": "boolean" }, "limit": { "type": "integer" } }, "additionalProperties": false }, "DocumentItem": { "type": "object", "properties": { "id": { "type": "integer" }, "transaction_id": { "type": "string" }, "endpoint": { "type": "string" }, "document": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "additionalProperties": true }, "TemplateItem": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" } }, "additionalProperties": true }, "ErrorResponse": { "type": "object", "properties": { "message": { "type": "string" } }, "additionalProperties": true }, "ValidationError": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "Human-readable summary of the validation failure." }, "errors": { "type": "object", "description": "Field-level error details.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "additionalProperties": true } } } }