--- title: "Parse API (v2)" method: POST path: "/v2/parse" --- # Parse API (v2) `POST /v2/parse` Parse a document image into structured output. Use `output_format` to select blocks or markdown (default). Currently supports `document.type = image_url` only (data URI or remote http(s) image URL). PDF / file URL inputs are not yet supported. Image limits: 20 MB file size; 50 megapixels or 200 MB decoded (whichever is exceeded first). ## Headers - `X-Client-Name` string ## Request body - object - `model` string, required — The name of a compatible Cohere parse model. - `document` ParseDocument, required — Document to parse. Currently only `image_url` documents are supported. - `type` 'image_url', required — Discriminator for the document payload. - `image_url` string, required — Image URL or base64 data URI to parse. Limits: - Maximum file size: 20 MB (compressed upload, download, or decoded data-URI payload) - Maximum decoded size: 50 megapixels or 200 MB decompressed (whichever is exceeded first) - `output_format` 'blocks' | 'markdown' — Selects the page payload shape in the response. Defaults to `"markdown"`. - `"markdown"`: each page includes markdown content. Tables are inlined as HTML, and images are referenced as `![]()` with matching entries in `page.markdown.images`. - `"blocks"`: each page includes an ordered `blocks` array of text, image, and table content regions, including bounding boxes where available. ## Response `200` OK - ParseResponse — Response from the v2 parse endpoint. - `id` string, required — Unique identifier for the parse response. - `pages` ParsePage[], required — Parsed pages in document order. - union — A single parsed page. The payload shape depends on `output_format`. - object — A parsed page with structured content blocks. - `index` integer, required — Zero-based page index. - `type` 'blocks', required - `blocks` ParseBlock[], required — Ordered content blocks extracted from the page. - union — A content block on a parsed page. - object — A text content block. - … - object — An image content block. - … - object — A table content block. - … - object — A parsed page with markdown content. - `index` integer, required — Zero-based page index. - `type` 'markdown', required - `markdown` ParseMarkdownPage, required — Markdown output payload for a parsed page. - `content` string, required — Page content as markdown. Images are embedded as `![]()`. Tables are inlined as HTML. - `images` ParseImageBlock[] — Image metadata referenced from `content`. - `id` string, required — Unique identifier for the image within the page (for example `img-0`). - `description` string, required — Model-generated description of the image. - `category` 'other' | 'flowchart' | 'logo' | 'signature', required — Image element category. - `bounding_box` ParseBoundingBox, required — A bounding box with pixel coordinates on the source document image. - … - `bounding_box_normalized` ParseBoundingBoxNormalized, required — A bounding box with coordinates in [0, 1] relative to the source page (model coordinates are thousandths of page width/height). - … - `meta` ApiMeta - `api_version` object - `version` string, required - `is_deprecated` boolean - `is_experimental` boolean - `billed_units` object - `images` number — The number of billed images. - `input_tokens` number — The number of billed input tokens. - `image_tokens` number — The number of billed image tokens. - `output_tokens` number — The number of billed output tokens. - `search_units` number — The number of billed search units. - `classifications` number — The number of billed classifications units. - `pages` number — The number of billed pages parsed. - `tokens` object - `input_tokens` number — The number of tokens used as input to the model. - `output_tokens` number — The number of tokens produced by the model. - `cached_tokens` number — The number of prompt tokens that hit the inference cache. - `warnings` string[] ## Other responses - `400` — This error is returned when the request is not well formed. This could be because: - JSON is invalid - The request is missing required fields - The request contains an invalid combination of fields - `401` — This error indicates that the operation attempted to be performed is not allowed. This could be because: - The api token is invalid - The user does not have the necessary permissions - `403` — This error indicates that the operation attempted to be performed is not allowed. This could be because: - The api token is invalid - The user does not have the necessary permissions - `404` — This error is returned when a resource is not found. This could be because: - The endpoint does not exist - The resource does not exist eg model id, dataset id - `422` — This error is returned when the request is not well formed. This could be because: - JSON is invalid - The request is missing required fields - The request contains an invalid combination of fields - `429` — Too many requests - `498` — This error is returned when a request or response contains a deny-listed token. - `499` — This error is returned when a request is cancelled by the user. - `500` — This error is returned when an uncategorised internal server error occurs. - `501` — This error is returned when the requested feature is not implemented. - `503` — This error is returned when the service is unavailable. This could be due to: - Too many users trying to access the service at the same time - `504` — This error is returned when a request to the server times out. This could be due to: - An internal services taking too long to respond ## Changes - **2026-08-26** `3984870f15e5` — 1 info - endpoint added [Change history](https://skmtc.dev/cohere-ai/apis/api-reference/changes/v2/parse/post.md) --- [API](https://skmtc.dev/cohere-ai/apis/api-reference.md) · [All operations](https://skmtc.dev/cohere-ai/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/cohere-ai/api-reference/revisions/6f64ec87c66d/schema)