Outfiles.io Public API Documentation

Introduction

Outfiles.io is a cloud-based document generation platform that allows developers to create PDF documents from custom templates through a simple RESTful API. With Outfiles.io, you can programmatically generate invoices, reports, certificates, and more – all by merging your data with pre-designed templates. This saves development time and ensures professional, consistent output. The API is designed to be easy to integrate (in the spirit of Stripe's developer-friendly docs) and scalable for both startups and enterprise use. In this guide, we'll cover the public API endpoints, how to authenticate, and provide examples to get you started.

API Overview and Base URL

All API requests are made to the base URL:https://api.outfiles.io/v1/. This is the root endpoint for version 1 of the Outfiles API. All endpoints described below should be prefixed with this base URL. For example, a request to the /generate/:id endpoint will be made to https://api.outfiles.io/v1/generate/:id. The API accepts and returns JSON in request and response bodies.

Base URL: https://api.outfiles.io/v1/
Content Type: Use application/json for request bodies and expect JSON responses (except where noted otherwise).
API Versioning: The current version is v1 (included in the URL). Future versions may be released with different base paths.

Authentication (API Keys)

Outfiles.io uses API keys to authenticate requests. You must include your API key in every API call to access protected endpoints. API keys are provided via the Authorization HTTP header using the Bearer token scheme:

Authorization: Bearer YOUR_API_KEY

Your API key can be obtained from your Outfiles.io dashboard (ensure you keep it secret). The API will reject requests without a valid Authorization header. In particular, if the header is missing or the key is invalid/revoked, the request will be denied with an HTTP 401 Unauthorized error. Make sure to include the "Bearer " prefix followed by your API key string, as shown above.

Example: If your API key is abcd1234, you would set Authorization: Bearer abcd1234 in the request headers. The server will extract the key from the header and validate it before processing your request.

Rate Limiting

To ensure fair use of resources, the Outfiles API enforces rate limiting on API key usage. Each API key is limited to 60 requests per minute. This means you can send up to 60 requests in a 60-second window per API key. Exceeding this limit will result in a 429 Too Many Requests response. The limit is applied per API key (not per IP address), so sharing an API key across multiple clients will aggregate their usage. If you need a higher rate limit, consider contacting support or upgrading your plan.

Note: The rate limit resets every 60 seconds (1 minute). If you hit the limit, simply wait for a short time before retrying. Designing your integration to handle HTTP 429 responses (e.g., with exponential backoff or queued requests) is recommended for robustness.

Endpoints

Below are the public API endpoints that use API Key authentication. All these endpoints require the Authorization: Bearer <API_KEY> header and will reject unauthorized requests. The endpoints follow a RESTful style and return JSON responses. In the descriptions, replace {templateId} and {documentId} with actual IDs from your Outfiles.io account.

1. Create a Document (Generate PDF)

Endpoint: POST /generate/{templateId}

Description: Initiates the generation of a new PDF document from a specified template, using the data you provide. This is an asynchronous operation – it will return immediately with a status and a document ID, while the document is generated in the background.

Required: An API key (in the header) with access to the template's workspace. The {templateId} in the URL path identifies which template to use for generation. You must have created this template in Outfiles.io beforehand (via the web interface or appropriate API, if available) and the API key's account must have access to it.

Try it out

Request Parameters:

Path Parameter: templateId – The ID of the template you want to use for generation. This is typically a string or UUID that uniquely identifies a template in your Outfiles.io account. *(Example: tmpl_1234567890)*
Body: JSON object with the following fields:
- data – An object containing key-value pairs of the dynamic content to insert into the template. The keys should match the placeholders or variables defined in your template. The structure of this object depends on your template. For example, if your template expects a customer name and items list, your data might look like: {"customerName": "John Doe", "items": [{...}, {...}]}. This data object is passed to the generation engine to produce the PDF content.

Example Request (cURL):

curl -X POST "https://api.outfiles.io/v1/generate/<<TEMPLATE_ID>>" \
     -H "Authorization: Bearer <<YOUR_API_KEY>>" \
     -H "Content-Type: application/json" \
     -d '{
           "data": {
             "customerName": "John Doe",
             "items": [
                { "description": "Product 1", "price": 19.99 },
                { "description": "Product 2", "price": 29.99 }
             ]
           }
         }'

Replace <<TEMPLATE_ID>> with your actual template ID, and <<YOUR_API_KEY>> with your API key.

In the above example, the request tells Outfiles.io to generate a document using the template identified by <<TEMPLATE_ID>>, filling in the placeholder values (like customerName and items) with the provided JSON data.

Response:
On success, this endpoint returns a JSON response containing a generation status and a document identifier. For example:

{
  "status": "waiting",
  "documentId": "doc_9876543210"
}

status – The status of the generation request. Initially, this will be "waiting" (or "in_progress") indicating that the document is being generated asynchronously. The status "completed" means the document has been generated successfully, and "failed" indicates there was an error during generation. In this immediate response, you will typically see "waiting" since the generation just started. (The status may transition to "completed" in the background once finished.)
documentId – A unique ID representing the generated document request. You will use this ID to retrieve the actual PDF file once it's ready. This ID is required for the download step (see the Retrieve Download URL endpoint below).

If the generation request cannot be queued or processed, the API will return a "failed" status instead of "waiting". For instance, if the templateId is invalid, if your API key doesn't have access to that template's workspace, or if you have exceeded your plan's generation limits, you may get a response like:

{ 
  "status": "failed" 
}

In such cases, documentId will not be present (the generation did not start). A status of "failed" at this stage means the request was not accepted for processing. You should check that your template ID is correct, your account is allowed to generate a document (e.g., within plan limits), and that your API key is valid for that template's workspace. The API will not elaborate the reason in this response for security, so use your Outfiles.io dashboard or logs for more details if needed.

Notes: After you receive a successful response with "status": "waiting", the document is being generated in the background. Actual PDF generation time can vary (typically a few seconds, depending on complexity and size). You do not get an automatic callback when it's done (unless you have set up webhooks in Outfiles.io separately). The next step is to retrieve the download URL for the generated PDF using the documentId. You might poll for the document's completion by attempting to get the download URL after a short delay or listen to a webhook if configured.

2. Retrieve Download URL (Get Generated PDF)

Endpoint: GET /generate/download-url/{documentId}

Description: Retrieves a one-time download URL for the PDF document that was generated. This URL is a pre-signed link to the PDF file, which can be used to download the actual document. The link is time-limited and will expire after 24 hours for security. This endpoint should be called after initiating document generation (using the document ID returned from the create call).

Required: A valid API key (in the header), and the {documentId} must correspond to a document generated by an API key belonging to your account. In other words, you can only retrieve URLs for documents you requested. The same API key used to generate the document should be used to fetch its download URL.

Try it out

Request Parameters:

Path Parameter: documentId – The ID of the document whose PDF you want to download. This is the documentId returned by the POST /generate call. *(Example: doc_9876543210)*
Headers: As with all protected endpoints, include the Authorization: Bearer <API_KEY> header. No request body is needed for this GET request.

Example Request (cURL):

curl -X GET "https://api.outfiles.io/v1/generate/download-url/<<DOCUMENT_ID>>" \
     -H "Authorization: Bearer <<YOUR_API_KEY>>"

Replace <<DOCUMENT_ID>> with the ID you received from the generation step, and use the same API key.

Response:
On success, this endpoint returns a URL (as a string) that you can use to download the PDF file. The response is typically a JSON string, which is the direct URL. For example:

"https://outfiles-prod.s3.amazonaws.com/abcd1234/efgh5678?AWSAccessKeyId=...&Signature=...&Expires=1699999999"

*(The above is a simplified example of a pre-signed URL; the actual URL will be a long string containing authentication tokens and an expiry timestamp.)*

This URL is a pre-signed download link to the PDF file stored on Outfiles.io's storage (for instance, an Amazon S3 bucket). It is valid for approximately 24 hours after generation. You can use this URL to directly download the PDF via a browser or HTTP client. Note: The URL will expire after its validity period (24 hours), after which you will need to request a new download URL if you still need to fetch the document.

To retrieve the PDF, you can perform an HTTP GET on the returned URL (no authentication needed for that S3 link itself). The PDF content will be returned as a binary stream. For example, you could paste the URL in a browser to view or download the PDF, or use curl to download it:

curl -L -o output.pdf "https://outfiles-prod.s3.amazonaws.com/....<signature>...."

The -L option instructs curl to follow any redirects (if any), and -o output.pdf saves the file locally.

Important: If the document is still being generated when you call this endpoint, or if an invalid documentId is used, the API will respond with an error. Specifically, if the document isn't ready or the ID is wrong/unauthorized, you will receive a 404 Not Found error. The API distinguishes "not found or not accessible" cases and will return a 404 status in those scenarios. This could mean either the document ID is incorrect, or the document isn't yet available for your API key (still processing or belongs to a different workspace). In practice, calling this endpoint too quickly may result in a 404 if the PDF is not finished generating. If that happens, wait a few seconds and try again. There is no need to call this repeatedly in a tight loop; a short delay (a few seconds) between retries is sufficient in most cases.
Once the document is successfully generated, this endpoint will return the URL as described. Use the URL promptly, as it will expire. If it expires, you can call the same GET endpoint again to obtain a new fresh URL (as long as the document is still stored).

Additional Information

Template Design & Data: The quality and correctness of the generated PDF depend on the template design and the data you provide. Templates are typically created in the Outfiles.io web interface, where you define the layout (using HTML/CSS and templating syntax such as Liquid) and placeholders for dynamic data. Ensure that your data JSON structure matches what the template expects (keys and data types). Any mismatch could result in an incomplete document or template errors (which may manifest as "failed" status). At this time, the public API focuses on the generation and retrieval of documents. Template creation and management is handled through the Outfiles dashboard (or future admin APIs).
Error Handling: Besides authentication errors (401) and rate limiting (429) mentioned earlier, the main errors you may encounter are:
- 404 Not Found: Returned by the download URL endpoint if the document cannot be found or accessed (e.g., wrong ID or not yet ready). Also returned if you use a templateId or documentId that doesn't exist or belong to you.
- 400 Bad Request: If your request payload is malformed JSON or missing required fields, the API may return a 400. For instance, forgetting to include the data object in the generate call could result in a validation error. Always ensure your JSON is correctly formatted.
- 401 Unauthorized: If the API key is missing or invalid, as described, or if the API key doesn't have access to the resource (e.g., you used a templateId from another workspace), you will get a 401. Make sure you're using the correct key and that it has the proper permissions.
- 500 Internal Server Error: Though rare, this could indicate an unexpected problem on the Outfiles.io side. If you encounter a 5xx error, you might retry after some time. If it persists, contact Outfiles.io support.
Webhook Notifications: If you have a large volume of documents or need to automate post-generation processing, consider using Outfiles.io's webhook feature (if available) to get notified when a document is generated. Webhooks can eliminate the need for polling. (Check the Outfiles.io documentation or dashboard for webhook setup – this may be outside the scope of the public API endpoints but is worth mentioning for completeness.)
SDKs and Libraries: Outfiles.io may provide client libraries or SDKs in various languages to simplify integration. Using an SDK (if available for your language) can handle a lot of the above steps (authentication, waiting for completion, etc.) behind the scenes. Check the official Outfiles.io docs or GitHub for any available SDKs that match the Stripe-like developer experience.

Conclusion

The Outfiles.io public API allows you to generate and retrieve PDF documents seamlessly, using API keys for secure access and a straightforward two-step process (request generation, then fetch the file URL). With a robust templating system and a focus on developer experience, Outfiles.io aims to streamline document generation for your applications. By following this documentation and the examples, you can integrate Outfiles.io into your project to create invoices, reports, certificates, or any other PDF documents on-the-fly – saving time and providing a professional output to your end-users.

For more details, best practices, and advanced usage (such as managing templates, webhooks, or handling large batches), refer to the official Outfiles.io documentation and support channels. Happy coding!