Endpoints

Process (async)

Send one or more documents for processing and receive the result later via webhook.

Returns immediately with an entry_id and status: "pending". When processing completes, Matil sends a POST request to your webhook URL with the result.

Request body

documents (required): Array of document objects.
webhook (required): Object with url (your endpoint), secret (optional, for HMAC signature verification), and incremental (optional, defaults to true).
metadata (optional): Custom key-value object stored with the result.

Webhook events

structurer.completed: Processing succeeded. Payload contains the extracted data.
structurer.failed: Processing failed. Payload contains error details.

POST

/

v3

/

deployments

/

{deployment_id}

/

async

Process (async)

curl --request POST \
  --url https://api.matil.ai/v3/deployments/{deployment_id}/async \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "documents": [
    {
      "text": "<string>",
      "type": "text",
      "metadata": {}
    }
  ],
  "webhook": {
    "url": "<string>",
    "secret": "<string>",
    "incremental": true
  },
  "metadata": {}
}
'

{
  "entry_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "resource_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "resource_version_number": 123,
  "created_at": "2023-11-07T05:31:56Z",
  "status": "pending",
  "resource_type": "structure"
}

Authorizations

x-api-key

string

header

required

Headers

authorization

string | null

x-api-key

string | null

X-Tenant-ID

string | null

Path Parameters

deployment_id

string<uuid>

required

Body

application/json

Request for asynchronous document processing via deployment.

documents

(DocumentInputText · object | DocumentInputURL · object | DocumentInputBase64 · object | DocumentInputId · object)[]

required

List of documents to process

Minimum array length: 1

Direct text content for processing.

DocumentInputText
DocumentInputURL
DocumentInputBase64
DocumentInputId

Show child attributes

webhook

WebhookConfig · object

required

Webhook configuration for receiving results

Show child attributes

metadata

Metadata · object

Optional client-provided metadata

Response

Successful Response

Response for async processing request creation.

entry_id

string<uuid>

required

ID of the pending entry

resource_id

string<uuid>

required

ID of the structure being processed

resource_version_number

integer

required

Version number of the structure

created_at

string<date-time>

required

When the request was received

status

string

default:pending

Initial status

resource_type

string

default:structure

Type of resource being processed

Process (batch)Submit multiple items for processing in a single request. Each item contains its own documents and optional metadata. Returns immediately with a `batch_id` and the total item count. Results are delivered via webhook as items complete. ## Request body - `requests` (required): Array of batch items (max 100). Each item has `documents` (required) and `metadata` (optional). - `webhook` (required): Object with `url`, `secret` (optional), and `incremental` (optional, defaults to `true`). When `incremental` is `true`, a webhook is sent as each item completes. When `false`, a single webhook is sent when the entire batch finishes. ## Webhook events - `batch.item.completed`: A single item finished processing (incremental mode). - `batch.completed`: The entire batch finished. - `batch.failed`: All items in the batch failed.

Process (async)

curl --request POST \
  --url https://api.matil.ai/v3/deployments/{deployment_id}/async \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "documents": [
    {
      "text": "<string>",
      "type": "text",
      "metadata": {}
    }
  ],
  "webhook": {
    "url": "<string>",
    "secret": "<string>",
    "incremental": true
  },
  "metadata": {}
}
'

{
  "entry_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "resource_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "resource_version_number": 123,
  "created_at": "2023-11-07T05:31:56Z",
  "status": "pending",
  "resource_type": "structure"
}