API Documentation

Authentication

All API requests require authentication using an API token. The API token is required via the X-Api-Token header. The Authorization: Bearer header is optional but can be provided for additional user context.

Required Header

X-Api-Token: YOUR_API_TOKEN

Optional Header

Authorization: Bearer YOUR_JWT_TOKEN

Note: Create API tokens in your dashboard. The Bearer token is optional and only used for additional user context validation.

Endpoints

Convert File

POST /api/convert

Convert a file from one format to another. Supports both JSON and multipart/form-data.

Request Body (JSON)

{
  "inputFormat": "pdf",
  "outputFormat": "png",
  "file": "base64-encoded-file-content",
  "options": {} // optional
}

Request Body (Form Data)

Content-Type: multipart/form-data

inputFormat: pdf
outputFormat: png
file: [binary file upload]
options: {"density": 300} // optional, as JSON string

Convert and Analyze

POST /api/convert/analyze

Convert a file and analyze it with AI. Supports both JSON and multipart/form-data.

Request Body (JSON)

{
  "inputFormat": "pdf",
  "outputFormat": "png",
  "file": "base64-encoded-file-content",
  "prompt": "Extract invoice data",
  "model": "openai",
  "modelName": "gpt-4o", // optional
  "outputFormatType": "JSON" // optional, defaults to "JSON"
}

Request Body (Form Data)

Content-Type: multipart/form-data

inputFormat: pdf
outputFormat: png
file: [binary file upload]
prompt: Extract invoice data
model: openai
modelName: gpt-4o // optional
outputFormatType: JSON // optional, defaults to "JSON"

Output Format Types

The outputFormatType parameter specifies the format for AI-generated responses. This allows you to control how structured data is returned, optimizing for token usage and parsing efficiency.

Supported Format Types

JSON (Default)

Standard JSON format. Best for general-purpose use and compatibility with most systems.

outputFormatType: "JSON"

TOON Documentation

Token-Optimized Object Notation - Reduces token costs by 30-60% compared to JSON by declaring fields once and streaming data as rows. Perfect for large datasets and uniform arrays. TOON uses 2-space indentation with explicit array lengths and field headers.

outputFormatType: "TOON"

// Example TOON output:
items[3]{id,name,price}:
  1,Item A,10.99
  2,Item B,20.50
  3,Item C,15.00

TONL Documentation

Token-Optimized Notation Language - A compact format that reduces token costs by 32-45% compared to JSON. Uses field declarations and row-based data for efficient serialization. Ideal for high-volume API calls where token costs matter.

outputFormatType: "TONL"

Custom Formats

You can also specify custom format types like "XML", "CSV", "YAML", etc. The AI will be instructed to return data in the specified format.

outputFormatType: "XML" // or "CSV", "YAML", etc.

💡 Why use TOON or TONL?

Save 30-60% on token costs - Especially beneficial for large datasets and high-volume operations
Faster processing - Less tokens means faster AI responses
Better for arrays - Field names declared once, data streamed as rows
Structured validation - Explicit lengths and headers make parsing more reliable

Get Supported Formats

GET /api/formats

Get list of supported input and output formats.

Code Examples

Node.js (JSON)

const fs = require('fs');
const file = fs.readFileSync('invoice.pdf');
const base64 = file.toString('base64');

const response = await fetch('http://localhost:3000/api/convert', {
  method: 'POST',
  headers: {
    'X-Api-Token': 'YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    inputFormat: 'pdf',
    outputFormat: 'png',
    file: base64
  })
});

const result = await response.json();
const outputFile = Buffer.from(result.outputFile, 'base64');
fs.writeFileSync('output.png', outputFile);

Node.js (Form Data)

const fs = require('fs');
const FormData = require('form-data');

const form = new FormData();
form.append('inputFormat', 'pdf');
form.append('outputFormat', 'png');
form.append('file', fs.createReadStream('invoice.pdf'));

const response = await fetch('http://localhost:3000/api/convert', {
  method: 'POST',
  headers: {
    'X-Api-Token': 'YOUR_API_TOKEN',
    ...form.getHeaders()
  },
  body: form
});

const result = await response.json();
const outputFile = Buffer.from(result.outputFile, 'base64');
fs.writeFileSync('output.png', outputFile);

Python (JSON)

import requests
import base64

with open('invoice.pdf', 'rb') as f:
    file_data = base64.b64encode(f.read()).decode('utf-8')

response = requests.post(
    'http://localhost:3000/api/convert',
    headers={
        'X-Api-Token': 'YOUR_API_TOKEN',
        'Content-Type': 'application/json'
    },
    json={
        'inputFormat': 'pdf',
        'outputFormat': 'png',
        'file': file_data
    }
)

result = response.json()
output_file = base64.b64decode(result['outputFile'])
with open('output.png', 'wb') as f:
    f.write(output_file)

Python (Form Data)

import requests

with open('invoice.pdf', 'rb') as f:
    files = {'file': f}
    data = {
        'inputFormat': 'pdf',
        'outputFormat': 'png'
    }
    
    response = requests.post(
        'http://localhost:3000/api/convert',
        headers={
            'X-Api-Token': 'YOUR_API_TOKEN'
        },
        files=files,
        data=data
    )

result = response.json()
output_file = base64.b64decode(result['outputFile'])
with open('output.png', 'wb') as f:
    f.write(output_file)

cURL (JSON)

curl -X POST http://localhost:3000/api/convert \
  -H "X-Api-Token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "inputFormat": "pdf",
    "outputFormat": "png",
    "file": "BASE64_ENCODED_FILE"
  }'

cURL (Form Data)

curl -X POST http://localhost:3000/api/convert \
  -H "X-Api-Token: YOUR_API_TOKEN" \
  -F "inputFormat=pdf" \
  -F "outputFormat=png" \
  -F "file=@invoice.pdf"

AI Integration with ChatGPT

To use with ChatGPT via AI SDK:

import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';

// First convert PDF to PNG
const convertResponse = await fetch('http://localhost:3000/api/convert', {
  method: 'POST',
  headers: {
    'X-Api-Token': 'YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    inputFormat: 'pdf',
    outputFormat: 'png',
    file: pdfBase64
  })
});

const { outputFile } = await convertResponse.json();

// Then analyze with ChatGPT
const result = await generateText({
  model: openai('gpt-4o'),
  messages: [{
    role: 'user',
    content: [
      { type: 'text', text: 'Extract invoice data as JSON' },
      { type: 'image', image: `data:image/png;base64,${outputFile}` }
    ]
  }]
});

console.log(result.text);

Using the Analyze Endpoint

Alternatively, you can use the /api/convert/analyze endpoint to convert and analyze in one request:

const response = await fetch('http://localhost:3000/api/convert/analyze', {
  method: 'POST',
  headers: {
    'X-Api-Token': 'YOUR_API_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    inputFormat: 'pdf',
    outputFormat: 'png',
    file: pdfBase64,
    prompt: 'Extract invoice data',
    model: 'openai',
    modelName: 'gpt-4o',
    outputFormatType: 'TOON' // Optional: JSON (default), TOON, TONL, or custom
  })
});

const result = await response.json();
console.log(result.ai.text); // AI analysis result in specified format
console.log(result.conversion.outputFile); // Converted file (base64)