Codestin Search App

Use POST /parse to turn a file into Markdown for search, document review, or an LLM. Send raw bytes from an upload or storage bucket; the file does not need a public URL. The upload limit is 25 MiB. Each successful conversion costs 1 credit, plus 1 credit per PDF page recovered by OCR when enabled.

Prerequisites

Create an API key in the dashboard and export it on your server:

export CONTEXT_DEV_API_KEY="ctxt_secret_..."

Convert a file to Markdown

Send the file itself as the request body, without multipart encoding or JSON. --data-binary preserves its bytes:

curl -X POST "https://api.context.dev/v1/parse?extension=pdf" \
  -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @report.pdf

import { readFile } from "node:fs/promises";
import ContextDev, { toFile } from "context.dev";

const client = new ContextDev({apiKey: process.env.CONTEXT_DEV_API_KEY});
const file = await toFile(await readFile("report.pdf"), "report.pdf", {
  type: "application/pdf",
});

const result = await client.parse.handle(file, {
  extension: "pdf"
}, {
  headers: {"Content-Type": "application/pdf"},
});

console.log(result.markdown);

import os
from pathlib import Path
from context.dev import ContextDev

client = ContextDev(api_key=os.environ["CONTEXT_DEV_API_KEY"])

result = client.parse.handle(
    body=Path("report.pdf").read_bytes(),
    extension="pdf",
    extra_headers={"Content-Type": "application/pdf"},
)

print(result.markdown)

require "cgi/core"
require "context_dev"

client = ContextDev::Client.new(api_key: ENV.fetch("CONTEXT_DEV_API_KEY"))

result = client.parse.handle(
  body: File.binread("report.pdf"),
  extension: :pdf,
  request_options: {extra_headers: {"Content-Type" => "application/pdf"}},
)

puts result.markdown

package main

import (
    "context"
    "fmt"
    "os"

    contextdev "github.com/context-dot-dev/context-go-sdk/v2"
    "github.com/context-dot-dev/context-go-sdk/v2/option"
)

func main() {
    client := contextdev.NewClient(
        option.WithAPIKey(os.Getenv("CONTEXT_DEV_API_KEY")),
    )

    file, err := os.Open("report.pdf")
    if err != nil {
        panic(err)
    }
    defer file.Close()

    // SDK 2.14.0 needs explicit query options for Parse.
    result, err := client.Parse.Handle(
        context.Background(),
        file,
        contextdev.ParseHandleParams{},
        option.WithQuery("extension", "pdf"),
        option.WithHeader("Content-Type", "application/pdf"),
    )
    if err != nil {
        panic(err)
    }

    fmt.Println(result.Markdown)
}

<?php

require __DIR__.'/vendor/autoload.php';

use ContextDev\Client;

$client = new Client(apiKey: getenv('CONTEXT_DEV_API_KEY'));

$bytes = file_get_contents('report.pdf');
if ($bytes === false) {
    throw new RuntimeException('Could not read report.pdf');
}

// Use the SDK's request method: the 2.14.0 Parse helper drops the body.
$raw = $client->request(
    method: 'post',
    path: 'parse',
    query: ['extension' => 'pdf'],
    headers: ['Content-Type' => 'application/pdf'],
    body: $bytes,
);

$result = json_decode((string) $raw->getBody(), true, flags: JSON_THROW_ON_ERROR);
echo $result['markdown'], PHP_EOL;

The request stays open until conversion finishes, then returns JSON:

{
  "success": true,
  "markdown": "# Quarterly Report\n\n## Summary\n\nRevenue grew 24% quarter over quarter…",
  "type": "pdf",
  "key_metadata": {
    "credits_consumed": 1,
    "credits_remaining": 499
  }
}

Field	Type	Description
`success`	boolean	`true` when the file was converted.
`markdown`	string	The converted Markdown.
`type`	string	The detected file type, such as `pdf`, `docx`, `xlsx`, `html`, `csv`, or `png`.
`key_metadata.credits_consumed`	integer	Credits charged for this request.
`key_metadata.credits_remaining`	integer	Credits left after the request.

Context.dev detects the type from the file contents. The returned type can differ from your hint: .xlsm reports xlsx, .ppsx reports pptx, and .jpeg reports jpg.

Supported formats

File	Markdown output
PDF, Word, and RTF	Structured sections for PDF and DOCX; paragraph text for legacy DOC and RTF
Excel, CSV, and TSV	Tables by sheet, or a fenced block when delimited data cannot be read as a table
PowerPoint	Slide sections with body text, tables, and speaker notes
HTML, XML, and feeds	Structured content with optional links and images
JSON, YAML, and SVG	Fenced blocks preserving the source data or markup
Text, Markdown, subtitles, and code	Preserved text, with language-tagged blocks for supported code formats
JPEG, PNG, GIF, BMP, TIFF, WebP, and Netpbm images	Image format and dimensions

Standalone image files return metadata, not OCR text. OCR is available for PDF pages without a usable text layer. See the Parse API reference for the complete extension list.

Read PDFs with OCR

OCR is off by default. Without OCR, PDFs are converted from their selectable text layer. A scanned PDF that paints images but has no selectable text returns a 400 PDF_IMAGES_ONLY response telling you the content is recoverable — retry with ocr=true. With ocr=true, Context.dev recovers selected pages that lack a usable text layer. Pages with readable text keep their existing text; this is not a general image-reading pass over every chart or screenshot. Use a page range to convert only the pages you need:

curl -X POST "https://api.context.dev/v1/parse?extension=pdf&ocr=true&pdf%5Bstart%5D=1&pdf%5Bend%5D=5" \
  -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  -H "Content-Type: application/pdf" \
  --data-binary @scanned-contract.pdf

import { readFile } from "node:fs/promises";
import ContextDev, { toFile } from "context.dev";

const client = new ContextDev({apiKey: process.env.CONTEXT_DEV_API_KEY});
const file = await toFile(await readFile("scanned-contract.pdf"), "scanned-contract.pdf", {
  type: "application/pdf",
});

const result = await client.parse.handle(file, {
  extension: "pdf",
  ocr: true,
  pdf: {
    start: 1,
    end: 5
  }
}, {
  headers: {"Content-Type": "application/pdf"},
});

console.log(result.markdown);

import os
from pathlib import Path
from context.dev import ContextDev

client = ContextDev(api_key=os.environ["CONTEXT_DEV_API_KEY"])

result = client.parse.handle(
    body=Path("scanned-contract.pdf").read_bytes(),
    extension="pdf",
    ocr=True,
    pdf={"start":1,"end":5},
    extra_headers={"Content-Type": "application/pdf"},
)

print(result.markdown)

require "cgi/core"
require "context_dev"

client = ContextDev::Client.new(api_key: ENV.fetch("CONTEXT_DEV_API_KEY"))

result = client.parse.handle(
  body: File.binread("scanned-contract.pdf"),
  extension: :pdf,
  ocr: true,
  pdf: {start: 1,end: 5},
  request_options: {extra_headers: {"Content-Type" => "application/pdf"}},
)

puts result.markdown

package main

import (
    "context"
    "fmt"
    "os"

    contextdev "github.com/context-dot-dev/context-go-sdk/v2"
    "github.com/context-dot-dev/context-go-sdk/v2/option"
)

func main() {
    client := contextdev.NewClient(
        option.WithAPIKey(os.Getenv("CONTEXT_DEV_API_KEY")),
    )

    file, err := os.Open("scanned-contract.pdf")
    if err != nil {
        panic(err)
    }
    defer file.Close()

    // SDK 2.14.0 needs explicit query options for Parse.
    result, err := client.Parse.Handle(
        context.Background(),
        file,
        contextdev.ParseHandleParams{},
        option.WithQuery("extension", "pdf"),
        option.WithQuery("ocr", "true"),
        option.WithQuery("pdf", "{\"start\":1,\"end\":5}"),
        option.WithHeader("Content-Type", "application/pdf"),
    )
    if err != nil {
        panic(err)
    }

    fmt.Println(result.Markdown)
}

<?php

require __DIR__.'/vendor/autoload.php';

use ContextDev\Client;

$client = new Client(apiKey: getenv('CONTEXT_DEV_API_KEY'));

$bytes = file_get_contents('scanned-contract.pdf');
if ($bytes === false) {
    throw new RuntimeException('Could not read scanned-contract.pdf');
}

// Use the SDK's request method: the 2.14.0 Parse helper drops the body.
$raw = $client->request(
    method: 'post',
    path: 'parse',
    query: ['extension' => 'pdf', 'ocr' => 'true', 'pdf' => ['start' => 1, 'end' => 5]],
    headers: ['Content-Type' => 'application/pdf'],
    body: $bytes,
);

$result = json_decode((string) $raw->getBody(), true, flags: JSON_THROW_ON_ERROR);
echo $result['markdown'], PHP_EOL;

In the URL above, pdf%5Bstart%5D and pdf%5Bend%5D are the URL-encoded forms of pdf[start] and pdf[end]. You can also send pdf as a URL-encoded JSON object such as {"start":1,"end":5}. OCR adds 1 credit per page it recovers. If OCR contributes no text, a successful conversion costs only the base credit. Failed parsing and validation requests consume 0 credits. Read key_metadata.credits_consumed for the actual charge. OCR can return partial recovery when a file reaches processing limits. Check the output before treating a document as complete, and use smaller files or page ranges for large scans. Zero data retention requests skip OCR and use the existing text layer in the PDF.

Control the output

All parsing options are query parameters. Send the file’s Content-Type when known, especially for non-UTF-8 text.

Parameter	Default	Behavior
`extension`	none	Lowercase hint without a dot, such as `pdf`, `docx`, or `xlsx`. Use a supported extension, not a filename.
`includeLinks`	`true`	Preserve hyperlinks in supported content.
`includeImages`	`false`	Include image references in supported content.
`shortenBase64Images`	`true`	Shorten inline base64 image data.
`useMainContentOnly`	`false`	Remove detected navigation and surrounding content from HTML-like inputs.
`ocr`	`false`	Recover PDF pages without a usable text layer.
`pdf`	full document	Set optional 1-based `start` and `end` pages, inclusive. `end` must be at least `start`.

Relative links and image paths stay relative because the file has no source URL. Unrecognized query parameters and repeated scalar parameters return 400.

Convert a spreadsheet or document

Point --data-binary at any supported file and pass its extension when useful. Excel workbooks become one Markdown table per non-empty sheet. DOCX files preserve headings, lists, and tables, while legacy DOC files return paragraph text.

curl -X POST "https://api.context.dev/v1/parse?extension=xlsx" \
  -H "Authorization: Bearer $CONTEXT_DEV_API_KEY" \
  -H "Content-Type: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet" \
  --data-binary @Q3-forecast.xlsx

import { readFile } from "node:fs/promises";
import ContextDev, { toFile } from "context.dev";

const client = new ContextDev({apiKey: process.env.CONTEXT_DEV_API_KEY});
const file = await toFile(await readFile("Q3-forecast.xlsx"), "Q3-forecast.xlsx", {
  type: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
});

const result = await client.parse.handle(file, {
  extension: "xlsx"
}, {
  headers: {"Content-Type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"},
});

console.log(result.markdown);

import os
from pathlib import Path
from context.dev import ContextDev

client = ContextDev(api_key=os.environ["CONTEXT_DEV_API_KEY"])

result = client.parse.handle(
    body=Path("Q3-forecast.xlsx").read_bytes(),
    extension="xlsx",
    extra_headers={"Content-Type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"},
)

print(result.markdown)

require "cgi/core"
require "context_dev"

client = ContextDev::Client.new(api_key: ENV.fetch("CONTEXT_DEV_API_KEY"))

result = client.parse.handle(
  body: File.binread("Q3-forecast.xlsx"),
  extension: :xlsx,
  request_options: {extra_headers: {"Content-Type" => "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"}},
)

puts result.markdown

package main

import (
    "context"
    "fmt"
    "os"

    contextdev "github.com/context-dot-dev/context-go-sdk/v2"
    "github.com/context-dot-dev/context-go-sdk/v2/option"
)

func main() {
    client := contextdev.NewClient(
        option.WithAPIKey(os.Getenv("CONTEXT_DEV_API_KEY")),
    )

    file, err := os.Open("Q3-forecast.xlsx")
    if err != nil {
        panic(err)
    }
    defer file.Close()

    // SDK 2.14.0 needs explicit query options for Parse.
    result, err := client.Parse.Handle(
        context.Background(),
        file,
        contextdev.ParseHandleParams{},
        option.WithQuery("extension", "xlsx"),
        option.WithHeader("Content-Type", "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"),
    )
    if err != nil {
        panic(err)
    }

    fmt.Println(result.Markdown)
}

<?php

require __DIR__.'/vendor/autoload.php';

use ContextDev\Client;

$client = new Client(apiKey: getenv('CONTEXT_DEV_API_KEY'));

$bytes = file_get_contents('Q3-forecast.xlsx');
if ($bytes === false) {
    throw new RuntimeException('Could not read Q3-forecast.xlsx');
}

// Use the SDK's request method: the 2.14.0 Parse helper drops the body.
$raw = $client->request(
    method: 'post',
    path: 'parse',
    query: ['extension' => 'xlsx'],
    headers: ['Content-Type' => 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'],
    body: $bytes,
);

$result = json_decode((string) $raw->getBody(), true, flags: JSON_THROW_ON_ERROR);
echo $result['markdown'], PHP_EOL;

Handle errors

Error responses include an error_code that distinguishes invalid input from files with no extractable content.

Status	`error_code`	Meaning	What to do
400	`INPUT_VALIDATION_ERROR`	The body is empty or a query parameter is invalid.	Attach the raw file bytes and use only the documented query parameters.
400	`WEBSITE_ACCESS_ERROR`	The file type was detected, but no content could be extracted.	Check that the file isn’t blank or corrupt. For a page range, confirm the pages exist.
400	`PDF_IMAGES_ONLY`	The PDF paints images but has no selectable text — it’s a scan.	Retry with `ocr=true` to recover the scanned pages (1 credit per recovered page).
401	Authentication or usage error	The API key is missing or invalid, or the account can’t cover the required credits.	Check the environment variable and available balance.
403	`FORBIDDEN`	The authenticated account isn’t allowed to complete the request.	Confirm that the key belongs to an active workspace with access to the API.
413	`INPUT_VALIDATION_ERROR`	The body is larger than 25 MiB.	Reduce or split the file before uploading it. A PDF page range doesn’t reduce the uploaded file size.
415	`UNSUPPORTED_CONTENT`	The bytes couldn’t be identified as a supported file type.	Check that the file is valid and supported, then provide its `extension` and `Content-Type` as hints.
429	`RATE_LIMITED`	The API-key rate limit was exceeded.	Wait for the rate-limit window to reset, then retry with backoff.

Build with an agent

Add document parsing to your app

Open in Cursor

Next steps

Build a PDF research workflow that keeps source identity, checks citations against retrieved text, and exposes incomplete evidence.

Scrape a webpage

Convert a public URL into Markdown.

Extract structured data

Pull schema-shaped data out of websites and linked documents.

Parse reference

Complete format list, options, and response schema.

Rate limits

Backoff strategies and pacing for high-volume jobs.

Get started

Web data

Brand data

Automation

Production

Parse PDFs and documents

Prerequisites

Convert a file to Markdown

Supported formats

Read PDFs with OCR

Control the output

Convert a spreadsheet or document

Handle errors

Next steps

Scrape a webpage

Extract structured data

Parse reference

Rate limits

​Prerequisites

​Convert a file to Markdown

​Supported formats

​Read PDFs with OCR

​Control the output

​Convert a spreadsheet or document

​Handle errors

​Next steps

Scrape a webpage

Extract structured data

Parse reference

Rate limits

Prerequisites

Convert a file to Markdown

Supported formats

Read PDFs with OCR

Control the output

Convert a spreadsheet or document

Handle errors

Next steps