API Documentation

Everything you need to integrate document generation

Overview

The BuildDocs API generates documents programmatically from your templates. It uses asynchronous processing: you submit a request and receive a job ID, then poll for status until ready.

Base URL

https://api.builddocs.io

Workflow

1. Generate

2. Poll Status

3. Download

Authentication

All requests require an API key in the Authorization header.

Key Format

sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Required Header

Authorization: Bearer sk_live_your_api_key

⚠️ Keep it secret! Never expose your API key in client-side code.

Generate Document

POST/v1/generate-document

Start a generation job. Returns immediately with a job ID.

Response

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "message": "Document generation started"
}

cURL Example

curl -X POST "https://api.builddocs.io/v1/generate-document" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "da0f993f-8e0c-4f21-89fb-b53e3942b84b",
    "data": {
      "name": "Sarah Jenkins",
      "date": "December 25, 2025",
      "title": "Certificate of Achievement"
    }
  }'

Document Status

GET/v1/document-status/{job_id}

Check job status. Poll until 'completed' or 'failed'.

States

Completed

{
  "status": "completed",
  "download_url": "https://storage.example.com/..."
}

Error Codes

Status	Code	Description
`400`	`BAD_REQUEST`	Invalid request or missing parameters
`401`	`UNAUTHORIZED`	Invalid or missing API key
`404`	`NOT_FOUND`	Template or job not found
`429`	`LIMIT_EXCEEDED`	Monthly quota exceeded
`500`	`INTERNAL_ERROR`	Internal server error

Rate Limits & Quotas

Generation is limited based on your plan. Quota resets monthly.

Plan	Monthly Quota
Developer	50 documents/month
Pro	5,000 documents/month
Enterprise	Custom

🚫 Quota Exceeded When you exceed your quota, the API returns a 429 status. Upgrade your plan or wait.

Code Examples

cURL

curl -X POST "https://api.builddocs.io/v1/generate-document" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "da0f993f-8e0c-4f21-89fb-b53e3942b84b",
    "data": {
      "name": "Sarah Jenkins",
      "date": "December 25, 2025",
      "title": "Certificate of Achievement"
    }
  }'

JavaScript

const response = await fetch("https://api.builddocs.io/v1/generate-document", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_live_your_api_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    template_id: "da0f993f-8e0c-4f21-89fb-b53e3942b84b",
    data: { name: "Sarah Jenkins", ... }
  })
});

const { job_id } = await response.json();

// Poll for status
const checkStatus = async () => {
  const res = await fetch(`https://api.builddocs.io/v1/document-status/${job_id}`, {
    headers: { "Authorization": "Bearer sk_live_your_api_key" }
  });
  return res.json();
};

Python

import requests

response = requests.post(
    "https://api.builddocs.io/v1/generate-document",
    headers={
        "Authorization": "Bearer sk_live_your_api_key",
        "Content-Type": "application/json"
    },
    json={
        "template_id": "da0f993f-8e0c-4f21-89fb-b53e3942b84b",
        "data": {"name": "Sarah Jenkins", ...}
    }
)

job_id = response.json()["job_id"]

# Check status
status_response = requests.get(
    f"https://api.builddocs.io/v1/document-status/{job_id}",
    headers={"Authorization": "Bearer sk_live_your_api_key"}
)