Skip to main content

​
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: 
X-API-Key: ca_your_api_key_here

​
Path Parameters

ParameterTypeRequiredDescription
task_idintegerYesUnique identifier for the task

​
Request Body

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

​
Required Fields

FieldTypeDescription
step_run_idstringID of the negotiation step run
fileobjectDocument file to upload. See File Object
uploading_partystringParty that uploaded this version: legal (our side), counterparty, or stakeholders (internal)

​
Optional Fields

FieldTypeDescription
file_uuidstringExisting negotiation thread UUID. Provide this to add a new version to an existing document
new_document_to_negotiatebooleanSet to true to start a new negotiation document (no file_uuid). Defaults to false

​
File Object Fields

FieldTypeDescription
filenamestringFilename, e.g. contract.pdf
base64_contentstringBase64-encoded file content
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.

​
Request Example

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"
  }'

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

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

​
Response

​
Success Response

Status Code: 200 OK 
{
  "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

FieldTypeDescription
task_idintegerID of the task
versionintegerVersion number assigned to the uploaded document
file_uuidstringNegotiation thread UUID. Pass this as file_uuid on the next upload to add to the same thread
file_idstringSOR file reference (document_{id} or attachment_{id}) used for download
file_namestringName of the uploaded file
uploading_partystringParty that uploaded this version: legal, counterparty, or stakeholders
download_urlstringPresigned URL to download the document
expires_atstringISO 8601 timestamp when the download URL expires

​
Error Responses

​
401 Unauthorized

Returned when authentication fails. See the authentication errors section for details. 
{
  "detail": "Invalid API key"
}

​
404 Not Found

Returned when the task doesn’t exist or you don’t have access to it. 
{
  "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. 
{
  "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. 
{
  "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. 
{
  "detail": "Failed to upload negotiation version"
}

​
Notes

To find the file_uuid of an existing negotiation document, call Get Latest Negotiation Versions and reuse the returned file_uuid.
Set uploading_party to reflect who produced this version. It feeds the our_party_changes flag and helps track negotiation turn order.
The presigned download URL expires after a certain time (indicated by expires_at). Download the file before the URL expires or request it again.

​
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