Upload Negotiation Version

Endpoint

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

Authentication

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

Authorization: Bearer your_access_token

Required scope: tasks:write

The version is uploaded as the access token’s user. The user_email field on the request body is ignored.

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
`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`
`user_email`	string	Ignored on this endpoint. The upload is always attributed to the access token’s user

File Object Fields

Field	Type	Description
`filename`	string	Filename, e.g. `contract.pdf`
`base64_content`	string	Base64-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/v2/tasks/12345/negotiation-version" \
  -H "Authorization: Bearer your_access_token" \
  -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/v2/tasks/{task_id}/negotiation-version"
headers = {
    "Authorization": "Bearer your_access_token",
    "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/v2/tasks/${taskId}/negotiation-version`,
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer your_access_token',
      '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

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

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:write"
}

Or when the user may not act on this task:

{
  "detail": "You do not have access to this resource"
}

404 Not Found

Returned when the task does not exist.

{
  "detail": "Not found"
}

409 Conflict

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

{
  "detail": "The task is not in a state that allows this operation"
}

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

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 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
Attributed revisions - Record which user contributed each version

Overview

API Key Access

OAuth App Access

Webhooks

Endpoint

Authentication

Path Parameters

Request Body

Required Fields

Optional Fields

File Object Fields

Request Example

Response

Success Response

Response Fields

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict

422 Validation Error

429 Too Many Requests

500 Internal Server Error

Notes

Use Cases

​Endpoint

​Authentication

​Path Parameters

​Request Body

​Required Fields

​Optional Fields

​File Object Fields

​Request Example

​Response

​Success Response

​Response Fields

​Error Responses

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​409 Conflict

​422 Validation Error

​429 Too Many Requests

​500 Internal Server Error

​Notes

​Use Cases

Endpoint

Authentication

Path Parameters

Request Body

Required Fields

Optional Fields

File Object Fields

Request Example

Response

Success Response

Response Fields

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

409 Conflict

422 Validation Error

429 Too Many Requests

500 Internal Server Error

Notes

Use Cases