Skip to content
Kindgi

Fetch a single approval

View as Markdown
GET
/v1/approvals/{approvalId}
curl --request GET \
  --url https://example.com/v1/approvals/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>'

Returns 404 for ids that exist but require a higher role than the caller (avoids cross-tier existence leaks — see API-ROUTE-CONVENTIONS.md §2.4). A decided approval carries its decision: what the reviewer decided, why, and who (decidedBy, user:<userId>).

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

Responses

Section titled “Responses”

200

Section titled “200”

Approval.

Media typeapplication/json
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

The reviewer’s decision, once one is recorded. Absent while the approval is open, and when it ended without one (it expired, a timeout escalated it, or its run’s end withdrew it).

object
decision
required
string
Allowed values: approve reject escalate withdraw
decidedBy

Who decided, as an actor: user:<userId>, the reviewer’s user. The run’s journal and provenance name the decider the same way. The Kindgi runtime always records it; a deployment whose HITL binding doesn’t leaves it out.

string
reviewerId
required
string format: uuid
reviewerRoleAtDecision
required

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

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

Who asked for it, when recorded: user:<id>, service_account:<id> or system:<what>.

string
separateApprover

Whether the person who asked may not approve it (four eyes). A runtime that knows it always sends it, false included.

boolean
withdrawnBecause

Why it was withdrawn, when its run’s end withdrew it (a reviewer’s withdrawal has its decision instead).

string
Allowed values: run-cancelled run-ended
escalatedFrom

The approval this one was escalated from.

string format: uuid
escalatedTo

The approval this one was escalated to.

string format: uuid
Example
{
  "requiredRole": "standard",
  "status": "pending",
  "decision": {
    "decision": "approve",
    "reviewerRoleAtDecision": "standard"
  },
  "withdrawnBecause": "run-cancelled"
}

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”

The caller isn’t a reviewer.

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 with that id — or the caller cannot see it.

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

See also