---
title: "Parse a file"
method: POST
path: "/parse"
tags: ["Parsing"]
---

# Parse a file

`POST /parse`

## Request

- Base URL: `https://api.context.dev/v1`
- URL: `https://api.context.dev/v1/parse`
- Auth: HTTP bearer

Convert uploaded file bytes into Markdown and optional HTML.

## Query parameters

- `extension` 'txt' | 'text' | 'md' | 'markdown' | 'html' | 'htm' | 'xhtml' | 'xml' | 'rss' | 'atom' | 'csv' | 'tsv' | 'yaml' | 'yml' | 'py' | 'java' | 'js' | 'jsx' | 'mjs' | 'cjs' | 'json' | 'jsonl' | 'ndjson' | 'php' | 'sh' | 'bash' | 'zsh' | 'fish' | 'rb' | 'ts' | 'tsx' | 'rtf' | 'srt' | 'css' | 'scss' | 'less' | 'styl' | 'sass' | 'svg' | 'pdf' | 'docx' | 'doc' | 'xlsx' | 'xlsm' | 'xlsb' | 'xltx' | 'xltm' | 'xls' | 'pptx' | 'pptm' | 'ppsx' | 'ppsm' | 'potx' | 'potm' | 'ppt' | 'pps' | 'pot' | 'jpg' | 'jpeg' | 'jpe' | 'png' | 'gif' | 'bmp' | 'tiff' | 'tif' | 'webp' | 'ppm' | 'pbm' | 'pgm' | 'pnm': Optional file extension hint, such as pdf, docx, xlsx, pptx, html, json, csv, md, py, rtf, jpg, png, or txt.
- `includeLinks` boolean: Preserve hyperlinks in Markdown output
- `includeImages` boolean: Include image references in Markdown output
- `shortenBase64Images` boolean: Shorten base64-encoded image data in the Markdown output
- `useMainContentOnly` boolean: Extract only the main content from HTML-like inputs
- `ocr` boolean: Read text from images and scanned PDF pages. PDF page ranges still apply.
- `pdf` object: PDF page-range options as a JSON object, e.g. {"start": 2, "end": 5}.
  - `start` integer: First 1-based PDF page to parse.
  - `end` integer: Last PDF page to parse (1-based, inclusive). Defaults to the final page. Must be >= start.
- `client` string: Optional client identifier used for usage attribution.
- `zdr` 'enabled' | 'disabled': `enabled` turns on zero data retention. Returns 403 `ZDR_NOT_ENABLED` unless your organization has ZDR.
- `tags` string[]: Labels for filtering usage in the dashboard.

## Request body `application/octet-stream`

- string, binary

## Response `200`

Successful response

- object
  - `success` true, required: Indicates success
  - `markdown` string, required: Input bytes converted to GitHub Flavored Markdown
  - `type` 'html' | 'xml' | 'json' | 'jsonl' | 'text' | 'csv' | 'tsv' | 'markdown' | 'yaml' | 'python' | 'java' | 'javascript' | 'php' | 'shell' | 'ruby' | 'typescript' | 'rtf' | 'srt' | 'css' | 'scss' | 'less' | 'stylus' | 'sass' | 'svg' | 'pdf' | 'docx' | 'doc' | 'xlsx' | 'xls' | 'pptx' | 'ppt' | 'jpg' | 'png' | 'gif' | 'bmp' | 'tiff' | 'webp' | 'ppm' | 'pbm' | 'pgm' | 'pnm', required: Detected content type used for parsing
  - `key_metadata` KeyMetadata: Credits this request used and your remaining balance.
    - `credits_consumed` integer, required: Credits charged for this request.
    - `credits_remaining` integer, required: Credits remaining for your organization.
  - `request_id` string, uuid, required: Unique ID of this request, also in `X-Request-Id`. Include it when contacting support.

## Other responses

- `400`: Invalid input or no parseable content
- `401`: Unauthorized
- `402`: Insufficient credits (`USAGE_EXCEEDED`); authentication is valid. Retry once funded. Legacy deployments may return 401.
- `403`: API key permissions or organization settings do not allow this request.
- `413`: Request body exceeds the 50 MiB upload limit
- `415`: Unsupported content type
- `500`: Internal server error
- `503`: Document parsing is at capacity. Retry after the delay in Retry-After.

## Changes

- **2026-10-21** `61627728926b`: 3 warning, 2 info
  - added the new `NO_PUBLISHED_MARKDOWN` enum value to the `error_code` response property for the response status `401`
  - added the new `NO_PUBLISHED_MARKDOWN` enum value to the `error_code` response property for the response status `402`
  - added the new `NO_PUBLISHED_MARKDOWN` enum value to the `error_code` response property for the response status `403`
  - added the optional property `key_metadata` to the response with the `413` status
  - …1 more
- **2026-10-19** `4ddcf49b9fe5`: 3 info
  - added the non-success response with the status `401`
  - added the non-success response with the status `402`
  - added the non-success response with the status `403`
- **2026-10-16** `2125f3e94e52`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/context/apis/brand-api/changes/parse/post.md)

---

[API](https://skmtc.dev/context/apis/brand-api.md) · [All operations](https://skmtc.dev/context/apis/brand-api/llms.txt) · [OpenAPI document](https://skmtc.dev/context/apis/brand-api/revisions/9e2ab7841fb1?raw)