Developer quickstart

One request. A clean document back.

Send a JPEG, PNG, or PDF to ScanKit and receive a perspective-corrected scan for the next step in your product. Explore the request, response, and code below.

Open the playgroundAPI reference
SCAN REQUESTReady
POST /scan/crop
InputJPEG, PNG, PDF
OutputClean JPG or PDF
ProcessingDetect + rectify
TRY THE API

Test ScanKit with your document.

Upload a JPEG, PNG, or PDF, choose the output you need, and see the clean scan ScanKit returns.

Input Image

Result

Did you find this information helpful?
Sample code

Drop-in code snippets

Integrate scanning capabilities into your application with a simple API call. The ScanKit API supports various parameters for precise control over the output.

JPEG Image
curl -X POST https://api.scankit.io/scan/crop \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: multipart/form-data" \
 -F "file=@/path/to/your/image.jpg" \
 -F "output_width=1536" \
 -F "filter=white" \
 --output result.jpg
PDF with OCR Text
curl -X POST https://api.scankit.io/scan/crop \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: multipart/form-data" \
 -F "file=@/path/to/your/image.jpg" \
 -F "output_width=1536" \
 -F "return_pdf=true" \
 -F "ocr_lang=eng" \
 --output result.pdf
Multi-Page French PDF
curl -X POST https://api.scankit.io/scan/crop \
 -H "Authorization: Bearer YOUR_API_KEY" \
 -H "Content-Type: multipart/form-data" \
 -F "files=@/path/to/page1.jpg" \
 -F "files=@/path/to/page2.jpg" \
 -F "output_width=1536" \
 -F "filter=white" \
 -F "return_pdf=true" \
 -F "ocr_lang=fra" \
 --output result.pdf
Get an API key
Reference

API reference

Servers

Document Scanning

Upload an image to be cropped and optionally filtered. The result is returned as a binary JPEG file.

Parameters

No parameters

Request body

file *
string($binary)

The image file to process.

output_width
integer($int32)

Specifies the desired width (in pixels) of the output image after cropping.

  • The output height is calculated automatically to preserve the aspect ratio of the cropped document.
  • The aspect ratio is determined by the shape of the document after cropping, which depends on the detected content and cannot be predicted in advance.
  • The default value is 1536 pixels, and a typical recommended range is between 1024 and 2048 pixels for optimal quality and performance.
filter
string

Specifies the filter applied to the image after cropping:

  • "white" (default): Corrects irregular lighting and produces a plain white background for white paper documents.
  • "flat": Corrects irregular lighting but does not change contrast or colors.
  • "original": No filter applied, the image remains unmodified.
segment_count
integer($int32)

Specifies the number of segments used to process curved or folded images.

  • Higher values provide better handling of heavily curved or folded documents but may increase processing time.
  • Lower values are faster but may not handle severe curves as well.
  • The default value is 9 segments, which provides a good balance between quality and performance.
return_pdf
boolean

Determines the output format of the processed document:

  • false (default): Returns the processed image as a JPEG file.
  • true: Creates a searchable PDF with an OCR text layer instead of returning a JPEG image.
ocr_lang
string

Language for OCR text recognition when return_pdf is true:

  • "eng" (default): English language OCR
  • "deu": German language OCR This parameter is only used when return_pdf is set to true.
return_meta
boolean

Opt-in metadata mode (v2 pipeline). When true, the response is JSON instead of a raw JPEG and includes the field document_detected:

  • true: a document was detected and warped; the returned image is the corrected scan.
  • false: no usable document was modelled; the response is HTTP 200 with the unchanged input image, so clients can open a manual-crop screen. Also available on the JSON paths return_json=1 / return_warp_geometry=true, and as the X-ScanKit-Detected header when a raw image is returned.

Responses

CodeDescriptionLinks
200

Successfully processed and cropped image returned as a binary file.

Media type
Controls Accept header.
(binary image data)

Headers:

NameDescriptionType
X-ScanKit-Detected

Present when the v2 Lambda reported a detection result (e.g. with return_meta=true). true = a document was detected and warped; false = no usable document was modelled and the unchanged input image is returned (clients can open a manual-crop screen). Absent on responses that predate this field.

string
No links
400

Invalid parameters or unprocessable input file (no credits charged)

Media type
Examples
{
  "errors": [
    {
      "code": "invalid_file_type",
      "title": "The uploaded file format is not supported. Please use JPEG or PNG."
    }
  ]
}
No links
401

Error: authentication failed (no credits charged). "Missing API Key" when no key was sent at all, "Invalid API Key" when the key that was sent is unknown or inactive.

Media type
Examples
{
  "errors": [
    {
      "title": "Missing API Key"
    }
  ]
}
No links
402

Error: Insufficient credits (no credits charged)

Media type
{
  "errors": [
    {
      "title": "Insufficient credits"
    }
  ]
}
No links
429

Rate limit exceeded: more than 1000 requests in a rolling hour for this API key (no credits charged). Wait the seconds given in the Retry-After header before retrying.

Media type
{
  "errors": [
    {
      "title": "Rate limit exceeded",
      "detail": "Limit is 1000 requests per hour per API key. Retry after 42 seconds."
    }
  ]
}

Headers:

NameDescriptionType
Retry-After

Seconds to wait before the next request is allowed.

integer
Example: 42
No links
500

Internal server error. Contact support if the issue persists.

No links
Did you find this information helpful?

Questions before integrating? Send us a message