---
title: "Migrating to Batch v2"
description: "The v2 Batch and Files API replaces single-file batch inputs with multi-file upload sessions and batches, improving speed, security and flexibility."
---

The core changes to the Batch API are related to how you get data in and results out: instead of uploading one file at a time 
you can now upload one or more files into a **session**, keeping subfolder organizations and reference them when submitting a batch job as `avra://uploads/<session_id>/file.ext`.

:::info
v1 endpoints remain available for backward compatibility and are marked **deprecated**. They will be sunset soon. All new integrations should use v2.
:::

## What changed

| Concern | v1 (deprecated) | v2 |
| --- | --- | --- |
| Upload | `POST /v1/api/batch-inputs/upload` — one file, referenced by UUID `input_file_id` | `POST /v2/api/files/upload` — many files per session, integrity-checked with MD5 |
| Discover files | `GET /v1/api/batch-inputs` | `GET /v2/api/files` with `prefix` / `session` / `suffix` filters |
| Create batch | `input_file_id` + optional `inputs`, `webhook_url` | `input.files[]` (avra:// paths), optional `reference_date` for backtesting |
| Result | `content_at` URL on `GET /v1/api/batches/{id}/result` | `download_url` + `expires_at` on `GET /v2/api/batches/{id}/result` |

Webhooks are now configurable only through our notifications tool, via dashboard (see [Webhooks](/pt-BR/integrate/webhook-notifications)).
Input and Result deletions and Input downloads are no longer available in self-service ways to ensure security. Reach out to Avra if you need to remove a file.

### Accepted file formats

- **Parquet** — recommended for all inputs, and the format results are written in (`result.parquet`).
- **CSV** — supported for low-complexity schemas.
- **JSONL** — deprecated due to low compression. Migrate to Parquet.

## Migration steps

1. **Upload files into a session**

    Call **`POST /v2/api/files/upload`** with one target per file. Each target declares the destination `file` path, its `content_type`, and a base64-encoded `md5` digest. You will receive one signed `upload_url` per target and a session `expiration`.

    ```json
    {
      "targets": [
        { "file": "base/input1.csv", "content_type": "text/csv", "md5": "KPRxZBtAn5UfexFEKfKr7Q==" }
      ]
    }
    ```
    For each target file, you will receive:
    - `file`: a reference for that file within Avra's domain, `avra://uploads/<session_id>/file.ext`
    - `content_type`: a MIME type for that file, matching the Content-Type provided in request or, if not provided, inferred from the file extension.
    - `md5`: exact MD5 provided in the request as a counter-proof to use.
    - `upload_url`: a signed, short-lived URL to upload the described file, that expects `Content-Type` and `Content-MD5` headers matching the response values. A mismatched digest will be rejected by the storage.

    ```json
    {
      "targets": [
          {
              "file": "avra://uploads/1784669990715/base/input1.csv",
              "content_type": "text/csv",
              "md5": "KPRxZBtAn5UfexFEKfKr7Q==",
              "upload_url": "https://storage.googleapis.com/..."
          }
      ],
      "expiration": "2026-07-21T22:39:50Z"
    }
    ```

2. **(Optional) List what you uploaded**

    Call **`GET /v2/api/files`** to enumerate uploaded files, optionally filtered by `session`, `prefix`, or `suffix`. Paths are returned in the `avra://` scheme, ready to reference in a batch.

3. **Create the batch**

    Call **`POST /v2/api/batches`** referencing the uploaded files. Provide `model_id` + `model_version_id` (or `alias`), an optional `reference_date` if backtesting, and the `input` definition.
    ```json
    {
      "model_id": "00000000-0000-0000-0000-000000000000",
      "model_version_id": "00000000-0000-0000-0000-000000000000",
      "reference_date": "2023-01-01",
      "input": { 
        "files": [
          "avra://uploads/1784143129686/base/input1.csv"
        ]
      }
    }
    ```


    Avra returns the batch `id` and `status` so you can track the job.

4. **Poll and download**

    Poll **`GET /v2/api/batches/{id}`** for status. When complete, call **`GET /v2/api/batches/{id}/result`** to receive a signed `download_url` that expires at `expires_at`.

:::info[API details]
See the [API Reference](/api-reference) for full v2 endpoint schemas, and [Batch Inference](/pt-BR/integrate/batch-inference) for the end-to-end workflow.
:::