Skip to content
Kindgi

Submit a decision on an approval

POST
/v1/approvals/{approvalId}/complete
curl --request POST \
  --url https://example.com/v1/approvals/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/complete \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "decision": "approve", "rationale": "example", "value": "example" }'

Records the decision (HitlBinding.submitReview). When the approval carries a waitTokenId and the decision is approve or reject, also completes the waitpoint so the suspended run resumes.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
approvalId
required
string format: uuid

ApprovalId — opaque branded string (a UUID).

Header Parameters

Section titled “Header Parameters”
Idempotency-Key
string
>= 1 characters

Caller-supplied idempotency key. Retries with the same key return the original response byte-identical (per docs/API-ROUTE-CONVENTIONS.md §3.1).

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
decision
required
string
Allowed values: approve reject escalate withdraw
rationale
string
value

Payload passed to the run waitpoint (RunBinding.completeToken) when the approval is linked to a suspended run and the decision is approve or reject.

Responses

Section titled “Responses”

200

Section titled “200”

Decision recorded.

Media typeapplication/json
object
kind
required
string
Allowed values: terminal escalated
approval
required
object
id
required
string format: uuid
tenantId
required
string format: uuid
projectId
string format: uuid
subjectKind
required
string
subjectRef
required
object
key
additional properties
any
requiredRole
required

Reviewer role class. Hierarchy: standard < senior < admin.

string
Allowed values: standard senior admin
status
required
string
Allowed values: pending assigned in_review approved rejected escalated expired withdrawn
assignedTo
string format: uuid
batchKey
string
title
string
description
string
context
object
key
additional properties
any
provenanceRef
object
runId
required
string format: uuid
provenanceId
string format: uuid
waitTokenId
string
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
decidedAt
string format: date-time
expiresAt
string format: date-time
decision
required
object
id
required
string
approvalId
required
string format: uuid
reviewerId
required
string format: uuid
decision
required
string
Allowed values: approve reject escalate withdraw
rationale
string
reviewerRoleAtDecision
required

Reviewer role class. Hierarchy: standard < senior < admin.

string
Allowed values: standard senior admin
decidedAt
required
string format: date-time
nextApproval

Present only when kind === "escalated".

object
id
required
string format: uuid
tenantId
required
string format: uuid
projectId
string format: uuid
subjectKind
required
string
subjectRef
required
object
key
additional properties
any
requiredRole
required

Reviewer role class. Hierarchy: standard < senior < admin.

string
Allowed values: standard senior admin
status
required
string
Allowed values: pending assigned in_review approved rejected escalated expired withdrawn
assignedTo
string format: uuid
batchKey
string
title
string
description
string
context
object
key
additional properties
any
provenanceRef
object
runId
required
string format: uuid
provenanceId
string format: uuid
waitTokenId
string
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
decidedAt
string format: date-time
expiresAt
string format: date-time
waitpointResolved
required

True when the approval had a waitTokenId + terminal accept/reject and the run waitpoint was completed as part of this call.

boolean
Example
{
  "kind": "terminal",
  "approval": {
    "requiredRole": "standard",
    "status": "pending"
  },
  "decision": {
    "decision": "approve",
    "reviewerRoleAtDecision": "standard"
  },
  "nextApproval": {
    "requiredRole": "standard",
    "status": "pending"
  }
}

400

Section titled “400”

Malformed request body.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

401

Section titled “401”

Missing / malformed / expired / revoked bearer token.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

403

Section titled “403”

Reviewer role too low, or no reviewer row for this user.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

404

Section titled “404”

No approval visible to the caller with that id.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

409

Section titled “409”

Idempotency-Key was reused with a different body, or resource-state conflict.

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}

500

Section titled “500”

Server error (unmapped domain code or framework crash).

Media typeapplication/json
object
error
required
object
code
required

Stable machine-readable discriminant. Values match domain error codes (see docs/API-ROUTE-CONVENTIONS.md §4.3).

string
message
required
string
details

Optional, kind-specific.

object
key
additional properties
any
requestId
required

Server-assigned request id; also echoed via X-Request-Id header.

string
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "details": {},
    "requestId": "example"
  }
}