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

# Get Latest Negotiation Versions

> Retrieve the latest version of each negotiation document on a negotiation step

## Endpoint

```
GET /v2/tasks/{task_id}/latest-negotiation-versions
```

## Authentication

This endpoint requires an OAuth access token. Send it as a bearer token:

```bash theme={null}
Authorization: Bearer your_access_token
```

**Required scope:** `tasks:read`

## Path Parameters

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

## Query Parameters

| Parameter     | Type   | Required | Description                                             |
| ------------- | ------ | -------- | ------------------------------------------------------- |
| `step_run_id` | string | Yes      | ID of the negotiation step run to retrieve versions for |

## Request Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://platform.chamelio.ai/v2/tasks/12345/latest-negotiation-versions?step_run_id=sr_abc123" \
    -H "Authorization: Bearer your_access_token"
  ```

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

  task_id = 12345

  url = f"https://platform.chamelio.ai/v2/tasks/{task_id}/latest-negotiation-versions"
  headers = {
      "Authorization": "Bearer your_access_token"
  }
  params = {
      "step_run_id": "sr_abc123"
  }

  response = requests.get(url, headers=headers, params=params)
  print(response.json())
  ```

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

  const response = await fetch(
    `https://platform.chamelio.ai/v2/tasks/${taskId}/latest-negotiation-versions?step_run_id=sr_abc123`,
    {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer your_access_token'
      }
    }
  );

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

## Response

### Success Response

**Status Code:** `200 OK`

```json theme={null}
{
  "files": [
    {
      "file_uuid": "5f1c2d8a-3b4e-4f6a-9c10-2e7b8d9a1f23",
      "file_id": "document_789",
      "file_name": "vendor_agreement.docx",
      "version": 3,
      "uploading_party": "counterparty",
      "our_party_changes": false,
      "download_url": "https://s3.amazonaws.com/chamelio-files/...",
      "expires_at": "2025-01-20T12:00:00Z"
    }
  ]
}
```

### Response Fields

| Field   | Type  | Description                                         |
| ------- | ----- | --------------------------------------------------- |
| `files` | array | Latest version of each negotiation file on the step |

### Negotiation File Object Fields

| Field               | Type    | Description                                                                                                      |
| ------------------- | ------- | ---------------------------------------------------------------------------------------------------------------- |
| `file_uuid`         | string  | Negotiation thread UUID. Pass this as `file_uuid` when uploading the next version of the same document           |
| `file_id`           | string  | SOR file reference (`document_{id}` or `attachment_{id}`) used for download                                      |
| `file_name`         | string  | Name of the negotiation document                                                                                 |
| `version`           | integer | Version number of this negotiation document                                                                      |
| `uploading_party`   | string  | Party that uploaded this version: `legal` (our side), `counterparty`, or `stakeholders` (internal)               |
| `our_party_changes` | boolean | Whether this version contains changes made by your party (true when the uploading party is not the counterparty) |
| `download_url`      | string  | Presigned URL to download the document                                                                           |
| `expires_at`        | string  | ISO 8601 timestamp when the download URL expires                                                                 |

## Error Responses

### 400 Bad Request

Returned when the access token has no user behind it.
`client_credentials` tokens act as the admin who created the application, so this applies only to
tokens issued before application creators were recorded.

```json theme={null}
{
  "detail": "client_credentials tokens are not associated with a user"
}
```

### 401 Unauthorized

Returned when the access token is missing, unknown, revoked, or expired, or when an `X-API-Key` was
sent instead of a bearer token. See [OAuth error responses](/api-reference/oauth-apps#error-responses).

```json theme={null}
{
  "detail": "Invalid access token"
}
```

### 403 Forbidden

Returned when the token lacks the required scope:

```json theme={null}
{
  "detail": "Insufficient scope; this endpoint requires: tasks:read"
}
```

Or when the user may not access this task:

```json theme={null}
{
  "detail": "You do not have access to this resource"
}
```

### 404 Not Found

Returned when the task or step run does not exist, or no negotiation version is available.

```json theme={null}
{
  "detail": "Not found"
}
```

### 422 Validation Error

Returned when the request parameters are invalid (e.g., `step_run_id` is missing).

```json theme={null}
{
  "detail": [
    {
      "loc": ["query", "step_run_id"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}
```

### 429 Too Many Requests

Returned when your organization exceeds its per-minute request limit.

```json theme={null}
{
  "detail": "Rate limit exceeded"
}
```

### 500 Internal Server Error

Returned when the request fails due to a server error.

```json theme={null}
{
  "detail": "Failed to get latest negotiation versions"
}
```

## Notes

<Info>
  A negotiation step can carry more than one document. This endpoint returns the most recent version of
  **each** negotiation file on the step, keyed by its `file_uuid` thread.
</Info>

<Tip>
  Use `file_uuid` to track a document across negotiation rounds. When you upload the next version with
  [Upload Negotiation Version](/api-reference/endpoint/v2/tasks/negotiation-version), pass the same
  `file_uuid` to add to the existing thread.
</Tip>

<Warning>
  The presigned download URLs expire after a certain time (indicated by `expires_at`). Download the files
  before the URLs expire or request them again.
</Warning>

## Use Cases

This endpoint is useful for:

* **Negotiation tracking** - Monitor the current state of every document under negotiation on a step
* **Document retrieval** - Download the latest version of each negotiated document
* **Turn detection** - Use `uploading_party` and `our_party_changes` to determine which side made the most recent changes
* **Integration** - Sync negotiation progress with external contract management systems