Skip to main content

cURL Examples

Quick cURL examples for testing the DocGenLab API.

Authentication​

All requests require an API key in the X-API-Key header:

export API_KEY="dgl_your_api_key_here"
export BASE_URL="https://api.docgenlab.com/api/v1"

Templates​

List Templates​

curl -X GET "$BASE_URL/templates/?is_uat=false" \
  -H "X-API-Key: $API_KEY"

Get Template​

curl -X GET "$BASE_URL/templates/TEMPLATE_ID" \
  -H "X-API-Key: $API_KEY"

Create HTML Template​

curl -X POST "$BASE_URL/templates/" \
  -H "X-API-Key: $API_KEY" \
  -F "name=Email Template" \
  -F "html_content=<html><body><h1>{{title}}</h1><p>{{content}}</p></body></html>" \
  -F "description=Marketing email template" \
  -F "is_uat=false"

Create DOCX Template​

curl -X POST "$BASE_URL/templates/" \
  -H "X-API-Key: $API_KEY" \
  -F "name=Invoice Template" \
  -F "file=@/path/to/template.docx" \
  -F "is_uat=false"

Documents​

Generate Document​

curl -X POST "$BASE_URL/documents/" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "TEMPLATE_UUID",
    "input_json": {
      "customer_name": "John Doe",
      "invoice_number": "INV-001",
      "amount": 1250.00,
      "due_date": "2024-02-15"
    },
    "output_format": "pdf"
  }'

Response:

{
  "id": "abc-123-def-456",
  "template_id": "TEMPLATE_UUID",
  "status": "queued",
  "created_at": "2024-01-15T10:30:00Z"
}

Get Document Status​

curl -X GET "$BASE_URL/documents/DOCUMENT_ID" \
  -H "X-API-Key: $API_KEY"

Response:

{
  "id": "abc-123-def-456",
  "status": "ready",
  "output_pdf_path": "gs://bucket/path/to/doc.pdf",
  "created_at": "2024-01-15T10:30:00Z"
}

Download Document​

curl -X GET "$BASE_URL/documents/DOCUMENT_ID/download?format=pdf" \
  -H "X-API-Key: $API_KEY" \
  -o invoice.pdf

Complete Workflow​

Generate and Download​

#!/bin/bash

# 1. Generate document
DOC_ID=$(curl -s -X POST "$BASE_URL/documents/" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_id": "TEMPLATE_UUID",
    "input_json": {"name": "John Doe"},
    "output_format": "pdf"
  }' | jq -r '.id')

echo "Document ID: $DOC_ID"

# 2. Poll until ready
while true; do
  STATUS=$(curl -s -X GET "$BASE_URL/documents/$DOC_ID" \
    -H "X-API-Key: $API_KEY" | jq -r '.status')
  
  echo "Status: $STATUS"
  
  if [ "$STATUS" = "ready" ]; then
    break
  elif [ "$STATUS" = "failed" ]; then
    echo "Generation failed"
    exit 1
  fi
  
  sleep 2
done

# 3. Download
curl -X GET "$BASE_URL/documents/$DOC_ID/download" \
  -H "X-API-Key: $API_KEY" \
  -o "document_$DOC_ID.pdf"

echo "Downloaded: document_$DOC_ID.pdf"

Error Handling​

Rate Limit (429)​

curl -X POST "$BASE_URL/documents/" \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"template_id": "xxx", "input_json": {}}'

Response (429):

{
  "detail": "Rate limit exceeded. Try again in 30 seconds."
}

Invalid Template (404)​

curl -X GET "$BASE_URL/templates/invalid-id" \
  -H "X-API-Key: $API_KEY"

Response (404):

{
  "detail": "Template not found"
}

Unauthorized (401)​

curl -X GET "$BASE_URL/templates/" \
  -H "X-API-Key: invalid_key"

Response (401):

{
  "detail": "Invalid API Key"
}

Testing with jq​

Pretty print JSON responses:

curl -s -X GET "$BASE_URL/templates/" \
  -H "X-API-Key: $API_KEY" \
  | jq '.'

Extract specific fields:

# Get all template names
curl -s -X GET "$BASE_URL/templates/" \
  -H "X-API-Key: $API_KEY" \
  | jq '.[].name'

# Get document status
curl -s -X GET "$BASE_URL/documents/DOCUMENT_ID" \
  -H "X-API-Key: $API_KEY" \
  | jq '.status'

Next Steps​