Developers

API Documentation

The KOIAE PDF Tools REST API lets you automate PDF workflows straight from your own apps and scripts. Authenticate with your personal API key and start processing documents in minutes.

Getting started

Grab your API key from the Dashboard → API access section. Each key looks like koiae_live_… followed by 48 hex characters. Keep it secret — treat it like a password.

Keys are stored only as a one-way hash on our servers, so we can never show a key again after it is created. You can revoke or regenerate your key at any time from the Dashboard; regenerating immediately invalidates the previous key.

Base URL

All v1 endpoints are relative to this base URL:

https://koiae.com/api/v1

Authentication

Every request must include your API key using one of the two supported headers. Requests without a valid key receive a 401 Unauthorized response.

Authorization header (recommended): Authorization: Bearer <your-key>
Custom header: x-api-key: <your-key>

GET/tools

List every available PDF tool, including its slug, category and processing type. The response also echoes your current plan.

curl https://koiae.com/api/v1/tools \
  -H "Authorization: Bearer koiae_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Example response:

{
  "tools": [
    {
      "slug": "merge-pdf",
      "name": "Merge PDF",
      "category": "organize",
      "processing": "client",
      "url": "/merge-pdf"
    }
  ],
  "plan": "free"
}

POST/merge

Merge two or more PDF files into a single document. Send a multipart/form-data body with a repeated files field — one entry per PDF, in the order you want them combined. Each file must be a valid PDF up to 50 MB. The response is the merged PDF as application/pdf.

curl https://koiae.com/api/v1/merge \
  -H "Authorization: Bearer koiae_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -F "files=@first.pdf" \
  -F "files=@second.pdf" \
  -o merged.pdf

Errors

Errors are returned as JSON with an error message and an appropriate HTTP status code — for example 401 for a missing or invalid key, 400 when fewer than two PDFs are supplied, 413 for oversized files, and 415 when an upload is not a valid PDF.