Fetch a single approval

GET

/v1/approvals/{approvalId}

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

• Same-origin — path relative to the deployment root.

Requires a reviewer, or (with authorization on) a person who is the workspace’s admin, as the list does; the workspace’s admin reads an approval of any tier. 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), or that are in a project the caller may not read. A decided approval carries its decision: what the reviewer decided, why, and who (decidedBy, user:<userId>).

Authorizations

• bearerAuth

Parameters

Path Parameters

approvalId

required

string format: uuid

ApprovalId — opaque branded string (a UUID).

Responses

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

sessionProvider

The provider of the session the reviewer decided with: site:<id> for a site’s sign-in, an identity provider’s id for a single sign-on session. Absent for an API key, and on decisions an older runtime recorded.

string

deciderName

The reviewer’s display name when they decided: a person renamed since still shows as they were. Absent on decisions an older runtime recorded.

string

factText

The text a reviewer approved a remembered fact with, in place of the agent’s (the approval’s description), which the fact now holds. Absent when the fact was approved as the agent wrote it.

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

approver

The one member who may decide it.

object

kind

required

string

Allowed values: member

userId

required

string

connection

The connection the call would use: the person’s own, or else the company’s connection the call was gated on, which it then runs with or doesn’t run (connection-changed). A person’s account isn’t named: show “this person’s account”.

object

app

required

The app’s entry id.

string

appName

required

string

as

Whose connection: the company’s, or the person’s. Absent from older approvals.

string

Allowed values: company person

account

The company’s account label at the app: an email address, a login. Absent for a person’s; older approvals have it for theirs too.

string

name

The company connection’s name: its label, else the account’s label. A person’s own connection has none.

string

Example

{
  "requiredRole": "standard",
  "status": "pending",
  "decision": {
    "decision": "approve",
    "reviewerRoleAtDecision": "standard"
  },
  "withdrawnBecause": "run-cancelled",
  "approver": {
    "kind": "member"
  },
  "connection": {
    "as": "company"
  }
}

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

Example^generated

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

403

The caller isn’t a reviewer or the workspace’s admin.

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

Example^generated

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

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

Example^generated

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

503

The database was too busy to answer in time (database-busy); Retry-After (whole seconds) says when to try again.

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

Example^generated

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

See also

• POST /v1/approvals/{approvalId}/complete: Submit a decision on an approval
• POST /v1/approvals/{approvalId}/audit-bundle: Export a signed audit bundle for a decided approval
• Error code database-busy
• Every error code