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
File to client.parse(file). Never place a secret API key in a public browser application; the Bulkgrid playground uses its authenticated session.
Python
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:POST /api/v1/parse/uploadswith{ "filename": "report.pdf", "size": 12345 }.sizemust be the exact file byte count.- Send a multipart POST to the returned
uploadUrl, including all returnedfields, followed by afilefield containing the bytes. Do not send your Bulkgrid API key to storage. POST /api/v1/parsewith{ "fileId": "<returned fileId>" }. The API returns 202 Accepted with{ "id": "<runId>", "type": "parse", "status": "pending" }.- Read
GET /api/v1/runs/{runId}untilstatusiscompleted,failedorcancelled. - On completion, fetch Markdown from
GET /api/v1/runs/{runId}/parseusingruns:read.
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:
GET /api/v1/parse/formats lists supported extensions and limits. For public document URLs, use the existing Crawl 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 /parsewith 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}/parsereturns409before completion and410if 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:retryandparse: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.
parse(file) and Python parse(path) upload, start, wait, and fetch the document. For explicit asynchronous control:
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
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.