API reference

API documentation

Process files programmatically with the Filagram REST API.

The Filagram API is coming soon.

This page shows planned endpoints. None are available yet. Join the waitlist to be notified at launch.

Authentication

All API requests require an API key passed as a Bearer token in the Authorization header.

Authorization: Bearer sk_live_your_api_key_here

API keys will be available from your account dashboard after launch.

Keep your API key secret. Do not expose it in client-side code or commit it to version control.

Keys are prefixed with sk_live_ for production and sk_test_ for testing.

Rate limits

Plan	Requests / month	Max file size	Burst limit
Free	100	10 MB	5 req / minute
Pro	10,000	100 MB	60 req / minute
Enterprise	Unlimited	1 GB	Custom

Rate limits are subject to change before launch.

Endpoints

POST/api/v1/compress

Compress an image. Supports JPEG, PNG, and WebP.

Request body

Content-Type: multipart/form-data

file        (required)  Image file to compress
quality     (optional)  1–100, default 80
format      (optional)  "jpeg" | "png" | "webp" — output format

Response

{
  "url": "https://cdn.filagram.com/output/abc123.jpg",
  "original_size": 214000,
  "output_size": 89400,
  "saved_percent": 58.2,
  "expires_at": "2026-04-03T00:00:00Z"
}

Examples

cURL

curl -X POST https://api.filagram.com/api/v1/compress \
  -H "Authorization: Bearer sk_live_..." \
  -F "file=@photo.jpg" \
  -F "quality=80"

JavaScript (fetch)

const form = new FormData();
form.append("file", fileInput.files[0]);
form.append("quality", "80");

const res = await fetch("https://api.filagram.com/api/v1/compress", {
  method: "POST",
  headers: { Authorization: "Bearer sk_live_..." },
  body: form,
});
const data = await res.json();
console.log(data.url);

POST/api/v1/convert

Convert an image between formats. Supports JPEG, PNG, WebP, and HEIC.

Request body

Content-Type: multipart/form-data

file        (required)  Image file to convert
to          (required)  "jpeg" | "png" | "webp"

Response

{
  "url": "https://cdn.filagram.com/output/def456.webp",
  "format": "webp",
  "size": 44200,
  "expires_at": "2026-04-03T00:00:00Z"
}

Examples

cURL

curl -X POST https://api.filagram.com/api/v1/convert \
  -H "Authorization: Bearer sk_live_..." \
  -F "file=@photo.png" \
  -F "to=webp"

JavaScript (fetch)

const form = new FormData();
form.append("file", fileInput.files[0]);
form.append("to", "webp");

const res = await fetch("https://api.filagram.com/api/v1/convert", {
  method: "POST",
  headers: { Authorization: "Bearer sk_live_..." },
  body: form,
});
const data = await res.json();
console.log(data.url);

POST/api/v1/resize

Resize an image to specific dimensions. Maintains aspect ratio by default.

Request body

Content-Type: multipart/form-data

file        (required)  Image file to resize
width       (optional)  Target width in pixels
height      (optional)  Target height in pixels
fit         (optional)  "contain" | "cover" | "fill", default "contain"

Response

{
  "url": "https://cdn.filagram.com/output/ghi789.jpg",
  "width": 1280,
  "height": 720,
  "size": 102400,
  "expires_at": "2026-04-03T00:00:00Z"
}

Examples

cURL

curl -X POST https://api.filagram.com/api/v1/resize \
  -H "Authorization: Bearer sk_live_..." \
  -F "file=@photo.jpg" \
  -F "width=1280" \
  -F "height=720"

JavaScript (fetch)

const form = new FormData();
form.append("file", fileInput.files[0]);
form.append("width", "1280");
form.append("height", "720");

const res = await fetch("https://api.filagram.com/api/v1/resize", {
  method: "POST",
  headers: { Authorization: "Bearer sk_live_..." },
  body: form,
});
const data = await res.json();
console.log(data.url);

POST/api/v1/merge-pdf

Merge multiple PDF files into a single document. Files are merged in the order they are provided.

Request body

Content-Type: multipart/form-data

files[]     (required)  Two or more PDF files

Response

{
  "url": "https://cdn.filagram.com/output/jkl012.pdf",
  "pages": 24,
  "size": 1048576,
  "expires_at": "2026-04-03T00:00:00Z"
}

Examples

cURL

curl -X POST https://api.filagram.com/api/v1/merge-pdf \
  -H "Authorization: Bearer sk_live_..." \
  -F "files[]=@doc1.pdf" \
  -F "files[]=@doc2.pdf"

JavaScript (fetch)

const form = new FormData();
form.append("files[]", file1);
form.append("files[]", file2);

const res = await fetch("https://api.filagram.com/api/v1/merge-pdf", {
  method: "POST",
  headers: { Authorization: "Bearer sk_live_..." },
  body: form,
});
const data = await res.json();
console.log(data.url);

POST/api/v1/split-pdf

Split a PDF into individual pages. Returns a zip archive containing each page as a separate PDF.

Request body

Content-Type: multipart/form-data

file        (required)  PDF file to split
pages       (optional)  Page range, e.g. "1-3,5" — defaults to all pages

Response

{
  "url": "https://cdn.filagram.com/output/mno345.zip",
  "pages": 12,
  "size": 512000,
  "expires_at": "2026-04-03T00:00:00Z"
}

Examples

cURL

curl -X POST https://api.filagram.com/api/v1/split-pdf \
  -H "Authorization: Bearer sk_live_..." \
  -F "file=@document.pdf"

JavaScript (fetch)

const form = new FormData();
form.append("file", fileInput.files[0]);

const res = await fetch("https://api.filagram.com/api/v1/split-pdf", {
  method: "POST",
  headers: { Authorization: "Bearer sk_live_..." },
  body: form,
});
const data = await res.json();
// data.url points to a .zip archive
console.log(data.url);

POST/api/v1/ocr

Extract text from an image or PDF using optical character recognition.

Request body

Content-Type: multipart/form-data

file        (required)  Image (JPEG, PNG) or PDF file
language    (optional)  ISO 639-1 language code, e.g. "en", default "en"

Response

{
  "text": "Extracted text content here...",
  "pages": 1,
  "confidence": 0.97,
  "expires_at": "2026-04-03T00:00:00Z"
}

Examples

cURL

curl -X POST https://api.filagram.com/api/v1/ocr \
  -H "Authorization: Bearer sk_live_..." \
  -F "file=@scan.pdf" \
  -F "language=en"

JavaScript (fetch)

const form = new FormData();
form.append("file", fileInput.files[0]);
form.append("language", "en");

const res = await fetch("https://api.filagram.com/api/v1/ocr", {
  method: "POST",
  headers: { Authorization: "Bearer sk_live_..." },
  body: form,
});
const data = await res.json();
console.log(data.text);

Error responses

All errors return a JSON body with a code and message field.

// 401 Unauthorized
{
  "code": "UNAUTHORIZED",
  "message": "Missing or invalid API key."
}

// 422 Unprocessable Entity
{
  "code": "INVALID_FILE",
  "message": "The uploaded file is not a supported image format."
}

// 429 Too Many Requests
{
  "code": "RATE_LIMITED",
  "message": "You have exceeded your monthly request limit.",
  "reset_at": "2026-05-01T00:00:00Z"
}

Status	Code	Meaning
400	BAD_REQUEST	Missing required parameter
401	UNAUTHORIZED	Invalid or missing API key
413	FILE_TOO_LARGE	File exceeds plan size limit
422	INVALID_FILE	Unsupported file format
429	RATE_LIMITED	Monthly limit exceeded
500	INTERNAL_ERROR	Unexpected server error

Want early access to the API?

Join the waitlist and be notified when the API launches.

Join the waitlist