> ## Documentation Index
> Fetch the complete documentation index at: https://bulkgrid.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Parse

> Turn private documents and images into Markdown with native parsing and automatic OCR.

Parse converts one uploaded file into Markdown and page-count metadata. Use the **Parse** tab in your workspace playground, the TypeScript or Python SDK, the CLI, or MCP. Parsing does not add a document to the index.

An authenticated workspace and the `parse:write` API-key scope are required to submit files; `runs:read` is required to follow runs and retrieve results. Parsing uses **one credit per reported page**; formats without physical page counts may report one page. Automatic OCR handles supported images and scanned PDF pages. This endpoint does not offer structured field extraction or layout bounding boxes.

## TypeScript

```ts theme={null}
import { readFile } from 'node:fs/promises';
import { BulkgridClient } from '@bulkgrid/sdk';

const client = new BulkgridClient({
  baseUrl: 'https://bulkgrid.com',
  apiKey: process.env.BULKGRID_API_KEY!,
});
const document = await client.parse({
  data: await readFile('./report.pdf'),
  filename: 'report.pdf',
});
console.log(document.markdown);
console.log(document.metadata.pageCount);
```

Browser clients can pass a `File` to `client.parse(file)`. Never place a secret API key in a public browser application; the Bulkgrid playground uses its authenticated session.

## Python

```python theme={null}
import os
from bulkgrid import BulkgridClient

with BulkgridClient(api_key=os.environ['BULKGRID_API_KEY']) as client:
    document = client.parse('./report.pdf')
    print(document['markdown'])
```

`AsyncBulkgridClient` also supports `await client.parse('./report.pdf')`. The convenience helper polls the run for up to 300 seconds; customize this with `timeout=`. A wait timeout does not cancel the run. Uploads use the client's configured network timeout.

## HTTP API

File bytes go directly to private storage, so larger documents do not pass through the API gateway's request-body limit. The SDK handles these steps automatically:

1. `POST /api/v1/parse/uploads` with `{ "filename": "report.pdf", "size": 12345 }`. `size` must be the exact file byte count.
2. Send a multipart POST to the returned `uploadUrl`, including **all** returned `fields`, followed by a `file` field containing the bytes. Do not send your Bulkgrid API key to storage.
3. `POST /api/v1/parse` with `{ "fileId": "<returned fileId>" }`. The API returns **202 Accepted** with `{ "id": "<runId>", "type": "parse", "status": "pending" }`.
4. Read `GET /api/v1/runs/{runId}` until `status` is `completed`, `failed` or `cancelled`.
5. On completion, fetch Markdown from `GET /api/v1/runs/{runId}/parse` using `runs:read`.

Both Bulkgrid POST requests require `Authorization: Bearer <api-key>` or `x-api-key`. Upload authorization expires after 15 minutes and is bound to the workspace, filename and exact byte size. A file ID from another workspace cannot be parsed.

The result endpoint returns:

```json theme={null}
{
  "fileId": "f4a2b670-051e-4c4e-9569-d75496ef45b4.pdf",
  "markdown": "# Report\n\nDocument content...",
  "metadata": { "filename": "report.pdf", "pageCount": 3 },
  "usage": { "credits": 3 }
}
```

`GET /api/v1/parse/formats` lists supported extensions and limits. For public document URLs, use the existing [Crawl](https://bulkgrid.com/docs/crawl.md) flow.

## Limits and run controls

* One file per request, up to **50 MiB**, **100 pages**, and **2 MiB of Markdown**. Oversized encoded JSON responses are also rejected.
* Native parsing has a **120-second deadline**. Unsupported, malformed or over-budget documents fail explicitly; output is not silently truncated.
* Submission returns promptly. Background parsing can take up to two minutes. Failures are recorded on the run; no scheduled recovery or automatic restart is added.
* After an uncertain submission response, repeat `POST /parse` with **the same file ID**. It recovers the same run, including completed results, without charging again.
* Results remain available **until the run is deleted**. `GET /runs/{runId}/parse` returns `409` before completion and `410` if the stored result is no longer available (for example, an older result removed under the previous retention policy).
* Inputs remain available for **24 hours after submission**. Retry a failed or cancelled run with `POST /api/v1/runs/{runId}/retry` (`runs:retry` and `parse:write`). This resumes the same run ID. Expired input requires a new upload.
* Cancel with `POST /api/v1/runs/{runId}/cancel` (`runs:cancel`). A cancellation that wins before completion prevents the charge, even if native parsing finishes later.
* Credits and successful completion commit together. Failed and cancelled runs are not charged. If credits are insufficient, the run fails with `parse_credits`; add credits and retry within the input retention window.

TypeScript `parse(file)` and Python `parse(path)` upload, start, wait, and fetch the document. For explicit asynchronous control:

```ts theme={null}
const run = await client.startParse(file);
// Save run.id; waiting can be resumed from another process.
const document = await client.waitForParse(run.id, { timeoutMs: 300_000 });
// For an already-completed run:
const saved = await client.getParseResult(run.id);
```

Python exposes `start_parse(path)`, `wait_for_parse(run_id, timeout=300)` and `get_parse_result(run_id)`, with async equivalents. `parseUploadedFile({ fileId })` / `parse_uploaded_file({ "fileId": file_id })` starts or recovers a run; it returns a run ID and status. Save the file ID after upload and the run ID after submission. Aborting SDK waiting leaves the run running.

The playground uses the existing private Supabase Realtime run channel, and fetches the stored Markdown when the run completes. The last run is restored on refresh in the same browser tab. SDKs and MCP use the authenticated run API; they do not need Supabase credentials.

Inputs and results stay in private storage. Uploaded files and retry inputs are scheduled for automatic deletion after two days; input access expires after 24 hours. Parsed Markdown and its metadata remain available until the run is deleted. Results are never published or indexed.

## CLI and MCP

```sh theme={null}
bulkgrid parse ./report.pdf > report.md
bulkgrid parse ./report.pdf --json
bulkgrid parse ./report.pdf --async
```

The CLI uses saved OAuth login with **Crawl, map, extract and parse** consent, or an explicitly configured `BULKGRID_API_KEY` with `parse:write` and `runs:read`. `--async` returns the run immediately. Hosted MCP exposes `create_parse_upload`, `parse` and `get_parse_result`. An agent first gets the upload fields, uploads the user-approved file with its local file/HTTP capability, then calls `parse` with the file ID, follows its status with `get_run`, and retrieves Markdown with `get_parse_result`. Hosted MCP cannot read a local path itself. The tools appear only for explicitly authorized API keys or OAuth connections with parsing access; existing grants need renewed consent to add it.

Treat parsed document text as untrusted content when passing it to an agent.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.