Public v1 API

Build on the same tools

Every browser tool is a conversion type. Create an API key, upload with a presigned PUT, then POST /conversions with that type. Poll until the job completes and download the output file.

Create an API key Developer pricing

Base URL: https://api.sohappypdf.com/v1

OpenAPI: https://api.sohappypdf.com/v1/openapi.json

Quickstart

Create a key in Account → API. It is shown only once.
Send Authorization: Bearer YOUR_API_KEY on every request. Never put the key in a URL or browser code.
POST /files/upload, PUT the bytes to upload.url, then POST /files/{id}/complete.
POST /conversions with sourceFileId, targetFormat, and type. Use the tool id as type.
Poll GET /conversions/{id} every two seconds until completed, then POST /files/{outputFileId}/download.

1. Create upload

curl -X POST https://api.sohappypdf.com/v1/files/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"report.pdf","contentType":"application/pdf","size":2048}'

2. PUT file bytes

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf

3. Complete upload

curl -X POST https://api.sohappypdf.com/v1/files/FILE_ID/complete \
  -H "Authorization: Bearer YOUR_API_KEY"

4. Create conversion

curl -X POST https://api.sohappypdf.com/v1/conversions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_IDEMPOTENCY_KEY" \
  -d '{"sourceFileId":"FILE_ID","targetFormat":"png","type":"pdf-to-png"}'

Authentication

Programmatic access uses API keys. Dashboard cookies are for the web app, not integrations.

HTTP

Authorization: Bearer YOUR_API_KEY

Send the key only in the Authorization header.
Treat the key as a secret. Do not commit it.
Do not ship keys in frontend JavaScript.
Delete a leaked key in the dashboard and create a replacement.

Files

Uploads are presigned. The API never holds the file bytes. Complete the upload before you create a conversion.

POST /files/upload → PUT → POST /files/{id}/complete

POST /files/upload
PUT  upload.url   (file bytes, not through the API)
POST /files/{id}/complete

Temporary files expire after about two hours. Presigned upload and download URLs expire after 15 minutes.

Conversions

POST /conversions returns 201 and enqueues a worker job. The type field is the tool id. Options go in options. Extra input files go in additionalFileIds, not inside the file bytes.

POST /conversions

curl -X POST https://api.sohappypdf.com/v1/conversions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_IDEMPOTENCY_KEY" \
  -d '{"sourceFileId":"FILE_ID","targetFormat":"png","type":"pdf-to-png"}'

Poll while status is pending, queued, processing. Stop on completed, failed, cancelled. When completed, conversion.outputFileId is set.

GET /conversions/{id}

curl https://api.sohappypdf.com/v1/conversions/CONVERSION_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /files/{outputFileId}/download

curl -X POST https://api.sohappypdf.com/v1/files/OUTPUT_FILE_ID/download \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /conversions/{id}/cancel

curl -X POST https://api.sohappypdf.com/v1/conversions/CONVERSION_ID/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"

Send Idempotency-Key (1–128 characters) on create. A replay with the same owner and key returns the original job and does not consume another credit.

Tools

Use the tool id as conversion type. The JSON below is the POST /conversions body. Credits come from the catalog. Planned tools are omitted until they ship.

37 tools

Merge PDF
Combine multiple PDF files into one document. Upload the files, set the order, and download a single PDF. No account needed for basic use.
Try in browser
type
merge-pdf
Input
pdf
Output
pdf
Credits
1 API credits
Files
21 files
Extra files
additionalFileIds required
- Pass extra uploads as additionalFileIds on the conversion, after each file is completed.
- Send type explicitly. The API will not infer this tool from formats alone.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "merge-pdf",
  "additionalFileIds": [
    "FILE_ID_2"
  ]
}
```
Split PDF
Split a PDF into a new file with only the pages you need. Select pages visually, then download the result.
Try in browser
type
split-pdf
Input
pdf
Output
pdf
Credits
1 API credits
Files
1 file
Extra files
Source file only
options
- ranges[{ start, end }, ...] 1-basedoptional
- Page numbers are 1-based.
- Range start and end are inclusive.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "split-pdf",
  "options": {
    "ranges": [
      {
        "start": 1,
        "end": 2
      }
    ]
  }
}
```
Extract PDF pages
Extract selected pages from a PDF and save them as a new file. Choose pages visually, then download.
Try in browser
type
extract-pages
Input
pdf
Output
pdf
Credits
1 API credits
Files
1 file
Extra files
Source file only
options
- ranges[{ start, end }, ...] 1-basedoptional
- Page numbers are 1-based.
- Range start and end are inclusive.
- Send type explicitly. The API will not infer this tool from formats alone.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "extract-pages",
  "options": {
    "ranges": [
      {
        "start": 1,
        "end": 3
      }
    ]
  }
}
```
Organize PDF
Rearrange, rotate, and manage PDF pages in one place, then download the updated file.
Try in browser
type
organize-pdf
Input
pdf
Output
pdf
Credits
1 API credits
Files
1 file
Extra files
Source file only
options
- ordernumber[] page orderrequired
- rotations0 | 90 | 180 | 270 per pageoptional
- Page numbers are 1-based.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "organize-pdf",
  "options": {
    "order": [
      2,
      1,
      3
    ]
  }
}
```
Remove PDF pages
Delete unwanted pages from a PDF and keep the rest in a new file.
Try in browser
type
remove-pages
Input
pdf
Output
pdf
Credits
1 API credits
Files
1 file
Extra files
Source file only
options
- pagesnumber[] 1-basedrequired
- Page numbers are 1-based.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "remove-pages",
  "options": {
    "pages": [
      2,
      4
    ]
  }
}
```
Reorder PDF pages
Change the page order of a PDF, then download the rearranged file.
Try in browser
type
reorder-pages
Input
pdf
Output
pdf
Credits
1 API credits
Files
1 file
Extra files
Source file only
options
- ordernumber[] 1-basedrequired
- Page numbers are 1-based.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "reorder-pages",
  "options": {
    "order": [
      3,
      1,
      2
    ]
  }
}
```
Rotate PDF
Rotate one or more pages in a PDF, then download the corrected file.
Try in browser
type
rotate-pdf
Input
pdf
Output
pdf
Credits
1 API credits
Files
1 file
Extra files
Source file only
options
- degrees90 | 180 | 270required
- pagesnumber[] 1-basedoptional
- Page numbers are 1-based.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "rotate-pdf",
  "options": {
    "degrees": 90
  }
}
```
Crop PDF
Crop page margins and extra space from a PDF, then download the result.
Try in browser
type
crop-pdf
Input
pdf
Output
pdf
Credits
2 API credits
Files
1 file
Extra files
Source file only
options
- marginTopnumber, default 0optional
- marginRightnumber, default 0optional
- marginBottomnumber, default 0optional
- marginLeftnumber, default 0optional
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "crop-pdf",
  "options": {
    "marginTop": 24,
    "marginRight": 24,
    "marginBottom": 24,
    "marginLeft": 24
  }
}
```
Compress PDF
Reduce PDF file size while keeping the document readable. Choose a compression level and download a smaller PDF.
Try in browser
type
compress-pdf
Input
pdf
Output
pdf
Credits
2 API credits
Files
1 file
Extra files
Source file only
options
- levellow | medium | highoptional
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "compress-pdf",
  "options": {
    "level": "medium"
  }
}
```
Repair PDF
Attempt to fix a damaged or unreadable PDF, then download a repaired copy.
Try in browser
type
repair-pdf
Input
pdf
Output
pdf
Credits
2 API credits
Files
1 file
Extra files
Source file only
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "repair-pdf"
}
```
PDF to PDF/A
Pro
Convert a PDF into an archival PDF/A file for longer-term storage.
Try in browser
type
pdf-to-pdfa
Input
pdf
Output
pdf
Credits
5 API credits
Files
1 file
Extra files
Source file only
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "pdf-to-pdfa"
}
```
PDF to Word
Convert a PDF into an editable Word document. Upload a PDF and download a DOC or DOCX file.
Try in browser
type
pdf-to-word
Input
pdf
Output
docx
Credits
5 API credits
Files
1 file
Extra files
Source file only
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "docx",
  "type": "pdf-to-word"
}
```
PDF to Word OCR
Pro
Convert a scanned PDF to Word with OCR so the text can be edited.
Try in browser
type
pdf-to-word-ocr
Input
pdf
Output
docx
Credits
12 API credits
Files
1 file
Extra files
Source file only
options
- languageOCR language coderequired
- Send type explicitly. The API will not infer this tool from formats alone.
- language is an OCR language code such as eng or tur.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "docx",
  "type": "pdf-to-word-ocr",
  "options": {
    "language": "eng"
  }
}
```
PDF to PowerPoint
Convert a PDF into a PowerPoint presentation you can edit and present.
Try in browser
type
pdf-to-powerpoint
Input
pdf
Output
pptx
Credits
5 API credits
Files
1 file
Extra files
Source file only
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pptx",
  "type": "pdf-to-powerpoint"
}
```
PDF to Excel
Convert tables in a PDF into an Excel spreadsheet you can sort and edit.
Try in browser
type
pdf-to-excel
Input
pdf
Output
xlsx
Credits
5 API credits
Files
1 file
Extra files
Source file only
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "xlsx",
  "type": "pdf-to-excel"
}
```
PDF to Excel OCR
Pro
Convert scanned PDF tables to Excel with OCR.
Try in browser
type
pdf-to-excel-ocr
Input
pdf
Output
xlsx
Credits
12 API credits
Files
1 file
Extra files
Source file only
options
- languageOCR language coderequired
- Send type explicitly. The API will not infer this tool from formats alone.
- language is an OCR language code such as eng or tur.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "xlsx",
  "type": "pdf-to-excel-ocr",
  "options": {
    "language": "eng"
  }
}
```
PDF to JPG
Convert PDF pages into JPG images you can save or share.
Try in browser
type
pdf-to-jpg
Input
pdf
Output
jpg
Credits
1 API credits
Files
1 file
Extra files
Source file only
options
- page1-based page numberoptional
- quality1-100optional
- dpi72-600optional
- Page numbers are 1-based.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "jpg",
  "type": "pdf-to-jpg",
  "options": {
    "page": 1,
    "dpi": 150
  }
}
```
PDF to PNG
Convert PDF pages into PNG images with a transparent or clean background.
Try in browser
type
pdf-to-png
Input
pdf
Output
png
Credits
1 API credits
Files
1 file
Extra files
Source file only
options
- page1-based page numberoptional
- quality1-100optional
- dpi72-600optional
- Page numbers are 1-based.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "png",
  "type": "pdf-to-png",
  "options": {
    "page": 1,
    "dpi": 150
  }
}
```
PDF to text
Extract plain text from a PDF and download it as a text file.
Try in browser
type
pdf-to-txt
Input
pdf
Output
txt
Credits
1 API credits
Files
1 file
Extra files
Source file only
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "txt",
  "type": "pdf-to-txt"
}
```
Word to PDF
Convert a Word document into a PDF you can share or print.
Try in browser
type
word-to-pdf
Input
doc, docx
Output
pdf
Credits
2 API credits
Files
1 file
Extra files
Source file only
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "word-to-pdf"
}
```
PowerPoint to PDF
Convert a PowerPoint presentation into a PDF.
Try in browser
type
powerpoint-to-pdf
Input
ppt, pptx
Output
pdf
Credits
2 API credits
Files
1 file
Extra files
Source file only
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "powerpoint-to-pdf"
}
```
Excel to PDF
Convert an Excel spreadsheet into a PDF.
Try in browser
type
excel-to-pdf
Input
xls, xlsx
Output
pdf
Credits
2 API credits
Files
1 file
Extra files
Source file only
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "excel-to-pdf"
}
```
JPG to PDF
Convert a JPG image into a PDF file.
Try in browser
type
jpg-to-pdf
Input
jpg
Output
pdf
Credits
1 API credits
Files
20 files
Extra files
Source file only
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "jpg-to-pdf"
}
```
PNG to PDF
Convert a PNG image into a PDF file.
Try in browser
type
png-to-pdf
Input
png
Output
pdf
Credits
1 API credits
Files
20 files
Extra files
Source file only
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "png-to-pdf"
}
```
Office to PDF
Convert Word, Excel, or PowerPoint files into PDF.
Try in browser
type
office-to-pdf
Input
doc, docx, ppt, pptx, xls, xlsx
Output
pdf
Credits
2 API credits
Files
1 file
Extra files
Source file only
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "office-to-pdf"
}
```
Edit PDF
Pro
Add text, highlights, shapes, and images on top of a PDF. Existing text stays as it is.
Try in browser
type
edit-pdf
Input
pdf
Output
pdf
Credits
5 API credits
Files
2 files
Extra files
additionalFileIds optional
options
- operationstext | rectangle | image overlaysrequired
- Page numbers are 1-based.
- Pass extra uploads as additionalFileIds on the conversion, after each file is completed.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "edit-pdf",
  "options": {
    "operations": [
      {
        "kind": "text",
        "page": 1,
        "x": 72,
        "y": 720,
        "text": "CONFIDENTIAL",
        "size": 14
      }
    ]
  }
}
```
Watermark PDF
Add a text or image watermark across every page of a PDF.
Try in browser
type
watermark-pdf
Input
pdf
Output
pdf
Credits
1 API credits
Files
1 file
Extra files
Source file only
options
- textstringrequired
- opacity0-1optional
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "watermark-pdf",
  "options": {
    "text": "DRAFT",
    "opacity": 0.25
  }
}
```
Add PDF page numbers
Add page numbers to a PDF, then download the numbered file.
Try in browser
type
page-numbers-pdf
Input
pdf
Output
pdf
Credits
1 API credits
Files
1 file
Extra files
Source file only
options
- startAtnumber, default 1optional
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "page-numbers-pdf",
  "options": {
    "startAt": 1
  }
}
```
Protect PDF
Add a password so others need it to open or use the PDF.
Try in browser
type
protect-pdf
Input
pdf
Output
pdf
Credits
2 API credits
Files
1 file
Extra files
Source file only
options
- passwordstringrequired
- Do not log passwords. Rotate them if a request is captured.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "protect-pdf",
  "options": {
    "password": "YOUR_PASSWORD"
  }
}
```
Unlock PDF
Remove password protection from a PDF you own, then download an unlocked copy.
Try in browser
type
unlock-pdf
Input
pdf
Output
pdf
Credits
2 API credits
Files
1 file
Extra files
Source file only
options
- passwordstringrequired
- Do not log passwords. Rotate them if a request is captured.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "unlock-pdf",
  "options": {
    "password": "YOUR_PASSWORD"
  }
}
```
Sign PDF
Pro
Add a visual signature image or text stamp. This is not a cryptographic digital signature.
Try in browser
type
sign-pdf
Input
pdf
Output
pdf
Credits
5 API credits
Files
2 files
Extra files
additionalFileIds optional
options
- page1-based page numberrequired
- xnumberrequired
- ynumberrequired
- widthnumberrequired
- heightnumberrequired
- textfallback stamp textoptional
- Page numbers are 1-based.
- This is a visual stamp, not a cryptographic digital signature.
- Pass extra uploads as additionalFileIds on the conversion, after each file is completed.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "sign-pdf",
  "options": {
    "page": 1,
    "x": 72,
    "y": 72,
    "width": 160,
    "height": 64,
    "text": "Signed"
  }
}
```
Redact PDF
Pro
Permanently black out sensitive text or areas in a PDF before you share it.
Try in browser
type
redact-pdf
Input
pdf
Output
pdf
Credits
6 API credits
Files
1 file
Extra files
Source file only
options
- regions[{ page, x, y, width, height }]required
- Page numbers are 1-based.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "redact-pdf",
  "options": {
    "regions": [
      {
        "page": 1,
        "x": 72,
        "y": 400,
        "width": 200,
        "height": 24
      }
    ]
  }
}
```
Compare PDF
Pro
Compare two PDF versions and see what changed.
Try in browser
type
compare-pdf
Input
pdf
Output
txt
Credits
5 API credits
Files
2 files
Extra files
additionalFileIds required
- Pass extra uploads as additionalFileIds on the conversion, after each file is completed.
- Send type explicitly. The API will not infer this tool from formats alone.
- Upload both PDFs, then pass the second id in additionalFileIds.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "txt",
  "type": "compare-pdf",
  "additionalFileIds": [
    "FILE_ID_2"
  ]
}
```
Scan to PDF
Pro
Turn scanned images into a single PDF.
Try in browser
type
scan-to-pdf
Input
jpg, png
Output
pdf
Credits
2 API credits
Files
50 files
Extra files
additionalFileIds optional
- Pass extra uploads as additionalFileIds on the conversion, after each file is completed.
- Send type explicitly. The API will not infer this tool from formats alone.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "scan-to-pdf",
  "additionalFileIds": [
    "FILE_ID_2"
  ]
}
```
Extract PDF content
Pro
Extract structured content from a PDF for reuse in other files.
Try in browser
type
pdf-extract
Input
pdf
Output
txt, json
Credits
12 API credits
Files
1 file
Extra files
Source file only
- Send type explicitly. The API will not infer this tool from formats alone.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "txt",
  "type": "pdf-extract"
}
```
PDF to Markdown
Pro
Convert PDF content into Markdown you can edit in a text editor.
Try in browser
type
pdf-to-markdown
Input
pdf
Output
md
Credits
5 API credits
Files
1 file
Extra files
Source file only
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "md",
  "type": "pdf-to-markdown"
}
```
OCR PDF
Pro
Make a scanned PDF searchable with OCR, or extract the recognized text.
Try in browser
type
ocr-pdf
Input
pdf
Output
pdf, txt
Credits
5 API credits
Files
1 file
Extra files
Source file only
options
- languageOCR language coderequired
- outputModepdf | txtrequired
- Send type explicitly. The API will not infer this tool from formats alone.
- language is an OCR language code such as eng or tur.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "ocr-pdf",
  "options": {
    "language": "eng",
    "outputMode": "pdf"
  }
}
```

Errors

Every error uses this envelope. Missing files and conversions both return NOT_FOUND. An expired owned file returns FILE_EXPIRED instead of 404.

JSON

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required",
    "requestId": "req_example"
  }
}

Code	HTTP
VALIDATION_ERROR	400
UNAUTHORIZED	401
FORBIDDEN	403
PLAN_LIMIT_REACHED	403
STORAGE_LIMIT_REACHED	403
API_KEY_LIMIT_REACHED	403
NOT_FOUND	404
CONFLICT	409
FILE_EXPIRED	410
FILE_TOO_LARGE	413
RATE_LIMITED	429
CONFIGURATION_ERROR	500
INTERNAL_ERROR	500

429 includes Retry-After, RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset. Wait, then retry. Do not tight-loop.

Limits and credits

API credits are separate from web tool credits. Rate limits follow the web plan. Hitting a quota returns 403 PLAN_LIMIT_REACHED.

Free: 5 conversions/day, 25 MB files, 30 API requests/minute.
Pro: unlimited conversions, 1 GB files, 60 API requests/minute.
Each conversion consumes the tool’s API credit cost. Accounts include 100 API credits each month; buy Developer packs from billing for more.
Webhooks are not available. Clients must poll.

Public v1 API

Build on the same tools

Every browser tool is a conversion type. Create an API key, upload with a presigned PUT, then POST /conversions with that type. Poll until the job completes and download the output file.

Create an API key Developer pricing

Base URL: https://api.sohappypdf.com/v1

OpenAPI: https://api.sohappypdf.com/v1/openapi.json

Quickstart

Create a key in Account → API. It is shown only once.
Send Authorization: Bearer YOUR_API_KEY on every request. Never put the key in a URL or browser code.
POST /files/upload, PUT the bytes to upload.url, then POST /files/{id}/complete.
POST /conversions with sourceFileId, targetFormat, and type. Use the tool id as type.
Poll GET /conversions/{id} every two seconds until completed, then POST /files/{outputFileId}/download.

1. Create upload

curl -X POST https://api.sohappypdf.com/v1/files/upload \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filename":"report.pdf","contentType":"application/pdf","size":2048}'

2. PUT file bytes

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf

3. Complete upload

curl -X POST https://api.sohappypdf.com/v1/files/FILE_ID/complete \
  -H "Authorization: Bearer YOUR_API_KEY"

4. Create conversion

curl -X POST https://api.sohappypdf.com/v1/conversions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_IDEMPOTENCY_KEY" \
  -d '{"sourceFileId":"FILE_ID","targetFormat":"png","type":"pdf-to-png"}'

Authentication

Programmatic access uses API keys. Dashboard cookies are for the web app, not integrations.

HTTP

Authorization: Bearer YOUR_API_KEY

Send the key only in the Authorization header.
Treat the key as a secret. Do not commit it.
Do not ship keys in frontend JavaScript.
Delete a leaked key in the dashboard and create a replacement.

Files

Uploads are presigned. The API never holds the file bytes. Complete the upload before you create a conversion.

POST /files/upload → PUT → POST /files/{id}/complete

POST /files/upload
PUT  upload.url   (file bytes, not through the API)
POST /files/{id}/complete

Temporary files expire after about two hours. Presigned upload and download URLs expire after 15 minutes.

Conversions

POST /conversions returns 201 and enqueues a worker job. The type field is the tool id. Options go in options. Extra input files go in additionalFileIds, not inside the file bytes.

POST /conversions

curl -X POST https://api.sohappypdf.com/v1/conversions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: YOUR_IDEMPOTENCY_KEY" \
  -d '{"sourceFileId":"FILE_ID","targetFormat":"png","type":"pdf-to-png"}'

Poll while status is pending, queued, processing. Stop on completed, failed, cancelled. When completed, conversion.outputFileId is set.

GET /conversions/{id}

curl https://api.sohappypdf.com/v1/conversions/CONVERSION_ID \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /files/{outputFileId}/download

curl -X POST https://api.sohappypdf.com/v1/files/OUTPUT_FILE_ID/download \
  -H "Authorization: Bearer YOUR_API_KEY"

POST /conversions/{id}/cancel

curl -X POST https://api.sohappypdf.com/v1/conversions/CONVERSION_ID/cancel \
  -H "Authorization: Bearer YOUR_API_KEY"

Send Idempotency-Key (1–128 characters) on create. A replay with the same owner and key returns the original job and does not consume another credit.

Tools

Use the tool id as conversion type. The JSON below is the POST /conversions body. Credits come from the catalog. Planned tools are omitted until they ship.

37 tools

Merge PDF
Combine multiple PDF files into one document. Upload the files, set the order, and download a single PDF. No account needed for basic use.
Try in browser
type
merge-pdf
Input
pdf
Output
pdf
Credits
1 API credits
Files
21 files
Extra files
additionalFileIds required
- Pass extra uploads as additionalFileIds on the conversion, after each file is completed.
- Send type explicitly. The API will not infer this tool from formats alone.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "merge-pdf",
  "additionalFileIds": [
    "FILE_ID_2"
  ]
}
```
Split PDF
Split a PDF into a new file with only the pages you need. Select pages visually, then download the result.
Try in browser
type
split-pdf
Input
pdf
Output
pdf
Credits
1 API credits
Files
1 file
Extra files
Source file only
options
- ranges[{ start, end }, ...] 1-basedoptional
- Page numbers are 1-based.
- Range start and end are inclusive.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "split-pdf",
  "options": {
    "ranges": [
      {
        "start": 1,
        "end": 2
      }
    ]
  }
}
```
Extract PDF pages
Extract selected pages from a PDF and save them as a new file. Choose pages visually, then download.
Try in browser
type
extract-pages
Input
pdf
Output
pdf
Credits
1 API credits
Files
1 file
Extra files
Source file only
options
- ranges[{ start, end }, ...] 1-basedoptional
- Page numbers are 1-based.
- Range start and end are inclusive.
- Send type explicitly. The API will not infer this tool from formats alone.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "extract-pages",
  "options": {
    "ranges": [
      {
        "start": 1,
        "end": 3
      }
    ]
  }
}
```
Organize PDF
Rearrange, rotate, and manage PDF pages in one place, then download the updated file.
Try in browser
type
organize-pdf
Input
pdf
Output
pdf
Credits
1 API credits
Files
1 file
Extra files
Source file only
options
- ordernumber[] page orderrequired
- rotations0 | 90 | 180 | 270 per pageoptional
- Page numbers are 1-based.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "organize-pdf",
  "options": {
    "order": [
      2,
      1,
      3
    ]
  }
}
```
Remove PDF pages
Delete unwanted pages from a PDF and keep the rest in a new file.
Try in browser
type
remove-pages
Input
pdf
Output
pdf
Credits
1 API credits
Files
1 file
Extra files
Source file only
options
- pagesnumber[] 1-basedrequired
- Page numbers are 1-based.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "remove-pages",
  "options": {
    "pages": [
      2,
      4
    ]
  }
}
```
Reorder PDF pages
Change the page order of a PDF, then download the rearranged file.
Try in browser
type
reorder-pages
Input
pdf
Output
pdf
Credits
1 API credits
Files
1 file
Extra files
Source file only
options
- ordernumber[] 1-basedrequired
- Page numbers are 1-based.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "reorder-pages",
  "options": {
    "order": [
      3,
      1,
      2
    ]
  }
}
```
Rotate PDF
Rotate one or more pages in a PDF, then download the corrected file.
Try in browser
type
rotate-pdf
Input
pdf
Output
pdf
Credits
1 API credits
Files
1 file
Extra files
Source file only
options
- degrees90 | 180 | 270required
- pagesnumber[] 1-basedoptional
- Page numbers are 1-based.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "rotate-pdf",
  "options": {
    "degrees": 90
  }
}
```
Crop PDF
Crop page margins and extra space from a PDF, then download the result.
Try in browser
type
crop-pdf
Input
pdf
Output
pdf
Credits
2 API credits
Files
1 file
Extra files
Source file only
options
- marginTopnumber, default 0optional
- marginRightnumber, default 0optional
- marginBottomnumber, default 0optional
- marginLeftnumber, default 0optional
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "crop-pdf",
  "options": {
    "marginTop": 24,
    "marginRight": 24,
    "marginBottom": 24,
    "marginLeft": 24
  }
}
```
Compress PDF
Reduce PDF file size while keeping the document readable. Choose a compression level and download a smaller PDF.
Try in browser
type
compress-pdf
Input
pdf
Output
pdf
Credits
2 API credits
Files
1 file
Extra files
Source file only
options
- levellow | medium | highoptional
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "compress-pdf",
  "options": {
    "level": "medium"
  }
}
```
Repair PDF
Attempt to fix a damaged or unreadable PDF, then download a repaired copy.
Try in browser
type
repair-pdf
Input
pdf
Output
pdf
Credits
2 API credits
Files
1 file
Extra files
Source file only
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "repair-pdf"
}
```
PDF to PDF/A
Pro
Convert a PDF into an archival PDF/A file for longer-term storage.
Try in browser
type
pdf-to-pdfa
Input
pdf
Output
pdf
Credits
5 API credits
Files
1 file
Extra files
Source file only
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "pdf-to-pdfa"
}
```
PDF to Word
Convert a PDF into an editable Word document. Upload a PDF and download a DOC or DOCX file.
Try in browser
type
pdf-to-word
Input
pdf
Output
docx
Credits
5 API credits
Files
1 file
Extra files
Source file only
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "docx",
  "type": "pdf-to-word"
}
```
PDF to Word OCR
Pro
Convert a scanned PDF to Word with OCR so the text can be edited.
Try in browser
type
pdf-to-word-ocr
Input
pdf
Output
docx
Credits
12 API credits
Files
1 file
Extra files
Source file only
options
- languageOCR language coderequired
- Send type explicitly. The API will not infer this tool from formats alone.
- language is an OCR language code such as eng or tur.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "docx",
  "type": "pdf-to-word-ocr",
  "options": {
    "language": "eng"
  }
}
```
PDF to PowerPoint
Convert a PDF into a PowerPoint presentation you can edit and present.
Try in browser
type
pdf-to-powerpoint
Input
pdf
Output
pptx
Credits
5 API credits
Files
1 file
Extra files
Source file only
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pptx",
  "type": "pdf-to-powerpoint"
}
```
PDF to Excel
Convert tables in a PDF into an Excel spreadsheet you can sort and edit.
Try in browser
type
pdf-to-excel
Input
pdf
Output
xlsx
Credits
5 API credits
Files
1 file
Extra files
Source file only
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "xlsx",
  "type": "pdf-to-excel"
}
```
PDF to Excel OCR
Pro
Convert scanned PDF tables to Excel with OCR.
Try in browser
type
pdf-to-excel-ocr
Input
pdf
Output
xlsx
Credits
12 API credits
Files
1 file
Extra files
Source file only
options
- languageOCR language coderequired
- Send type explicitly. The API will not infer this tool from formats alone.
- language is an OCR language code such as eng or tur.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "xlsx",
  "type": "pdf-to-excel-ocr",
  "options": {
    "language": "eng"
  }
}
```
PDF to JPG
Convert PDF pages into JPG images you can save or share.
Try in browser
type
pdf-to-jpg
Input
pdf
Output
jpg
Credits
1 API credits
Files
1 file
Extra files
Source file only
options
- page1-based page numberoptional
- quality1-100optional
- dpi72-600optional
- Page numbers are 1-based.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "jpg",
  "type": "pdf-to-jpg",
  "options": {
    "page": 1,
    "dpi": 150
  }
}
```
PDF to PNG
Convert PDF pages into PNG images with a transparent or clean background.
Try in browser
type
pdf-to-png
Input
pdf
Output
png
Credits
1 API credits
Files
1 file
Extra files
Source file only
options
- page1-based page numberoptional
- quality1-100optional
- dpi72-600optional
- Page numbers are 1-based.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "png",
  "type": "pdf-to-png",
  "options": {
    "page": 1,
    "dpi": 150
  }
}
```
PDF to text
Extract plain text from a PDF and download it as a text file.
Try in browser
type
pdf-to-txt
Input
pdf
Output
txt
Credits
1 API credits
Files
1 file
Extra files
Source file only
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "txt",
  "type": "pdf-to-txt"
}
```
Word to PDF
Convert a Word document into a PDF you can share or print.
Try in browser
type
word-to-pdf
Input
doc, docx
Output
pdf
Credits
2 API credits
Files
1 file
Extra files
Source file only
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "word-to-pdf"
}
```
PowerPoint to PDF
Convert a PowerPoint presentation into a PDF.
Try in browser
type
powerpoint-to-pdf
Input
ppt, pptx
Output
pdf
Credits
2 API credits
Files
1 file
Extra files
Source file only
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "powerpoint-to-pdf"
}
```
Excel to PDF
Convert an Excel spreadsheet into a PDF.
Try in browser
type
excel-to-pdf
Input
xls, xlsx
Output
pdf
Credits
2 API credits
Files
1 file
Extra files
Source file only
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "excel-to-pdf"
}
```
JPG to PDF
Convert a JPG image into a PDF file.
Try in browser
type
jpg-to-pdf
Input
jpg
Output
pdf
Credits
1 API credits
Files
20 files
Extra files
Source file only
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "jpg-to-pdf"
}
```
PNG to PDF
Convert a PNG image into a PDF file.
Try in browser
type
png-to-pdf
Input
png
Output
pdf
Credits
1 API credits
Files
20 files
Extra files
Source file only
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "png-to-pdf"
}
```
Office to PDF
Convert Word, Excel, or PowerPoint files into PDF.
Try in browser
type
office-to-pdf
Input
doc, docx, ppt, pptx, xls, xlsx
Output
pdf
Credits
2 API credits
Files
1 file
Extra files
Source file only
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "office-to-pdf"
}
```
Edit PDF
Pro
Add text, highlights, shapes, and images on top of a PDF. Existing text stays as it is.
Try in browser
type
edit-pdf
Input
pdf
Output
pdf
Credits
5 API credits
Files
2 files
Extra files
additionalFileIds optional
options
- operationstext | rectangle | image overlaysrequired
- Page numbers are 1-based.
- Pass extra uploads as additionalFileIds on the conversion, after each file is completed.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "edit-pdf",
  "options": {
    "operations": [
      {
        "kind": "text",
        "page": 1,
        "x": 72,
        "y": 720,
        "text": "CONFIDENTIAL",
        "size": 14
      }
    ]
  }
}
```
Watermark PDF
Add a text or image watermark across every page of a PDF.
Try in browser
type
watermark-pdf
Input
pdf
Output
pdf
Credits
1 API credits
Files
1 file
Extra files
Source file only
options
- textstringrequired
- opacity0-1optional
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "watermark-pdf",
  "options": {
    "text": "DRAFT",
    "opacity": 0.25
  }
}
```
Add PDF page numbers
Add page numbers to a PDF, then download the numbered file.
Try in browser
type
page-numbers-pdf
Input
pdf
Output
pdf
Credits
1 API credits
Files
1 file
Extra files
Source file only
options
- startAtnumber, default 1optional
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "page-numbers-pdf",
  "options": {
    "startAt": 1
  }
}
```
Protect PDF
Add a password so others need it to open or use the PDF.
Try in browser
type
protect-pdf
Input
pdf
Output
pdf
Credits
2 API credits
Files
1 file
Extra files
Source file only
options
- passwordstringrequired
- Do not log passwords. Rotate them if a request is captured.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "protect-pdf",
  "options": {
    "password": "YOUR_PASSWORD"
  }
}
```
Unlock PDF
Remove password protection from a PDF you own, then download an unlocked copy.
Try in browser
type
unlock-pdf
Input
pdf
Output
pdf
Credits
2 API credits
Files
1 file
Extra files
Source file only
options
- passwordstringrequired
- Do not log passwords. Rotate them if a request is captured.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "unlock-pdf",
  "options": {
    "password": "YOUR_PASSWORD"
  }
}
```
Sign PDF
Pro
Add a visual signature image or text stamp. This is not a cryptographic digital signature.
Try in browser
type
sign-pdf
Input
pdf
Output
pdf
Credits
5 API credits
Files
2 files
Extra files
additionalFileIds optional
options
- page1-based page numberrequired
- xnumberrequired
- ynumberrequired
- widthnumberrequired
- heightnumberrequired
- textfallback stamp textoptional
- Page numbers are 1-based.
- This is a visual stamp, not a cryptographic digital signature.
- Pass extra uploads as additionalFileIds on the conversion, after each file is completed.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "sign-pdf",
  "options": {
    "page": 1,
    "x": 72,
    "y": 72,
    "width": 160,
    "height": 64,
    "text": "Signed"
  }
}
```
Redact PDF
Pro
Permanently black out sensitive text or areas in a PDF before you share it.
Try in browser
type
redact-pdf
Input
pdf
Output
pdf
Credits
6 API credits
Files
1 file
Extra files
Source file only
options
- regions[{ page, x, y, width, height }]required
- Page numbers are 1-based.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "redact-pdf",
  "options": {
    "regions": [
      {
        "page": 1,
        "x": 72,
        "y": 400,
        "width": 200,
        "height": 24
      }
    ]
  }
}
```
Compare PDF
Pro
Compare two PDF versions and see what changed.
Try in browser
type
compare-pdf
Input
pdf
Output
txt
Credits
5 API credits
Files
2 files
Extra files
additionalFileIds required
- Pass extra uploads as additionalFileIds on the conversion, after each file is completed.
- Send type explicitly. The API will not infer this tool from formats alone.
- Upload both PDFs, then pass the second id in additionalFileIds.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "txt",
  "type": "compare-pdf",
  "additionalFileIds": [
    "FILE_ID_2"
  ]
}
```
Scan to PDF
Pro
Turn scanned images into a single PDF.
Try in browser
type
scan-to-pdf
Input
jpg, png
Output
pdf
Credits
2 API credits
Files
50 files
Extra files
additionalFileIds optional
- Pass extra uploads as additionalFileIds on the conversion, after each file is completed.
- Send type explicitly. The API will not infer this tool from formats alone.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "scan-to-pdf",
  "additionalFileIds": [
    "FILE_ID_2"
  ]
}
```
Extract PDF content
Pro
Extract structured content from a PDF for reuse in other files.
Try in browser
type
pdf-extract
Input
pdf
Output
txt, json
Credits
12 API credits
Files
1 file
Extra files
Source file only
- Send type explicitly. The API will not infer this tool from formats alone.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "txt",
  "type": "pdf-extract"
}
```
PDF to Markdown
Pro
Convert PDF content into Markdown you can edit in a text editor.
Try in browser
type
pdf-to-markdown
Input
pdf
Output
md
Credits
5 API credits
Files
1 file
Extra files
Source file only
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "md",
  "type": "pdf-to-markdown"
}
```
OCR PDF
Pro
Make a scanned PDF searchable with OCR, or extract the recognized text.
Try in browser
type
ocr-pdf
Input
pdf
Output
pdf, txt
Credits
5 API credits
Files
1 file
Extra files
Source file only
options
- languageOCR language coderequired
- outputModepdf | txtrequired
- Send type explicitly. The API will not infer this tool from formats alone.
- language is an OCR language code such as eng or tur.
POST /conversions body
```
{
  "sourceFileId": "FILE_ID",
  "targetFormat": "pdf",
  "type": "ocr-pdf",
  "options": {
    "language": "eng",
    "outputMode": "pdf"
  }
}
```

Errors

Every error uses this envelope. Missing files and conversions both return NOT_FOUND. An expired owned file returns FILE_EXPIRED instead of 404.

JSON

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required",
    "requestId": "req_example"
  }
}

Code	HTTP
VALIDATION_ERROR	400
UNAUTHORIZED	401
FORBIDDEN	403
PLAN_LIMIT_REACHED	403
STORAGE_LIMIT_REACHED	403
API_KEY_LIMIT_REACHED	403
NOT_FOUND	404
CONFLICT	409
FILE_EXPIRED	410
FILE_TOO_LARGE	413
RATE_LIMITED	429
CONFIGURATION_ERROR	500
INTERNAL_ERROR	500

429 includes Retry-After, RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset. Wait, then retry. Do not tight-loop.

Limits and credits

API credits are separate from web tool credits. Rate limits follow the web plan. Hitting a quota returns 403 PLAN_LIMIT_REACHED.

Free: 5 conversions/day, 25 MB files, 30 API requests/minute.
Pro: unlimited conversions, 1 GB files, 60 API requests/minute.
Each conversion consumes the tool’s API credit cost. Accounts include 100 API credits each month; buy Developer packs from billing for more.
Webhooks are not available. Clients must poll.

Quickstart

Authentication

Files

Conversions

Tools

Merge PDF

Split PDF

Extract PDF pages

Organize PDF

Remove PDF pages

Reorder PDF pages

Rotate PDF

Crop PDF

Compress PDF

Repair PDF

PDF to PDF/A

PDF to Word

PDF to Word OCR

PDF to PowerPoint

PDF to Excel

PDF to Excel OCR

PDF to JPG

PDF to PNG

PDF to text

Word to PDF

PowerPoint to PDF

Excel to PDF

JPG to PDF

PNG to PDF

Office to PDF

Edit PDF

Watermark PDF

Add PDF page numbers

Protect PDF

Unlock PDF

Sign PDF

Redact PDF

Compare PDF

Scan to PDF

Extract PDF content

PDF to Markdown

OCR PDF

Errors

Limits and credits

Quickstart

Authentication

Files

Conversions

Tools

Merge PDF

Split PDF

Extract PDF pages

Organize PDF

Remove PDF pages

Reorder PDF pages

Rotate PDF

Crop PDF

Compress PDF

Repair PDF

PDF to PDF/A

PDF to Word

PDF to Word OCR

PDF to PowerPoint

PDF to Excel

PDF to Excel OCR

PDF to JPG

PDF to PNG

PDF to text

Word to PDF

PowerPoint to PDF

Excel to PDF

JPG to PDF

PNG to PDF

Office to PDF

Edit PDF

Watermark PDF

Add PDF page numbers

Protect PDF

Unlock PDF

Sign PDF