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

# Upload Negotiation Version

> Upload a new negotiation document version for a workflow task

## Endpoint

```
POST /tasks/{task_id}/negotiation-version
```

## Authentication

This endpoint requires authentication via API key. Include your API key in the `X-API-Key` header:

```bash theme={null}
X-API-Key: ca_your_api_key_here
```

## Path Parameters

| Parameter | Type    | Required | Description                    |
| --------- | ------- | -------- | ------------------------------ |
| `task_id` | integer | Yes      | Unique identifier for the task |

## Request Body

The request body must be a JSON object with the following fields:

### Required Fields

| Field             | Type   | Description                                                                                        |
| ----------------- | ------ | -------------------------------------------------------------------------------------------------- |
| `step_run_id`     | string | ID of the negotiation step run                                                                     |
| `file`            | object | Document file to upload. See [File Object](#file-object-fields)                                    |
| `uploading_party` | string | Party that uploaded this version: `legal` (our side), `counterparty`, or `stakeholders` (internal) |

### Optional Fields

| Field                       | Type    | Description                                                                                 |
| --------------------------- | ------- | ------------------------------------------------------------------------------------------- |
| `file_uuid`                 | string  | Existing negotiation thread UUID. Provide this to add a new version to an existing document |
| `new_document_to_negotiate` | boolean | Set to `true` to start a new negotiation document (no `file_uuid`). Defaults to `false`     |

### File Object Fields

| Field            | Type   | Description                   |
| ---------------- | ------ | ----------------------------- |
| `filename`       | string | Filename, e.g. `contract.pdf` |
| `base64_content` | string | Base64-encoded file content   |

<Warning>
  Provide exactly one upload mode:

  * **New version of an existing document** — provide `file_uuid` and leave `new_document_to_negotiate` as `false`.
  * **New negotiation document** — set `new_document_to_negotiate` to `true` and omit `file_uuid`.

  Providing both, or neither, returns a `422 Validation Error`.
</Warning>

## Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://platform.chamelio.ai/tasks/12345/negotiation-version" \
    -H "X-API-Key: ca_your_api_key_here" \
    -H "Content-Type: application/json" \
    -d '{
      "step_run_id": "sr_abc123",
      "file": {
        "filename": "vendor_agreement_v4.docx",
        "base64_content": "UEsDBBQABgAIAAAAIQ..."
      },
      "uploading_party": "legal",
      "file_uuid": "5f1c2d8a-3b4e-4f6a-9c10-2e7b8d9a1f23"
    }'
  ```

  ```python Python theme={null}
  import base64
  import requests

  task_id = 12345

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

  url = f"https://platform.chamelio.ai/tasks/{task_id}/negotiation-version"
  headers = {
      "X-API-Key": "ca_your_api_key_here",
      "Content-Type": "application/json"
  }

  payload = {
      "step_run_id": "sr_abc123",
      "file": {
          "filename": "vendor_agreement_v4.docx",
          "base64_content": content
      },
      "uploading_party": "legal",
      "file_uuid": "5f1c2d8a-3b4e-4f6a-9c10-2e7b8d9a1f23"
  }

  response = requests.post(url, json=payload, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const taskId = 12345;

  const response = await fetch(
    `https://platform.chamelio.ai/tasks/${taskId}/negotiation-version`,
    {
      method: 'POST',
      headers: {
        'X-API-Key': 'ca_your_api_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        step_run_id: 'sr_abc123',
        file: {
          filename: 'vendor_agreement_v4.docx',
          base64_content: 'UEsDBBQABgAIAAAAIQ...'
        },
        uploading_party: 'legal',
        file_uuid: '5f1c2d8a-3b4e-4f6a-9c10-2e7b8d9a1f23'
      })
    }
  );

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

## Response

### Success Response

**Status Code:** `200 OK`

```json theme={null}
{
  "task_id": 12345,
  "version": 4,
  "file_uuid": "5f1c2d8a-3b4e-4f6a-9c10-2e7b8d9a1f23",
  "file_id": "document_790",
  "file_name": "vendor_agreement_v4.docx",
  "uploading_party": "legal",
  "download_url": "https://s3.amazonaws.com/chamelio-files/...",
  "expires_at": "2025-01-20T12:00:00Z"
}
```

### Response Fields

| Field             | Type    | Description                                                                                    |
| ----------------- | ------- | ---------------------------------------------------------------------------------------------- |
| `task_id`         | integer | ID of the task                                                                                 |
| `version`         | integer | Version number assigned to the uploaded document                                               |
| `file_uuid`       | string  | Negotiation thread UUID. Pass this as `file_uuid` on the next upload to add to the same thread |
| `file_id`         | string  | SOR file reference (`document_{id}` or `attachment_{id}`) used for download                    |
| `file_name`       | string  | Name of the uploaded file                                                                      |
| `uploading_party` | string  | Party that uploaded this version: `legal`, `counterparty`, or `stakeholders`                   |
| `download_url`    | string  | Presigned URL to download the document                                                         |
| `expires_at`      | string  | ISO 8601 timestamp when the download URL expires                                               |

## Error Responses

### 401 Unauthorized

Returned when authentication fails. See the [authentication errors](/api-reference/introduction#authentication-errors) section for details.

```json theme={null}
{
  "detail": "Invalid API key"
}
```

### 404 Not Found

Returned when the task doesn't exist or you don't have access to it.

```json theme={null}
{
  "detail": "Task not found"
}
```

### 409 Conflict

Returned when the task is not at a negotiation step or the upload conflicts with the current step state.

```json theme={null}
{
  "detail": "Task is not at a negotiation step"
}
```

### 422 Validation Error

Returned when the request body is invalid, including when neither `file_uuid` nor `new_document_to_negotiate` is provided, or when both are provided.

```json theme={null}
{
  "detail": [
    {
      "loc": ["body"],
      "msg": "Either provide file_uuid to upload a new version, or set new_document_to_negotiate=True to upload a new negotiation document",
      "type": "value_error"
    }
  ]
}
```

### 500 Internal Server Error

Returned when the upload fails due to a server error.

```json theme={null}
{
  "detail": "Failed to upload negotiation version"
}
```

## Notes

<Tip>
  To find the `file_uuid` of an existing negotiation document, call [Get Latest Negotiation Versions](/api-reference/endpoint/tasks/latest-negotiation-versions) and reuse the returned `file_uuid`.
</Tip>

<Info>
  Set `uploading_party` to reflect who produced this version. It feeds the `our_party_changes` flag and helps track negotiation turn order.
</Info>

<Warning>
  The presigned download URL expires after a certain time (indicated by `expires_at`). Download the file before the URL expires or request it again.
</Warning>

## Use Cases

This endpoint is useful for:

* **Round-trip negotiation** - Upload counterparty redlines or your own revisions as new versions
* **External drafting tools** - Push documents edited outside Chamelio back into the negotiation thread
* **New document negotiation** - Start a fresh negotiation document on a step with `new_document_to_negotiate`
* **Integration** - Sync externally managed contract versions into the workflow