# API Documentation

Cohesive offers common data extraction use cases, such as order data and metrics data, as **templates.** For maximum flexibility, you can define your own custom response schema.

{% hint style="info" %}
Cohesive support can assist you with setting up a custom response schema to fit your needs - let us know.
{% endhint %}

### API Overview

**Cohesive's API can be accessed at the base URL of <https://ocr.cohesiveapp.com>**. When making a request, be sure to include your provided API key as a `bearer token` in the request header.

Cohesive offers two options / endpoints for making a `POST` request. While both fundamentally work the same, the `upload_async` endpoint will send the extracted data as part of a webhook to a callback URL provided, whereas the `upload` endpoint returns the extracted data as part of an API response.

{% content-ref url="api-documentation/post-upload" %}
[post-upload](https://docs.cohesiveapp.com/reference/api-documentation/post-upload)
{% endcontent-ref %}

{% content-ref url="api-documentation/post-upload\_async" %}
[post-upload\_async](https://docs.cohesiveapp.com/reference/api-documentation/post-upload_async)
{% endcontent-ref %}

Typically, we recommend the `upload_async` endpoint if you expect to be uploading large files or if you already have implemented callback/webhook processing functionality.

{% hint style="info" %}
For small files (e.g., a typical contract/invoice or a financial statement), you can expect a response in under 30 seconds. However, for larger files, responses can take up to a minute.
{% endhint %}

### Cohesive Response Format

Cohesive's response will contain a `data` array that is an array of objects. Each object contains the following:

* `pageRange`: The page(s) that the extraction covers
* `extraction`: The extracted response, in the response schema specified, for the pages specified

Cohesive will attempt to process the entire file at once, in order to ensure that data extraction leverages the entire file context. For most files, the `pageRange` will be the entire document, meaning that the singular `extraction` covers the entire file.\
\
However, in the case of large files (e.g., a legal contract that is 50 pages long), Cohesive will break up the extraction into groups of different pages and return a response for each group.&#x20;

Here's what the response would look like for a very large file:

```
// Will return an array if the file is too large to process together
{
  "data": [
    {
      "pageRange": [
        0,
        1,
        2,
        3,
        4,
        5
      ],
      "extraction": null
    },
    {
      "pageRange": [
        6,
        7,
        8,
        9,
        10
      ],
      "extraction": null
    }
    ...
  }
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cohesiveapp.com/reference/api-documentation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.