> This page is for version v2 API (default).
> For other versions, use one of these documentation indexes:
> - v2 API (default): https://docs.cohere.com/v2/llms.txt
> - v1 API: https://docs.cohere.com/v1/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.cohere.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.cohere.com/_mcp/server.

# Parse

POST https://api.cohere.com/v2/parse
Content-Type: application/json

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


Reference: https://docs.cohere.com/reference/parse

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Headers

- `X-Client-Name` (string, optional) — The name of the project that is making the request.

### Body (application/json)

This endpoint expects an 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.
- `output_format` (enum, optional, default: 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 `![<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.
  - Allowed values: `blocks`, `markdown`

## Response

### 200

OK

- `id` (string, required) — Unique identifier for the parse response.
- `pages` (list of ParsePage, required) — Parsed pages in document order.
- `meta` (ApiMeta, optional)
- `finish_reason` (enum, optional) — The reason parsing finished. For Parse, this is only ever `COMPLETE` or `MAX_TOKENS`; `MAX_TOKENS` indicates the output was truncated because it exceeded the maximum output token limit.
  - Allowed values: `COMPLETE`, `STOP_SEQUENCE`, `MAX_TOKENS`, `TOOL_CALL`, `ERROR`, `TIMEOUT`

## Errors

### 400 Bad Request Error

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

- `message` (string, optional)
- `id` (string, optional)

### 401 Unauthorized Error

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

- `message` (string, optional)
- `id` (string, optional)

### 403 Forbidden Error

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

- `message` (string, optional)
- `id` (string, optional)

### 404 Not Found Error

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

- `message` (string, optional)
- `id` (string, optional)

### 422 Unprocessable Entity Error

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

- `message` (string, optional)
- `id` (string, optional)

### 429 Too Many Requests Error

Too many requests

- `message` (string, optional)
- `id` (string, optional)

### 498 Invalid Token Error

This error is returned when a request or response contains a deny-listed token.

- `message` (string, optional)
- `id` (string, optional)

### 499 Client Closed Request Error

This error is returned when a request is cancelled by the user.

- `message` (string, optional)
- `id` (string, optional)

### 500 Internal Server Error

This error is returned when an uncategorised internal server error occurs.

- `message` (string, optional)
- `id` (string, optional)

### 501 Not Implemented Error

This error is returned when the requested feature is not implemented.

- `message` (string, optional)
- `id` (string, optional)

### 503 Service Unavailable Error

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

- `message` (string, optional)
- `id` (string, optional)

### 504 Gateway Timeout Error

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

- `message` (string, optional)
- `id` (string, optional)

## Types

### ParseDocument

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

- `type` (enum, required) — Discriminator for the document payload.
  - Allowed values: `image_url`
- `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)

### ParsePage

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

- `type`: `blocks` (blocks)
  - `blocks` (list of ParseBlock, required) — Ordered content blocks extracted from the page.
  - `index` (integer, required) — Zero-based page index.
- `type`: `markdown` (markdown)
  - `index` (integer, required) — Zero-based page index.
  - `markdown` (ParseMarkdownPage, required) — Markdown output payload for a parsed page.

### ApiMeta

- `api_version` (ApiMetaApiVersion, optional)
- `billed_units` (ApiMetaBilledUnits, optional)
- `tokens` (ApiMetaTokens, optional)
- `cached_tokens` (double, optional) — The number of prompt tokens that hit the inference cache.
- `warnings` (list of string, optional)

### ParseBlock

A content block on a parsed page.

- `type`: `text` (text)
  - `text` (ParseTextBlock, required) — Payload for a text block.
- `type`: `image` (image)
  - `image` (ParseImageBlock, required) — Payload for an image block.
- `type`: `table` (table)
  - `table` (ParseTableBlock, required) — Payload for a table block.

### ParseMarkdownPage

Markdown output payload for a parsed page.

- `content` (string, required) — Page content as markdown. Images are embedded as `![<description>](<image_id>)`. Tables are inlined as HTML.
- `images` (list of ParseImageBlock, optional) — Image metadata referenced from `content`.

### ApiMetaApiVersion

- `version` (string, required)
- `is_deprecated` (boolean, optional)
- `is_experimental` (boolean, optional)

### ApiMetaBilledUnits

- `images` (double, optional) — The number of billed images.
- `input_tokens` (double, optional) — The number of billed input tokens.
- `image_tokens` (double, optional) — The number of billed image tokens.
- `output_tokens` (double, optional) — The number of billed output tokens.
- `search_units` (double, optional) — The number of billed search units.
- `classifications` (double, optional) — The number of billed classifications units.
- `pages` (double, optional) — The number of billed pages parsed.

### ApiMetaTokens

- `input_tokens` (double, optional) — The number of tokens used as input to the model.
- `output_tokens` (double, optional) — The number of tokens produced by the model.

### ParseTextBlock

Payload for a text block.

- `content` (string, required) — Extracted text content.

### ParseImageBlock

Payload for an image block.

- `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` (enum, required) — Image element category.
  - Allowed values: `other`, `flowchart`, `logo`, `signature`
- `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).

### ParseTableBlock

Payload for a table block.

- `type` (enum, required) — Table serialization format.
  - Allowed values: `html`
- `html` (string, required) — Table content as HTML.
- `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).
- `title` (string, optional) — Optional table title when detected.
- `description` (string, optional) — Optional table description when detected.

### ParseBoundingBox

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

- `top_left_x` (integer, required) — X coordinate of the top-left corner.
- `top_left_y` (integer, required) — Y coordinate of the top-left corner.
- `bottom_right_x` (integer, required) — X coordinate of the bottom-right corner.
- `bottom_right_y` (integer, required) — Y coordinate of the bottom-right corner.

### ParseBoundingBoxNormalized

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

- `top_left_x` (double, required) — Normalized X coordinate of the top-left corner.
- `top_left_y` (double, required) — Normalized Y coordinate of the top-left corner.
- `bottom_right_x` (double, required) — Normalized X coordinate of the bottom-right corner.
- `bottom_right_y` (double, required) — Normalized Y coordinate of the bottom-right corner.

## Examples

### Markdown

**Request**

```json
{
  "model": "parse-v5.0",
  "document": {
    "type": "image_url",
    "image_url": "https://cohere.com/favicon-32x32.png"
  },
  "output_format": "markdown"
}
```

**Response**

```json
{
  "id": "8f2a1c3e-4b5d-6e7f-8091-a2b3c4d5e6f7",
  "pages": [
    {
      "type": "markdown",
      "index": 0,
      "markdown": {
        "content": "# Sample Document\n\nCohere builds AI that understands language.\n\n![Company logo](img-0)\n",
        "images": [
          {
            "id": "img-0",
            "description": "Company logo",
            "category": "logo",
            "bounding_box": {
              "top_left_x": 12,
              "top_left_y": 8,
              "bottom_right_x": 48,
              "bottom_right_y": 44
            },
            "bounding_box_normalized": {
              "top_left_x": 0.04,
              "top_left_y": 0.03,
              "bottom_right_x": 0.15,
              "bottom_right_y": 0.14
            }
          }
        ]
      }
    }
  ],
  "meta": {
    "api_version": {
      "version": "2"
    },
    "billed_units": {
      "pages": 1
    }
  }
}
```

**SDK Code**

```go Markdown
package main

import (
	"context"
	"log"
	"os"

	cohere "github.com/cohere-ai/cohere-go/v2"
	"github.com/cohere-ai/cohere-go/v2/client"
)

func main() {
	co := client.NewClient(client.WithToken(os.Getenv("CO_API_KEY")))

	resp, err := co.V2.Parse(
		context.TODO(),
		&cohere.ParseRequest{
			Model: "parse-v5.0",
			Document: &cohere.ParseDocument{
				ImageUrl: "https://cohere.com/favicon-32x32.png",
			},
			OutputFormat: cohere.ParseOutputFormatMarkdown.Ptr(),
		},
	)
	if err != nil {
		log.Fatal(err)
	}

	log.Printf("%+v", resp)
}

```

```typescript Markdown
import { CohereClient } from 'cohere-ai';

const cohere = new CohereClient({});

(async () => {
  const response = await cohere.v2.parse({
    model: 'parse-v5.0',
    document: {
      type: 'image_url',
      imageUrl: 'https://cohere.com/favicon-32x32.png',
    },
    outputFormat: 'markdown',
  });
  console.log(response);
})();

```

```python Markdown
import cohere

co = cohere.ClientV2()

response = co.parse(
    model="parse-v5.0",
    document={
        "type": "image_url",
        "image_url": "https://cohere.com/favicon-32x32.png",
    },
    output_format="markdown",
)

print(response)

```

```python Markdown (async)
import asyncio

import cohere

co = cohere.AsyncClientV2()


async def main():
    response = await co.parse(
        model="parse-v5.0",
        document={
            "type": "image_url",
            "image_url": "https://cohere.com/favicon-32x32.png",
        },
        output_format="markdown",
    )
    print(response)


asyncio.run(main())

```

```java Markdown
package parsev2post; /* (C)2024 */

import com.cohere.api.Cohere;
import com.cohere.api.resources.v2.requests.ParseRequest;
import com.cohere.api.types.ParseDocument;
import com.cohere.api.types.ParseOutputFormat;
import com.cohere.api.types.ParseResponse;

public class Markdown {
  public static void main(String[] args) {
    Cohere cohere = Cohere.builder().clientName("snippet").build();

    ParseResponse response =
        cohere
            .v2()
            .parse(
                ParseRequest.builder()
                    .model("parse-v5.0")
                    .document(
                        ParseDocument.builder()
                            .imageUrl("https://cohere.com/favicon-32x32.png")
                            .build())
                    .outputFormat(ParseOutputFormat.MARKDOWN)
                    .build());

    System.out.println(response);
  }
}

```

```ruby Markdown
require 'uri'
require 'net/http'

url = URI("https://api.cohere.com/v2/parse")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"parse-v5.0\",\n  \"document\": {\n    \"type\": \"image_url\",\n    \"image_url\": \"https://cohere.com/favicon-32x32.png\"\n  },\n  \"output_format\": \"markdown\"\n}"

response = http.request(request)
puts response.read_body
```

```php Markdown
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cohere.com/v2/parse', [
  'body' => '{
  "model": "parse-v5.0",
  "document": {
    "type": "image_url",
    "image_url": "https://cohere.com/favicon-32x32.png"
  },
  "output_format": "markdown"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Markdown
using RestSharp;

var client = new RestClient("https://api.cohere.com/v2/parse");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"model\": \"parse-v5.0\",\n  \"document\": {\n    \"type\": \"image_url\",\n    \"image_url\": \"https://cohere.com/favicon-32x32.png\"\n  },\n  \"output_format\": \"markdown\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Markdown
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "model": "parse-v5.0",
  "document": [
    "type": "image_url",
    "image_url": "https://cohere.com/favicon-32x32.png"
  ],
  "output_format": "markdown"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cohere.com/v2/parse")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Blocks

**Request**

```json
{
  "model": "parse-v5.0",
  "document": {
    "type": "image_url",
    "image_url": "https://cohere.com/favicon-32x32.png"
  },
  "output_format": "blocks"
}
```

**Response**

```json
{
  "id": "1a2b3c4d-5e6f-7081-92a3-b4c5d6e7f809",
  "pages": [
    {
      "type": "blocks",
      "blocks": [
        {
          "type": "text",
          "text": {
            "content": "# Sample Document\n\nCohere builds AI that understands language."
          }
        },
        {
          "type": "image",
          "image": {
            "id": "img-0",
            "description": "Company logo",
            "category": "logo",
            "bounding_box": {
              "top_left_x": 12,
              "top_left_y": 8,
              "bottom_right_x": 48,
              "bottom_right_y": 44
            },
            "bounding_box_normalized": {
              "top_left_x": 0.04,
              "top_left_y": 0.03,
              "bottom_right_x": 0.15,
              "bottom_right_y": 0.14
            }
          }
        }
      ],
      "index": 0
    }
  ],
  "meta": {
    "api_version": {
      "version": "2"
    },
    "billed_units": {
      "pages": 1
    }
  }
}
```

**SDK Code**

```go Blocks
package main

import (
	"context"
	"log"
	"os"

	cohere "github.com/cohere-ai/cohere-go/v2"
	"github.com/cohere-ai/cohere-go/v2/client"
)

func main() {
	co := client.NewClient(client.WithToken(os.Getenv("CO_API_KEY")))

	resp, err := co.V2.Parse(
		context.TODO(),
		&cohere.ParseRequest{
			Model: "parse-v5.0",
			Document: &cohere.ParseDocument{
				ImageUrl: "https://cohere.com/favicon-32x32.png",
			},
			OutputFormat: cohere.ParseOutputFormatBlocks.Ptr(),
		},
	)
	if err != nil {
		log.Fatal(err)
	}

	log.Printf("%+v", resp)
}

```

```typescript Blocks
import { CohereClient } from 'cohere-ai';

const cohere = new CohereClient({});

(async () => {
  const response = await cohere.v2.parse({
    model: 'parse-v5.0',
    document: {
      type: 'image_url',
      imageUrl: 'https://cohere.com/favicon-32x32.png',
    },
    outputFormat: 'blocks',
  });
  console.log(response);
})();

```

```python Blocks
import cohere

co = cohere.ClientV2()

response = co.parse(
    model="parse-v5.0",
    document={
        "type": "image_url",
        "image_url": "https://cohere.com/favicon-32x32.png",
    },
    output_format="blocks",
)

print(response)

```

```python Blocks (async)
import asyncio

import cohere

co = cohere.AsyncClientV2()


async def main():
    response = await co.parse(
        model="parse-v5.0",
        document={
            "type": "image_url",
            "image_url": "https://cohere.com/favicon-32x32.png",
        },
        output_format="blocks",
    )
    print(response)


asyncio.run(main())

```

```java Blocks
package parsev2post; /* (C)2024 */

import com.cohere.api.Cohere;
import com.cohere.api.resources.v2.requests.ParseRequest;
import com.cohere.api.types.ParseDocument;
import com.cohere.api.types.ParseOutputFormat;
import com.cohere.api.types.ParseResponse;

public class Blocks {
  public static void main(String[] args) {
    Cohere cohere = Cohere.builder().clientName("snippet").build();

    ParseResponse response =
        cohere
            .v2()
            .parse(
                ParseRequest.builder()
                    .model("parse-v5.0")
                    .document(
                        ParseDocument.builder()
                            .imageUrl("https://cohere.com/favicon-32x32.png")
                            .build())
                    .outputFormat(ParseOutputFormat.BLOCKS)
                    .build());

    System.out.println(response);
  }
}

```

```ruby Blocks
require 'uri'
require 'net/http'

url = URI("https://api.cohere.com/v2/parse")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model\": \"parse-v5.0\",\n  \"document\": {\n    \"type\": \"image_url\",\n    \"image_url\": \"https://cohere.com/favicon-32x32.png\"\n  },\n  \"output_format\": \"blocks\"\n}"

response = http.request(request)
puts response.read_body
```

```php Blocks
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.cohere.com/v2/parse', [
  'body' => '{
  "model": "parse-v5.0",
  "document": {
    "type": "image_url",
    "image_url": "https://cohere.com/favicon-32x32.png"
  },
  "output_format": "blocks"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Blocks
using RestSharp;

var client = new RestClient("https://api.cohere.com/v2/parse");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"model\": \"parse-v5.0\",\n  \"document\": {\n    \"type\": \"image_url\",\n    \"image_url\": \"https://cohere.com/favicon-32x32.png\"\n  },\n  \"output_format\": \"blocks\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Blocks
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "model": "parse-v5.0",
  "document": [
    "type": "image_url",
    "image_url": "https://cohere.com/favicon-32x32.png"
  ],
  "output_format": "blocks"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.cohere.com/v2/parse")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```