Parse API (v2)

POST/v2/parseParse API (v2)

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).

Parameters

X-Client-Namestringheader

The name of the project that is making the request.

Request body

required

application/json

object

documentobjectrequired

Document to parse. Currently only `image_url` documents are supported.

Show child attributes

image_urlstringrequired

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)

typestringrequired

Discriminator for the document payload.

one of "image_url"

modelstringrequired

The name of a compatible Cohere parse model.

output_formatstring

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 `![<description>](<image_id>)` 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.

one of "blocks", "markdown" · default "markdown"

Example request

{
  "document": {
    "image_url": "string",
    "type": "image_url"
  },
  "model": "string",
  "output_format": "markdown"
}

Responses

objectParseResponse

Response from the v2 parse endpoint.

finish_reasonstring

The reason a chat request has finished. - **complete**: The model finished sending a complete message. - **max_tokens**: The number of generated tokens exceeded the model's context length or the value specified via the `max_tokens` parameter. - **stop_sequence**: One of the provided `stop_sequence` entries was reached in the model's generation. - **tool_call**: The model generated a Tool Call and is expecting a Tool Message in return - **error**: The generation failed due to an internal error - **timeout**: The generation was stopped because it exceeded the allowed time limit.

one of "COMPLETE", "STOP_SEQUENCE", "MAX_TOKENS", "TOOL_CALL", "ERROR", "TIMEOUT"

idstringrequired

Unique identifier for the parse response.

metaobject

Show child attributes

api_versionobject

Show child attributes

is_deprecatedboolean

is_experimentalboolean

versionstringrequired

billed_unitsobject

Show child attributes

classificationsnumber

The number of billed classifications units.

image_tokensnumber

The number of billed image tokens.

imagesnumber

The number of billed images.

input_tokensnumber

The number of billed input tokens.

output_tokensnumber

The number of billed output tokens.

pagesnumber

The number of billed pages parsed.

search_unitsnumber

The number of billed search units.

cached_tokensnumber

The number of prompt tokens that hit the inference cache.

tokensobject

Show child attributes

input_tokensnumber

The number of tokens used as input to the model.

output_tokensnumber

The number of tokens produced by the model.

warningsarray of string

Show child attributes

pagesarray of valuerequired

Parsed pages in document order.

Show child attributes

Show array items

A single parsed page. The payload shape depends on `output_format`.

oneOf · 2 options

Option 1objectParseBlocksPageVariant

A parsed page with structured content blocks.

blocksarray of valuerequired

Ordered content blocks extracted from the page.

Show child attributes

Show array items

A content block on a parsed page.

oneOf · 3 options

Option 1objectParseTextContentBlock

A text content block.

textobjectrequired

Payload for a text block.

Show child attributes

contentstringrequired

Extracted text content.

typestringrequired

one of "text"

Option 2objectParseImageContentBlock

An image content block.

imageobjectrequired

Payload for an image block.

Show child attributes

bounding_boxobjectrequired

A bounding box with pixel coordinates on the source document image.

Show child attributes

bottom_right_xintegerrequired

X coordinate of the bottom-right corner.

bottom_right_yintegerrequired

Y coordinate of the bottom-right corner.

top_left_xintegerrequired

X coordinate of the top-left corner.

top_left_yintegerrequired

Y coordinate of the top-left corner.

bounding_box_normalizedobjectrequired

A bounding box with coordinates in [0, 1] relative to the source page (model coordinates are thousandths of page width/height).

Show child attributes

bottom_right_xnumber · doublerequired

Normalized X coordinate of the bottom-right corner.

bottom_right_ynumber · doublerequired

Normalized Y coordinate of the bottom-right corner.

top_left_xnumber · doublerequired

Normalized X coordinate of the top-left corner.

top_left_ynumber · doublerequired

Normalized Y coordinate of the top-left corner.

categorystringrequired

Image element category.

one of "other", "flowchart", "logo", "signature"

descriptionstringrequired

Model-generated description of the image.

idstringrequired

Unique identifier for the image within the page (for example `img-0`).

typestringrequired

one of "image"

Option 3objectParseTableContentBlock

A table content block.

tableobjectrequired

Payload for a table block.

Show child attributes

bounding_boxobjectrequiredParseBoundingBox ↑

A bounding box with pixel coordinates on the source document image.

bounding_box_normalizedobjectrequiredParseBoundingBoxNormalized ↑

A bounding box with coordinates in [0, 1] relative to the source page (model coordinates are thousandths of page width/height).

descriptionstring

Optional table description when detected.

htmlstringrequired

Table content as HTML.

titlestring

Optional table title when detected.

typestringrequired

Table serialization format.

one of "html"

typestringrequired

one of "table"

indexintegerrequired

Zero-based page index.

typestringrequired

one of "blocks"

Option 2objectParseMarkdownPageVariant

A parsed page with markdown content.

indexintegerrequired

Zero-based page index.

markdownobjectrequired

Markdown output payload for a parsed page.

Show child attributes

contentstringrequired

Page content as markdown. Images are embedded as `![<description>](<image_id>)`. Tables are inlined as HTML.

imagesarray of object

Image metadata referenced from `content`.

Show child attributes

Items: ParseImageBlock ↑

typestringrequired

one of "markdown"

Example response

{
  "finish_reason": "COMPLETE",
  "id": "string",
  "meta": {
    "api_version": {
      "is_deprecated": true,
      "is_experimental": true,
      "version": "string"
    },
    "billed_units": {
      "classifications": 0,
      "image_tokens": 0,
      "images": 0,
      "input_tokens": 0,
      "output_tokens": 0,
      "pages": 0,
      "search_units": 0
    },
    "cached_tokens": 0,
    "tokens": {
      "input_tokens": 0,
      "output_tokens": 0
    },
    "warnings": [
      "string"
    ]
  },
  "pages": [
    {
      "blocks": [
        {
          "image": {
            "bounding_box": {
              "bottom_right_x": 0,
              "bottom_right_y": 0,
              "top_left_x": 0,
              "top_left_y": 0
            },
            "bounding_box_normalized": {
              "bottom_right_x": 0,
              "bottom_right_y": 0,
              "top_left_x": 0,
              "top_left_y": 0
            },
            "category": "flowchart",
            "description": "string",
            "id": "string"
          },
          "type": "image"
        }
      ],
      "index": 0,
      "type": "blocks"
    }
  ]
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

object

idstring

messagestring

Example response

{
  "id": "string",
  "message": "string"
}

Examples

X-Client-Nameheader parameter

curl -X POST 'https://api.cohere.com/v2/parse' \
  -H 'Content-Type: application/json' \
  -d '{"document":{"image_url":"string","type":"image_url"},"model":"string","output_format":"markdown"}'

const response = await fetch('https://api.cohere.com/v2/parse', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({"document":{"image_url":"string","type":"image_url"},"model":"string","output_format":"markdown"}),
});
const data = await response.json();

const response = await fetch('https://api.cohere.com/v2/parse', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: "{\"document\":{\"image_url\":\"string\",\"type\":\"image_url\"},\"model\":\"string\",\"output_format\":\"markdown\"}" });
console.log(await response.json());

import requests

response = requests.request(
    "POST",
    "https://api.cohere.com/v2/parse",
    headers={"Content-Type": "application/json"},
    data='{"document":{"image_url":"string","type":"image_url"},"model":"string","output_format":"markdown"}',
)
print(response.json())

package main

import (
	"context"
	"net/http"
	"strings"
)

func main() {
	ctx := context.Background()
	body := strings.NewReader(`{"document":{"image_url":"string","type":"image_url"},"model":"string","output_format":"markdown"}`)
	req, err := http.NewRequestWithContext(ctx, "POST", "https://api.cohere.com/v2/parse", body)
	if err != nil {
		panic(err)
	}
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
}

<?php
$request = curl_init("https://api.cohere.com/v2/parse");
curl_setopt($request, CURLOPT_CUSTOMREQUEST, "POST");
curl_setopt($request, CURLOPT_POSTFIELDS, "{\"document\":{\"image_url\":\"string\",\"type\":\"image_url\"},\"model\":\"string\",\"output_format\":\"markdown\"}");
curl_setopt($request, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
$response = curl_exec($request);
curl_close($request);

var request = HttpRequest.newBuilder(URI.create("https://api.cohere.com/v2/parse"))
    .method("POST", HttpRequest.BodyPublishers.noBody())
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"document\":{\"image_url\":\"string\",\"type\":\"image_url\"},\"model\":\"string\",\"output_format\":\"markdown\"}"))
    .build();
var response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());

require 'net/http'

uri = URI("https://api.cohere.com/v2/parse")
request = Net::HTTPGenericRequest.new("POST", true, true, uri)
request['Content-Type'] = 'application/json'
request.body = "{\"document\":{\"image_url\":\"string\",\"type\":\"image_url\"},\"model\":\"string\",\"output_format\":\"markdown\"}"
response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(request) }

using var client = new HttpClient();
using var request = new HttpRequestMessage(HttpMethod.Post, "https://api.cohere.com/v2/parse");
request.Content = new StringContent("{\"document\":{\"image_url\":\"string\",\"type\":\"image_url\"},\"model\":\"string\",\"output_format\":\"markdown\"}", Encoding.UTF8, "application/json");
using var response = await client.SendAsync(request);

{
  "finish_reason": "COMPLETE",
  "id": "string",
  "meta": {
    "api_version": {
      "is_deprecated": true,
      "is_experimental": true,
      "version": "string"
    },
    "billed_units": {
      "classifications": 0,
      "image_tokens": 0,
      "images": 0,
      "input_tokens": 0,
      "output_tokens": 0,
      "pages": 0,
      "search_units": 0
    },
    "cached_tokens": 0,
    "tokens": {
      "input_tokens": 0,
      "output_tokens": 0
    },
    "warnings": [
      "string"
    ]
  },
  "pages": [
    {
      "blocks": [
        {
          "image": {
            "bounding_box": {
              "bottom_right_x": 0,
              "bottom_right_y": 0,
              "top_left_x": 0,
              "top_left_y": 0
            },
            "bounding_box_normalized": {
              "bottom_right_x": 0,
              "bottom_right_y": 0,
              "top_left_x": 0,
              "top_left_y": 0
            },
            "category": "flowchart",
            "description": "string",
            "id": "string"
          },
          "type": "image"
        }
      ],
      "index": 0,
      "type": "blocks"
    }
  ]
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

{
  "id": "string",
  "message": "string"
}

Search documentation

/datasets

/connectors

/embed-jobs

/finetuning

/models

/audio/transcriptions

/batches

Operations

Parse API (v2)

Parameters

Request body

Responses

/datasets

/connectors

/embed-jobs

/finetuning

/models

/audio/transcriptions

/batches

Operations