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

# Processing modes

> Synchronous, asynchronous, and batch processing.

Matil offers three ways to process documents through a deployment. All three use the same document input format and return the same result structure.

## Synchronous

The request blocks until processing completes. The result is returned directly in the response.

```
POST /v3/deployments/{deployment_id}
```

Use this when you need the result immediately and can wait for the response (typically 1-10 seconds).

## Asynchronous

The request returns immediately with an `entry_id` and `status: "pending"`. The result is delivered to your webhook URL when ready.

```
POST /v3/deployments/{deployment_id}/async
```

Include a `webhook` object in the request body:

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

Use this when you don't need the result immediately and want to decouple submission from result handling.

## Batch

Submit up to 100 items in a single request. Returns a `batch_id` and total item count. Results are delivered via webhook.

```
POST /v3/deployments/{deployment_id}/batch
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "requests": [
    {
      "metadata": {"order_id": "ORD-001"},
      "documents": [{"type": "url", "url": "https://example.com/invoice-1.pdf"}]
    },
    {
      "metadata": {"order_id": "ORD-002"},
      "documents": [{"type": "url", "url": "https://example.com/invoice-2.pdf"}]
    }
  ],
  "webhook": {
    "url": "https://your-server.com/webhook",
    "secret": "your-webhook-secret",
    "incremental": true
  }
}
```

The `incremental` flag controls delivery:

| Value   | Behavior                                                 |
| ------- | -------------------------------------------------------- |
| `true`  | A webhook is sent as each item completes.                |
| `false` | A single webhook is sent when the entire batch finishes. |

Check batch progress at any time:

```
GET /v3/batches/{batch_id}
```