---
title: "Create commitment version"
---

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

Path: Sureshake API › execution

`POST /v2/execution/cycles/{cycleId}/commitments/{commitmentId}/versions`

## Path parameters

- `cycleId` (`execution-create-commitment-version.path.cycleId`; string, required)
  - format `uuid`
- `commitmentId` (`execution-create-commitment-version.path.commitmentId`; string, required)
  - format `uuid`

## Request body

_Required._

- `expectedVersionNumber` (`execution-create-commitment-version.expectedVersionNumber`; integer, required)
  - min 1
- `reason` (`execution-create-commitment-version.reason`; string, required)
  - minLength 1; maxLength 2000
- `commitment` (`execution-create-commitment-version.commitment`; object, required)
  - `outcome` (`execution-create-commitment-version.commitment.outcome`; string, required)
    - minLength 1; maxLength 500
  - `ownerUserId` (`execution-create-commitment-version.commitment.ownerUserId`; string, required)
    - minLength 1; maxLength 255
  - `completionDefinition` (`execution-create-commitment-version.commitment.completionDefinition`; string, required)
    - minLength 1; maxLength 2000
  - `proofStandard` (`execution-create-commitment-version.commitment.proofStandard`; string, required)
    - minLength 1; maxLength 2000
  - `category` (`execution-create-commitment-version.commitment.category`; string, required)
    - one of `"revenue"`, `"product"`, `"hiring"`, `"customers"`, `"partnerships"`, `"custom"`
  - `deadlineAt` (`execution-create-commitment-version.commitment.deadlineAt`; string, required)
    - format `date-time`
  - `baselineValue` (`execution-create-commitment-version.commitment.baselineValue`; number, optional)
    - min -1000000000000000; max 1000000000000000
  - `targetValue` (`execution-create-commitment-version.commitment.targetValue`; number, optional)
    - min -1000000000000000; max 1000000000000000
  - `measurementUnit` (`execution-create-commitment-version.commitment.measurementUnit`; string, optional)
    - minLength 1; maxLength 100
  - `expectedEffortMinutes` (`execution-create-commitment-version.commitment.expectedEffortMinutes`; integer, optional)
    - min 1; max 10080
  - `dependencies` (`execution-create-commitment-version.commitment.dependencies`; array<string>, optional)
    - minLength 1; maxLength 500
  - `risks` (`execution-create-commitment-version.commitment.risks`; array<string>, optional)
    - minLength 1; maxLength 500

## Example request

```json
{
  "expectedVersionNumber": 1,
  "reason": "string",
  "commitment": {
    "outcome": "string",
    "ownerUserId": "string",
    "completionDefinition": "string",
    "proofStandard": "string",
    "baselineValue": -1000000000000000,
    "targetValue": -1000000000000000,
    "measurementUnit": "string",
    "expectedEffortMinutes": 1,
    "dependencies": [
      "string"
    ],
    "risks": [
      "string"
    ],
    "category": "revenue",
    "deadlineAt": "2019-08-24T14:15:22Z"
  }
}
```

## Code samples

### cURL

```bash
curl --request POST \
  --url 'https://api.sureshake.com/v2/execution/cycles/<cycleId>/commitments/<commitmentId>/versions' \
  --header 'Content-Type: application/json' \
  --data '
{
  "expectedVersionNumber": 1,
  "reason": "string",
  "commitment": {
    "outcome": "string",
    "ownerUserId": "string",
    "completionDefinition": "string",
    "proofStandard": "string",
    "baselineValue": -1000000000000000,
    "targetValue": -1000000000000000,
    "measurementUnit": "string",
    "expectedEffortMinutes": 1,
    "dependencies": [
      "string"
    ],
    "risks": [
      "string"
    ],
    "category": "revenue",
    "deadlineAt": "2019-08-24T14:15:22Z"
  }
}
'
```

### TypeScript

```typescript
const url = 'https://api.sureshake.com/v2/execution/cycles/<cycleId>/commitments/<commitmentId>/versions';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    expectedVersionNumber: 1,
    reason: 'string',
    commitment: {
      outcome: 'string',
      ownerUserId: 'string',
      completionDefinition: 'string',
      proofStandard: 'string',
      baselineValue: -1000000000000000,
      targetValue: -1000000000000000,
      measurementUnit: 'string',
      expectedEffortMinutes: 1,
      dependencies: ['string'],
      risks: ['string'],
      category: 'revenue',
      deadlineAt: '2019-08-24T14:15:22Z'
    }
  })
};

fetch(url, options)
  .then(res => res.json())
  .then(json => console.log(json))
  .catch(err => console.error(err));
```

### Python

```python
import requests

url = "https://api.sureshake.com/v2/execution/cycles/<cycleId>/commitments/<commitmentId>/versions"

payload = {
    "expectedVersionNumber": 1,
    "reason": "string",
    "commitment": {
        "outcome": "string",
        "ownerUserId": "string",
        "completionDefinition": "string",
        "proofStandard": "string",
        "baselineValue": -1000000000000000,
        "targetValue": -1000000000000000,
        "measurementUnit": "string",
        "expectedEffortMinutes": 1,
        "dependencies": ["string"],
        "risks": ["string"],
        "category": "revenue",
        "deadlineAt": "2019-08-24T14:15:22Z"
    }
}
headers = {"Content-Type": "application/json"}

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

print(response.text)
```

## Responses

### 201

Default Response

#### Example

```json
{
  "data": {
    "commitment": {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "entityId": "156e622c-6cdf-4c27-9bc9-2f2db69919f5",
      "cycleId": "811bdbf8-a42f-4f8c-b62e-39c77332ffe1",
      "title": "string",
      "outcome": "string",
      "description": "string",
      "successCriteria": "string",
      "ownerUserId": "string",
      "completionDefinition": "string",
      "proofStandard": "string",
      "category": "revenue",
      "goalType": "financial_auto",
      "weight": 0,
      "targetValue": 0,
      "commitmentTargetValue": 0,
      "baselineValue": 0,
      "measurementUnit": "string",
      "expectedEffortMinutes": 1,
      "dependencies": [
        "string"
      ],
      "risks": [
        "string"
      ],
      "qualityWarnings": [
        {
          "code": "activity_based",
          "message": "string",
          "fields": [
            "outcome"
          ]
        }
      ],
      "qualityAssessedAt": "2019-08-24T14:15:22Z",
      "actualValue": 0,
      "completionPct": 0,
      "status": "string",
      "deadlineAt": "2019-08-24T14:15:22Z",
      "committedAt": "2019-08-24T14:15:22Z",
      "commitmentStartAt": "2019-08-24T14:15:22Z",
      "currentVersionNumber": 1,
      "payloadHash": "string",
      "createdAt": "2019-08-24T14:15:22Z",
      "updatedAt": "2019-08-24T14:15:22Z"
    },
    "versions": [
      {
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "commitmentId": "4e1ecf7c-8127-4207-92b0-010ff43ff54d",
        "entityId": "156e622c-6cdf-4c27-9bc9-2f2db69919f5",
        "cycleId": "811bdbf8-a42f-4f8c-b62e-39c77332ffe1",
        "versionNumber": 1,
        "supersedesVersionId": "04880951-4fe2-4c15-a1ea-ff10aac0c782",
        "changeKind": "initial",
        "reason": "string",
        "snapshot": {
          "outcome": "string",
          "ownerUserId": "string",
          "completionDefinition": "string",
          "proofStandard": "string",
          "baselineValue": 0,
          "targetValue": 0,
          "measurementUnit": "string",
          "expectedEffortMinutes": 1,
          "dependencies": [
            "string"
          ],
          "risks": [
            "string"
          ],
          "category": "revenue",
          "deadlineAt": "2019-08-24T14:15:22Z",
          "qualityWarnings": [
            {
              "code": "activity_based",
              "message": "string",
              "fields": [
                null
              ]
            }
          ],
          "qualityAssessedAt": "2019-08-24T14:15:22Z"
        },
        "payloadHash": "string",
        "createdBy": "string",
        "createdAt": "2019-08-24T14:15:22Z"
      }
    ]
  },
  "meta": {
    "timestamp": "2019-08-24T14:15:22Z"
  }
}
```

- `data` (`execution-create-commitment-version.response.201.data`; object, required)
  - `commitment` (`execution-create-commitment-version.response.201.data.commitment`; object, required)
    - `id` (`execution-create-commitment-version.response.201.data.commitment.id`; string, required)
      - format `uuid`
    - `entityId` (`execution-create-commitment-version.response.201.data.commitment.entityId`; string, required)
      - format `uuid`
    - `title` (`execution-create-commitment-version.response.201.data.commitment.title`; string, required)
    - `outcome` (`execution-create-commitment-version.response.201.data.commitment.outcome`; string, required)
    - `ownerUserId` (`execution-create-commitment-version.response.201.data.commitment.ownerUserId`; string, required, nullable)
      - minLength 1
    - `completionDefinition` (`execution-create-commitment-version.response.201.data.commitment.completionDefinition`; string, required, nullable)
      - minLength 1; maxLength 2000
    - `proofStandard` (`execution-create-commitment-version.response.201.data.commitment.proofStandard`; string, required, nullable)
      - minLength 1; maxLength 2000
    - `category` (`execution-create-commitment-version.response.201.data.commitment.category`; string, required)
      - one of `"revenue"`, `"product"`, `"hiring"`, `"customers"`, `"partnerships"`, `"custom"`
    - `goalType` (`execution-create-commitment-version.response.201.data.commitment.goalType`; string, required)
      - one of `"financial_auto"`, `"manual"`
    - `commitmentTargetValue` (`execution-create-commitment-version.response.201.data.commitment.commitmentTargetValue`; number, required, nullable)
    - `baselineValue` (`execution-create-commitment-version.response.201.data.commitment.baselineValue`; number, required, nullable)
    - `measurementUnit` (`execution-create-commitment-version.response.201.data.commitment.measurementUnit`; string, required, nullable)
      - minLength 1; maxLength 100
    - `expectedEffortMinutes` (`execution-create-commitment-version.response.201.data.commitment.expectedEffortMinutes`; integer, required, nullable)
      - min 1; max 10080
    - `dependencies` (`execution-create-commitment-version.response.201.data.commitment.dependencies`; array<string>, required, nullable)
      - minLength 1; maxLength 500
    - `risks` (`execution-create-commitment-version.response.201.data.commitment.risks`; array<string>, required, nullable)
      - minLength 1; maxLength 500
    - `qualityWarnings` (`execution-create-commitment-version.response.201.data.commitment.qualityWarnings`; array<object>, required, nullable)
      - `code` (`execution-create-commitment-version.response.201.data.commitment.qualityWarnings.code`; string, required)
        - one of `"activity_based"`, `"not_objectively_closeable"`
      - `message` (`execution-create-commitment-version.response.201.data.commitment.qualityWarnings.message`; string, required)
        - minLength 1; maxLength 500
      - `fields` (`execution-create-commitment-version.response.201.data.commitment.qualityWarnings.fields`; array<string>, required)
        - one of `"outcome"`, `"completionDefinition"`, `"proofStandard"`
    - `qualityAssessedAt` (`execution-create-commitment-version.response.201.data.commitment.qualityAssessedAt`; string, required, nullable)
      - format `date-time`
    - `status` (`execution-create-commitment-version.response.201.data.commitment.status`; string, required)
    - `createdAt` (`execution-create-commitment-version.response.201.data.commitment.createdAt`; string, required)
      - format `date-time`
    - `updatedAt` (`execution-create-commitment-version.response.201.data.commitment.updatedAt`; string, required)
      - format `date-time`
    - `cycleId` (`execution-create-commitment-version.response.201.data.commitment.cycleId`; string, optional, nullable)
      - format `uuid`
    - `description` (`execution-create-commitment-version.response.201.data.commitment.description`; string, optional, nullable)
    - `successCriteria` (`execution-create-commitment-version.response.201.data.commitment.successCriteria`; string, optional, nullable)
    - `weight` (`execution-create-commitment-version.response.201.data.commitment.weight`; number, optional, nullable)
    - `targetValue` (`execution-create-commitment-version.response.201.data.commitment.targetValue`; number, optional, nullable)
    - `actualValue` (`execution-create-commitment-version.response.201.data.commitment.actualValue`; number, optional, nullable)
    - `completionPct` (`execution-create-commitment-version.response.201.data.commitment.completionPct`; number, optional, nullable)
    - `deadlineAt` (`execution-create-commitment-version.response.201.data.commitment.deadlineAt`; string, optional, nullable)
      - format `date-time`
    - `committedAt` (`execution-create-commitment-version.response.201.data.commitment.committedAt`; string, optional, nullable)
      - format `date-time`
    - `commitmentStartAt` (`execution-create-commitment-version.response.201.data.commitment.commitmentStartAt`; string, optional, nullable)
      - format `date-time`
    - `currentVersionNumber` (`execution-create-commitment-version.response.201.data.commitment.currentVersionNumber`; integer, optional, nullable)
      - min 1
    - `payloadHash` (`execution-create-commitment-version.response.201.data.commitment.payloadHash`; string, optional, nullable)
  - `versions` (`execution-create-commitment-version.response.201.data.versions`; array<object>, required)
    - `id` (`execution-create-commitment-version.response.201.data.versions.id`; string, required)
      - format `uuid`
    - `commitmentId` (`execution-create-commitment-version.response.201.data.versions.commitmentId`; string, required)
      - format `uuid`
    - `entityId` (`execution-create-commitment-version.response.201.data.versions.entityId`; string, required)
      - format `uuid`
    - `cycleId` (`execution-create-commitment-version.response.201.data.versions.cycleId`; string, required)
      - format `uuid`
    - `versionNumber` (`execution-create-commitment-version.response.201.data.versions.versionNumber`; integer, required)
      - min 1
    - `supersedesVersionId` (`execution-create-commitment-version.response.201.data.versions.supersedesVersionId`; string, required, nullable)
      - format `uuid`
    - `changeKind` (`execution-create-commitment-version.response.201.data.versions.changeKind`; string, required)
      - one of `"initial"`, `"edit"`, `"correction"`
    - `reason` (`execution-create-commitment-version.response.201.data.versions.reason`; string, required, nullable)
      - minLength 1; maxLength 2000
    - `snapshot` (`execution-create-commitment-version.response.201.data.versions.snapshot`; object, required)
      - `outcome` (`execution-create-commitment-version.response.201.data.versions.snapshot.outcome`; string, required)
        - minLength 1; maxLength 500
      - `ownerUserId` (`execution-create-commitment-version.response.201.data.versions.snapshot.ownerUserId`; string, required)
        - minLength 1; maxLength 255
      - `completionDefinition` (`execution-create-commitment-version.response.201.data.versions.snapshot.completionDefinition`; string, required)
        - minLength 1; maxLength 2000
      - `proofStandard` (`execution-create-commitment-version.response.201.data.versions.snapshot.proofStandard`; string, required)
        - minLength 1; maxLength 2000
      - `baselineValue` (`execution-create-commitment-version.response.201.data.versions.snapshot.baselineValue`; number, required, nullable)
      - `targetValue` (`execution-create-commitment-version.response.201.data.versions.snapshot.targetValue`; number, required, nullable)
      - `measurementUnit` (`execution-create-commitment-version.response.201.data.versions.snapshot.measurementUnit`; string, required, nullable)
        - minLength 1; maxLength 100
      - `expectedEffortMinutes` (`execution-create-commitment-version.response.201.data.versions.snapshot.expectedEffortMinutes`; integer, required, nullable)
        - min 1; max 10080
      - `dependencies` (`execution-create-commitment-version.response.201.data.versions.snapshot.dependencies`; array<string>, required)
        - minLength 1; maxLength 500
      - `risks` (`execution-create-commitment-version.response.201.data.versions.snapshot.risks`; array<string>, required)
        - minLength 1; maxLength 500
      - `category` (`execution-create-commitment-version.response.201.data.versions.snapshot.category`; string, required)
        - one of `"revenue"`, `"product"`, `"hiring"`, `"customers"`, `"partnerships"`, `"custom"`
      - `deadlineAt` (`execution-create-commitment-version.response.201.data.versions.snapshot.deadlineAt`; string, required)
        - format `date-time`
      - `qualityWarnings` (`execution-create-commitment-version.response.201.data.versions.snapshot.qualityWarnings`; array<object>, required)
        - `code` (`execution-create-commitment-version.response.201.data.versions.snapshot.qualityWarnings.code`; string, required)
          - one of `"activity_based"`, `"not_objectively_closeable"`
        - `message` (`execution-create-commitment-version.response.201.data.versions.snapshot.qualityWarnings.message`; string, required)
          - minLength 1; maxLength 500
        - `fields` (`execution-create-commitment-version.response.201.data.versions.snapshot.qualityWarnings.fields`; array<string>, required)
          - one of `"outcome"`, `"completionDefinition"`, `"proofStandard"`
      - `qualityAssessedAt` (`execution-create-commitment-version.response.201.data.versions.snapshot.qualityAssessedAt`; string, required)
        - format `date-time`
    - `payloadHash` (`execution-create-commitment-version.response.201.data.versions.payloadHash`; string, required)
      - pattern `^sha256:[a-f0-9]{64}$`
    - `createdBy` (`execution-create-commitment-version.response.201.data.versions.createdBy`; string, required)
      - minLength 1
    - `createdAt` (`execution-create-commitment-version.response.201.data.versions.createdAt`; string, required)
      - format `date-time`
- `meta` (`execution-create-commitment-version.response.201.meta`; object, optional)
  - `timestamp` (`execution-create-commitment-version.response.201.meta.timestamp`; string, required)
    - format `date-time`

### 400

Default Response

#### Example

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "details": null,
    "traceId": "string"
  }
}
```

- `error` (`execution-create-commitment-version.response.400.error`; object, required)
  - `code` (`execution-create-commitment-version.response.400.error.code`; string, required) — Machine-readable error code (e.g., NOT_FOUND)
  - `message` (`execution-create-commitment-version.response.400.error.message`; string, required) — Human-readable error message
  - `details` (`execution-create-commitment-version.response.400.error.details`; unknown, optional) — Optional structured error details
  - `traceId` (`execution-create-commitment-version.response.400.error.traceId`; string, optional) — Unique ID for log correlation

### 401

Default Response

#### Example

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "details": null,
    "traceId": "string"
  }
}
```

- `error` (`execution-create-commitment-version.response.401.error`; object, required)
  - `code` (`execution-create-commitment-version.response.401.error.code`; string, required) — Machine-readable error code (e.g., NOT_FOUND)
  - `message` (`execution-create-commitment-version.response.401.error.message`; string, required) — Human-readable error message
  - `details` (`execution-create-commitment-version.response.401.error.details`; unknown, optional) — Optional structured error details
  - `traceId` (`execution-create-commitment-version.response.401.error.traceId`; string, optional) — Unique ID for log correlation

### 403

Default Response

#### Example

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "details": null,
    "traceId": "string"
  }
}
```

- `error` (`execution-create-commitment-version.response.403.error`; object, required)
  - `code` (`execution-create-commitment-version.response.403.error.code`; string, required) — Machine-readable error code (e.g., NOT_FOUND)
  - `message` (`execution-create-commitment-version.response.403.error.message`; string, required) — Human-readable error message
  - `details` (`execution-create-commitment-version.response.403.error.details`; unknown, optional) — Optional structured error details
  - `traceId` (`execution-create-commitment-version.response.403.error.traceId`; string, optional) — Unique ID for log correlation

### 404

Default Response

#### Example

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "details": null,
    "traceId": "string"
  }
}
```

- `error` (`execution-create-commitment-version.response.404.error`; object, required)
  - `code` (`execution-create-commitment-version.response.404.error.code`; string, required) — Machine-readable error code (e.g., NOT_FOUND)
  - `message` (`execution-create-commitment-version.response.404.error.message`; string, required) — Human-readable error message
  - `details` (`execution-create-commitment-version.response.404.error.details`; unknown, optional) — Optional structured error details
  - `traceId` (`execution-create-commitment-version.response.404.error.traceId`; string, optional) — Unique ID for log correlation

### 409

Default Response

#### Example

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "details": null,
    "traceId": "string"
  }
}
```

- `error` (`execution-create-commitment-version.response.409.error`; object, required)
  - `code` (`execution-create-commitment-version.response.409.error.code`; string, required) — Machine-readable error code (e.g., NOT_FOUND)
  - `message` (`execution-create-commitment-version.response.409.error.message`; string, required) — Human-readable error message
  - `details` (`execution-create-commitment-version.response.409.error.details`; unknown, optional) — Optional structured error details
  - `traceId` (`execution-create-commitment-version.response.409.error.traceId`; string, optional) — Unique ID for log correlation

### 422

Default Response

#### Example

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "details": null,
    "traceId": "string"
  }
}
```

- `error` (`execution-create-commitment-version.response.422.error`; object, required)
  - `code` (`execution-create-commitment-version.response.422.error.code`; string, required) — Machine-readable error code (e.g., NOT_FOUND)
  - `message` (`execution-create-commitment-version.response.422.error.message`; string, required) — Human-readable error message
  - `details` (`execution-create-commitment-version.response.422.error.details`; unknown, optional) — Optional structured error details
  - `traceId` (`execution-create-commitment-version.response.422.error.traceId`; string, optional) — Unique ID for log correlation

### 429

Default Response

#### Example

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "details": null,
    "traceId": "string"
  }
}
```

- `error` (`execution-create-commitment-version.response.429.error`; object, required)
  - `code` (`execution-create-commitment-version.response.429.error.code`; string, required) — Machine-readable error code (e.g., NOT_FOUND)
  - `message` (`execution-create-commitment-version.response.429.error.message`; string, required) — Human-readable error message
  - `details` (`execution-create-commitment-version.response.429.error.details`; unknown, optional) — Optional structured error details
  - `traceId` (`execution-create-commitment-version.response.429.error.traceId`; string, optional) — Unique ID for log correlation

### 500

Default Response

#### Example

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "details": null,
    "traceId": "string"
  }
}
```

- `error` (`execution-create-commitment-version.response.500.error`; object, required)
  - `code` (`execution-create-commitment-version.response.500.error.code`; string, required) — Machine-readable error code (e.g., NOT_FOUND)
  - `message` (`execution-create-commitment-version.response.500.error.message`; string, required) — Human-readable error message
  - `details` (`execution-create-commitment-version.response.500.error.details`; unknown, optional) — Optional structured error details
  - `traceId` (`execution-create-commitment-version.response.500.error.traceId`; string, optional) — Unique ID for log correlation

### 502

Default Response

#### Example

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "details": null,
    "traceId": "string"
  }
}
```

- `error` (`execution-create-commitment-version.response.502.error`; object, required)
  - `code` (`execution-create-commitment-version.response.502.error.code`; string, required) — Machine-readable error code (e.g., NOT_FOUND)
  - `message` (`execution-create-commitment-version.response.502.error.message`; string, required) — Human-readable error message
  - `details` (`execution-create-commitment-version.response.502.error.details`; unknown, optional) — Optional structured error details
  - `traceId` (`execution-create-commitment-version.response.502.error.traceId`; string, optional) — Unique ID for log correlation

### 503

Default Response

#### Example

```json
{
  "error": {
    "code": "string",
    "message": "string",
    "details": null,
    "traceId": "string"
  }
}
```

- `error` (`execution-create-commitment-version.response.503.error`; object, required)
  - `code` (`execution-create-commitment-version.response.503.error.code`; string, required) — Machine-readable error code (e.g., NOT_FOUND)
  - `message` (`execution-create-commitment-version.response.503.error.message`; string, required) — Human-readable error message
  - `details` (`execution-create-commitment-version.response.503.error.details`; unknown, optional) — Optional structured error details
  - `traceId` (`execution-create-commitment-version.response.503.error.traceId`; string, optional) — Unique ID for log correlation


Source: https://docs.sureshake.com/reference/execution-create-commitment-version/index.md