> ## Documentation Index
> Fetch the complete documentation index at: https://docs.matil.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Document input

> How to format documents in your API requests.

Every processing request includes a `documents` array. Each document must have a `type` field that determines how Matil receives the content.

## URL

Send a direct download link. Matil fetches the file and processes it.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "documents": [
    {
      "type": "url",
      "url": "https://example.com/invoice.pdf"
    }
  ]
}
```

<Warning>
  The URL must point directly to the file. Links that require authentication, redirect to a login page, or return HTML instead of the file will fail with a `400` error. For services like Google Drive or Dropbox, use the direct download URL, not the sharing link.
</Warning>

## Base64

Send the file content encoded in base64. Always include `mime_type` so Matil knows how to process the file.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "documents": [
    {
      "type": "base64",
      "content": "JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZw...",
      "mime_type": "application/pdf",
      "filename": "invoice.pdf"
    }
  ]
}
```

| Field       | Required | Description                                                                           |
| ----------- | -------- | ------------------------------------------------------------------------------------- |
| `content`   | Yes      | The base64-encoded file content.                                                      |
| `mime_type` | No       | MIME type of the file (e.g. `application/pdf`, `image/png`). Strongly recommended.    |
| `filename`  | No       | Original filename. Helps Matil detect the file type when `mime_type` is not provided. |

<Warning>
  Send only the raw base64 string. Do not include the `data:application/pdf;base64,` prefix — that is a Data URI format used in browsers, not in API requests.
</Warning>

### Encoding a file to base64

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import base64

  with open("invoice.pdf", "rb") as f:
      content = base64.b64encode(f.read()).decode("utf-8")

  # Use in your request
  document = {
      "type": "base64",
      "content": content,
      "mime_type": "application/pdf",
      "filename": "invoice.pdf"
  }
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import fs from "fs";

  const content = fs.readFileSync("invoice.pdf").toString("base64");

  // Use in your request
  const document = {
    type: "base64",
    content: content,
    mime_type: "application/pdf",
    filename: "invoice.pdf"
  };
  ```

  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  # Encode and send in one command
  curl -X POST "https://api.matil.ai/v3/deployments/{deployment_id}" \
    -H "x-api-key: your-api-key" \
    -H "Content-Type: application/json" \
    -d "{
      \"documents\": [{
        \"type\": \"base64\",
        \"content\": \"$(base64 -i invoice.pdf)\",
        \"mime_type\": \"application/pdf\",
        \"filename\": \"invoice.pdf\"
      }]
    }"
  ```

  ```csharp C# theme={"theme":{"light":"github-light","dark":"github-dark"}}
  byte[] bytes = File.ReadAllBytes("invoice.pdf");
  string content = Convert.ToBase64String(bytes);

  var document = new {
      type = "base64",
      content = content,
      mime_type = "application/pdf",
      filename = "invoice.pdf"
  };
  ```

  ```java Java theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import java.nio.file.Files;
  import java.nio.file.Path;
  import java.util.Base64;

  byte[] bytes = Files.readAllBytes(Path.of("invoice.pdf"));
  String content = Base64.getEncoder().encodeToString(bytes);
  ```
</CodeGroup>

## Text

Send plain text directly. This is useful for passing additional instructions or context alongside other documents, or for processing text that you already have extracted.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "documents": [
    {
      "type": "url",
      "url": "https://example.com/invoice.pdf"
    },
    {
      "type": "text",
      "text": "The invoice currency is USD. The supplier VAT ID is ES12345678A."
    }
  ]
}
```

In this example, the first document is the actual file and the second provides extra context that helps Matil extract the data more accurately.

## Multiple documents

You can send multiple documents in a single request. Matil processes them together as a single unit.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "documents": [
    {
      "type": "url",
      "url": "https://example.com/invoice-page1.pdf"
    },
    {
      "type": "url",
      "url": "https://example.com/invoice-page2.pdf"
    }
  ]
}
```

## Per-document metadata

Each document accepts an optional `metadata` object for your own tracking:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "documents": [
    {
      "type": "url",
      "url": "https://example.com/invoice.pdf",
      "metadata": {"source": "email", "sender": "supplier@example.com"}
    }
  ]
}
```