API Documentation

Complete reference for the My File Tool REST API v1. Base URL: https://myfiletool.com/api/v1

Authentication

All endpoints except /formats, /tools, /register, and /verify require a Bearer token in the Authorization header:

Authorization: Bearer mt_xxxxxxxxxxxxxxxxxxxx

Get a key by calling POST /register, then verify your email. New accounts receive 50 free credits.

Response Format

Successful responses return a data object and a meta object with the request ID and remaining credits. Errors return an error object with a machine-readable code and a human-readable message.

Every response includes X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers.

Conversion

POST /convert Auth required

Upload a file and receive the converted result in one request. By default the response is the binary converted file. Set Accept: application/json to get JSON metadata with a download URL instead.

Request Body (multipart/form-data)

Field	Type	Description
`file` required	binary	The file to convert.
`output_format` required	string	Target format, e.g. `jpeg`, `webp`, `png`.
`quality` optional	integer	Output quality (1-100). Applies to lossy formats only.

Example Request

curl -X POST https://myfiletool.com/api/v1/convert \
  -H "Authorization: Bearer mt_YOUR_KEY" \
  -H "Accept: application/json" \
  -F "file=@photo.heic" \
  -F "output_format=jpeg"

Example Response (JSON)

{
  "data": {
    "file_id": "a1b2c3d4e5f6",
    "input_format": "heic",
    "output_format": "jpeg",
    "original_size": 2458000,
    "processed_size": 890400,
    "reduction_percent": 63.8,
    "download_url": "/api/v1/files/a1b2c3d4e5f6/download",
    "processing_time_ms": 320
  },
  "meta": {
    "request_id": "req_a1b2c3d4e5f6",
    "credits_remaining": 49
  }
}

Responses

200 Converted file (binary or JSON)
400 Invalid parameters or unsupported conversion
401 Missing or invalid API key
402 No credits remaining
413 File too large
429 Rate limited

POST /files/upload Auth required

Upload a file for later conversion (two-step flow, step 1). Returns a file_id to pass to POST /files/{file_id}/convert.

Request Body (multipart/form-data)

Field	Type	Description
`file` required	binary	The file to upload.

Example Response

{
  "data": {
    "file_id": "a1b2c3d4e5f6",
    "extension": "heic",
    "size": 2458000,
    "original_name": "photo.heic"
  },
  "meta": { "request_id": "req_b2c3d4e5f6a1", "credits_remaining": 50 }
}

Responses

200 File uploaded
400 Invalid file
401 Unauthorized
413 File too large

POST /files/{file_id}/convert Auth required

Convert a previously uploaded file (two-step flow, step 2). The request body is JSON since the file was already uploaded.

Path Parameters

Param	Type	Description
`file_id` required	string	File ID from the upload step.

Request Body (JSON)

Field	Type	Description
`output_format` required	string	Target format.
`quality` optional	integer	Output quality (1-100).

Responses

200 Conversion result with download URL
400 Invalid parameters
402 No credits
404 File not found

GET /files/{file_id} Auth required

Check the status of a file: pending (uploaded, not yet converted) or processed (ready for download).

Responses

200 File status object
404 File not found

GET /files/{file_id}/download Auth required

Download a converted file. Returns the binary file content. The file must have processed status.

Responses

200 Binary file
404 File not found or not processed

Batch

POST /batch Auth required

Create a batch session for converting multiple files. Creating a batch costs 0 credits; credits are charged when you convert.

Request Body (JSON)

Field	Type	Description
`output_format` required	string	Target format for all files.

Example Response

{
  "data": {
    "batch_id": "bat_f6a1b2c3d4e5",
    "output_format": "webp",
    "status": "created"
  }
}

POST /batch/{batch_id}/files Auth required

Add a file to an existing batch. Repeat for each file. Files are stored but not converted until you call the convert endpoint.

Request Body (multipart/form-data)

Field	Type	Description
`file` required	binary	File to add to the batch.

POST /batch/{batch_id}/convert Auth required

Convert all or a subset of files in the batch. Each successfully converted file costs 1 credit.

Request Body (JSON)

Field	Type	Description
`file_ids` required	string[]	Array of file IDs to convert.
`output_format` required	string	Target format.
`quality` optional	integer	Output quality (1-100).

Example Response

{
  "data": {
    "results": [
      { "file_id": "a1b2...", "status": "success", "download_url": "/api/v1/files/a1b2.../download" },
      { "file_id": "b2c3...", "status": "success", "download_url": "/api/v1/files/b2c3.../download" }
    ],
    "total": 2, "successful": 2, "failed": 0
  },
  "meta": { "credits_remaining": 48 }
}

GET /batch/{batch_id} Auth required

Get the current status and file counts for a batch.

PDF

POST /pdf/merge Auth required

Upload 2-20 PDF files and receive a single merged PDF. Costs 1 credit. Upload files as files[] (array). Set Accept: application/json for JSON metadata.

Request Body (multipart/form-data)

Field	Type	Description
`files[]` required	binary[]	2-20 PDF files to merge.

Example Request

curl -X POST https://myfiletool.com/api/v1/pdf/merge \
  -H "Authorization: Bearer mt_YOUR_KEY" \
  -H "Accept: application/json" \
  -F "files[]=@doc1.pdf" \
  -F "files[]=@doc2.pdf"

POST /pdf/delete-pages Auth required

Upload a PDF and specify which pages to remove. Costs 1 credit.

Request Body (multipart/form-data)

Field	Type	Description
`file` required	binary	The PDF file.
`pages` required	string	Comma-separated page numbers to delete (1-indexed), e.g. `2,5,8`.

Formats

GET /formats No auth

List every supported input-to-output format pair. No authentication required.

Example Request

curl https://myfiletool.com/api/v1/formats

Example Response

{
  "data": {
    "conversions": [
      { "input_format": "heic", "output_format": "jpeg" },
      { "input_format": "png", "output_format": "webp" }
    ],
    "by_input_format": {
      "heic": ["jpeg", "png", "webp"],
      "jpeg": ["png", "webp", "avif"]
    },
    "total": 103
  }
}

GET /tools No auth

List all conversion tools with their input/output format capabilities. No authentication required.

Account

GET /account Auth required

Returns your account details: tier, credit balance, file-size limits, and rate-limit configuration.

Example Response

{
  "data": {
    "name": "My App",
    "email": "dev@example.com",
    "tier": "free",
    "credits_remaining": 42,
    "credits_total_purchased": 0,
    "max_file_size": 10485760,
    "created_at": "2025-06-01 08:00:00",
    "last_used_at": "2025-06-15 12:34:56"
  },
  "meta": { "credits_remaining": 42 }
}

GET /account/usage Auth required

Returns conversion counts and data transfer for a given period. Defaults to the current month.

Query Parameters

Param	Type	Description
`period` optional	string	Period start in `YYYY-MM-DD` or `YYYY-MM` format. Defaults to current month.

Registration

POST /register No auth

Register for an API key. A verification email is sent with a link that expires in 24 hours. After verifying, you receive your API key and 50 free credits.

Request Body (JSON)

Field	Type	Description
`email` required	string	Your email address.
`name` required	string	Application or project name (2-100 characters).

Example Request

curl -X POST https://myfiletool.com/api/v1/register \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@example.com", "name": "My App"}'

Example Response

{
  "data": {
    "email": "dev@example.com",
    "verification_sent": true,
    "message": "Check your email for a verification link."
  }
}

GET /verify No auth

Called via the link in the verification email. Returns the API key (for API clients) or redirects to the developer page (for browsers). Save your API key immediately — it is shown only once.

Query Parameters

Param	Type	Description
`token` required	string	64-character hex verification token from the email link.

POST /credits/purchase Auth required

Create a Stripe Checkout session for a credit pack. The response includes a checkout_url to open in a browser.

Request Body (JSON)

Field	Type	Description
`pack` required	string	Pack name: `starter` (500 credits, 5 EUR), `pro` (2000 credits, 15 EUR), or `business` (10000 credits, 50 EUR).
`language` optional	string	Language code for checkout page (default: `en`).

Error Codes

Code	HTTP	Description
`invalid_api_key`	401	Missing or invalid Bearer token.
`key_not_verified`	403	API key exists but email not verified.
`rate_limit_exceeded`	429	Too many requests. Check `Retry-After` header.
`no_credits`	402	No credits remaining. Purchase a credit pack.
`invalid_file_type`	400	Uploaded file type not recognized.
`file_too_large`	413	File exceeds size limit (10MB free, 100MB paid).
`unsupported_conversion`	400	No conversion path for the input/output pair.
`processing_failed`	500	Conversion engine error.
`invalid_parameter`	400	Missing or invalid request parameter.
`not_found`	404	Resource not found or expired.
`server_error`	500	Internal server error.