Get Latest Negotiation Versions

Endpoint

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

Authentication

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

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

curl -X GET "https://platform.chamelio.ai/v2/tasks/12345/latest-negotiation-versions?step_run_id=sr_abc123" \
  -H "Authorization: Bearer your_access_token"

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())

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);

Response

Success Response

Status Code: 200 OK

{
  "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.

{
  "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.

{
  "detail": "Invalid access token"
}

403 Forbidden

Returned when the token lacks the required scope:

{
  "detail": "Insufficient scope; this endpoint requires: tasks:read"
}

Or when the user may not access this task:

{
  "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.

{
  "detail": "Not found"
}

422 Validation Error

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

{
  "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.

{
  "detail": "Rate limit exceeded"
}

500 Internal Server Error

Returned when the request fails due to a server error.

{
  "detail": "Failed to get latest negotiation versions"
}

Notes

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.

Use file_uuid to track a document across negotiation rounds. When you upload the next version with Upload Negotiation Version, pass the same file_uuid to add to the existing thread.

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

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

Overview

API Key Access

OAuth App Access

Webhooks

Endpoint

Authentication

Path Parameters

Query Parameters

Request Example

Response

Success Response

Response Fields

Negotiation File Object Fields

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

422 Validation Error

429 Too Many Requests

500 Internal Server Error

Notes

Use Cases

​Endpoint

​Authentication

​Path Parameters

​Query Parameters

​Request Example

​Response

​Success Response

​Response Fields

​Negotiation File Object Fields

​Error Responses

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​422 Validation Error

​429 Too Many Requests

​500 Internal Server Error

​Notes

​Use Cases

Endpoint

Authentication

Path Parameters

Query Parameters

Request Example

Response

Success Response

Response Fields

Negotiation File Object Fields

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

422 Validation Error

429 Too Many Requests

500 Internal Server Error

Notes

Use Cases