API Reference

REST API reference for the Approval Workflow Engine — rendered directly from the live OpenAPI 3.1 spec committed to the repo.

Base path: /v1/awe/. The spec below is rendered from the live docs/openapi.json. CI regenerates it from the FastAPI app on every src/-touching push, so endpoint signatures, response shapes, status-code descriptions, and the error-code catalog stay in lockstep with the code. This page does not duplicate any of that in prose.

A running instance also exposes the live spec at /v1/awe/openapi.json and interactive UIs at /v1/awe/docs (Swagger) and /v1/awe/redoc.

Health / readiness probe

get

Responses

200

Service is ready.

application/json

idstringOptionalDefault: openg2p.aweExample: openg2p.awe

versionstringOptionalDefault: 1.0Example: 1.0

responsetimestringRequiredExample: 2026-04-23T10:00:00.000Z

503

Not ready (AWE-005 startup; AWE-006 db).

get

/v1/awe/health

HTTPcURLJavaScriptPython

GET /v1/awe/health HTTP/1.1
Accept: */*

{
  "id": "openg2p.awe",
  "version": "1.0",
  "responsetime": "2026-04-23T10:00:00.000Z",
  "response": {
    "status": "UP"
  },
  "errors": [
    {
      "errorCode": "AWE-003",
      "message": "Approval request not found"
    }
  ]
}

Service version + build metadata

get

Responses

200

Successful Response

application/json

idstringOptionalDefault: openg2p.aweExample: openg2p.awe

versionstringOptionalDefault: 1.0Example: 1.0

responsetimestringRequiredExample: 2026-04-23T10:00:00.000Z

get

/v1/awe/version

HTTPcURLJavaScriptPython

GET /v1/awe/version HTTP/1.1
Accept: */*

200

Successful Response

{
  "id": "openg2p.awe",
  "version": "1.0",
  "responsetime": "2026-04-23T10:00:00.000Z",
  "response": {
    "service_version": "0.1.0",
    "build_time": "2026-04-23T08:30:00.000Z",
    "git_commit": "a1b2c3d"
  },
  "errors": [
    {
      "errorCode": "AWE-003",
      "message": "Approval request not found"
    }
  ]
}

Effective non-sensitive configuration

get

Responses

200

Successful Response

application/json

anyOptional

get

/v1/awe/config

HTTPcURLJavaScriptPython

GET /v1/awe/config HTTP/1.1
Accept: */*

200

Successful Response

No content

Create the first draft of a new policy

post

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Body

application/json

policy_keystringRequiredExample: registry.change_request.v1

namestringRequiredExample: Registry CR approval

descriptionany ofOptional

stringOptional

or

nullOptional

artifact_typestringRequiredExample: registry.change_request

forbid_self_approvalbooleanOptional

Filter the request's requester out of every stage's approver list.

Default: false

forbid_repeat_approversbooleanOptional

Filter users who approved an earlier stage out of later stages.

Default: false

Responses

201

Successful Response

application/json

422

Validation Error

application/json

post

/v1/awe/policies

HTTPcURLJavaScriptPython

POST /v1/awe/policies HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 628

{
  "policy_key": "registry.change_request.v1",
  "name": "Registry CR approval",
  "description": "text",
  "artifact_type": "registry.change_request",
  "forbid_self_approval": false,
  "forbid_repeat_approvers": false,
  "stages": [
    {
      "name": "District officers",
      "stage_order": 1,
      "mode": "any-n",
      "mode_value": 1,
      "sla_hours": 1,
      "skip_if": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "on_empty": "block",
      "parallel_group": 1,
      "on_breach": "text",
      "escalation_rules": [
        {
          "rule_type": "role",
          "rule_value": {
            "role": "district-officer"
          },
          "kind": "approver",
          "required": false
        }
      ],
      "rules": [
        {
          "rule_type": "role",
          "rule_value": {
            "role": "district-officer"
          },
          "kind": "approver",
          "required": false
        }
      ]
    }
  ]
}

{
  "id": "text",
  "policy_key": "text",
  "version": 1,
  "name": "text",
  "description": "text",
  "status": "text",
  "artifact_type": "text",
  "forbid_self_approval": false,
  "forbid_repeat_approvers": false,
  "created_by": "text",
  "created_at": "2026-05-09T16:39:20.717Z",
  "updated_at": "2026-05-09T16:39:20.717Z",
  "stages": [
    {
      "name": "District officers",
      "stage_order": 1,
      "mode": "any-n",
      "mode_value": 1,
      "sla_hours": 1,
      "skip_if": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "on_empty": "block",
      "parallel_group": 1,
      "on_breach": "text",
      "escalation_rules": [
        {
          "rule_type": "role",
          "rule_value": {
            "role": "district-officer"
          },
          "kind": "approver",
          "required": false,
          "id": "text"
        }
      ],
      "rules": [
        {
          "rule_type": "role",
          "rule_value": {
            "role": "district-officer"
          },
          "kind": "approver",
          "required": false,
          "id": "text"
        }
      ],
      "id": "text"
    }
  ]
}

List policies (newest version of each policy_key)

get

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Responses

200

Successful Response

application/json

idstringRequired

policy_keystringRequired

versionintegerRequired

namestringRequired

descriptionany ofOptional

stringOptional

or

nullOptional

statusstringRequired

artifact_typestringRequired

forbid_self_approvalbooleanOptionalDefault: false

forbid_repeat_approversbooleanOptionalDefault: false

created_byany ofOptional

stringOptional

or

nullOptional

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

get

/v1/awe/policies

HTTPcURLJavaScriptPython

GET /v1/awe/policies HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Successful Response

[
  {
    "id": "text",
    "policy_key": "text",
    "version": 1,
    "name": "text",
    "description": "text",
    "status": "text",
    "artifact_type": "text",
    "forbid_self_approval": false,
    "forbid_repeat_approvers": false,
    "created_by": "text",
    "created_at": "2026-05-09T16:39:20.717Z",
    "updated_at": "2026-05-09T16:39:20.717Z",
    "stages": [
      {
        "name": "District officers",
        "stage_order": 1,
        "mode": "any-n",
        "mode_value": 1,
        "sla_hours": 1,
        "skip_if": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        },
        "on_empty": "block",
        "parallel_group": 1,
        "on_breach": "text",
        "escalation_rules": [
          {
            "rule_type": "role",
            "rule_value": {
              "role": "district-officer"
            },
            "kind": "approver",
            "required": false,
            "id": "text"
          }
        ],
        "rules": [
          {
            "rule_type": "role",
            "rule_value": {
              "role": "district-officer"
            },
            "kind": "approver",
            "required": false,
            "id": "text"
          }
        ],
        "id": "text"
      }
    ]
  }
]

List all versions of a policy_key

get

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

policy_keystringRequired

Responses

200

Successful Response

application/json

idstringRequired

policy_keystringRequired

versionintegerRequired

statusstringRequired

created_atstring · date-timeRequired

422

Validation Error

application/json

get

/v1/awe/policies/{policy_key}/versions

HTTPcURLJavaScriptPython

GET /v1/awe/policies/{policy_key}/versions HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "id": "text",
    "policy_key": "text",
    "version": 1,
    "status": "text",
    "created_at": "2026-05-09T16:39:20.717Z"
  }
]

Fetch a specific policy version with stages and rules

get

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

policy_keystringRequired

versionintegerRequired

Responses

200

Successful Response

application/json

idstringRequired

policy_keystringRequired

versionintegerRequired

namestringRequired

descriptionany ofOptional

stringOptional

or

nullOptional

statusstringRequired

artifact_typestringRequired

forbid_self_approvalbooleanOptionalDefault: false

forbid_repeat_approversbooleanOptionalDefault: false

created_byany ofOptional

stringOptional

or

nullOptional

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

422

Validation Error

application/json

get

/v1/awe/policies/{policy_key}/versions/{version}

HTTPcURLJavaScriptPython

GET /v1/awe/policies/{policy_key}/versions/{version} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "policy_key": "text",
  "version": 1,
  "name": "text",
  "description": "text",
  "status": "text",
  "artifact_type": "text",
  "forbid_self_approval": false,
  "forbid_repeat_approvers": false,
  "created_by": "text",
  "created_at": "2026-05-09T16:39:20.717Z",
  "updated_at": "2026-05-09T16:39:20.717Z",
  "stages": [
    {
      "name": "District officers",
      "stage_order": 1,
      "mode": "any-n",
      "mode_value": 1,
      "sla_hours": 1,
      "skip_if": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "on_empty": "block",
      "parallel_group": 1,
      "on_breach": "text",
      "escalation_rules": [
        {
          "rule_type": "role",
          "rule_value": {
            "role": "district-officer"
          },
          "kind": "approver",
          "required": false,
          "id": "text"
        }
      ],
      "rules": [
        {
          "rule_type": "role",
          "rule_value": {
            "role": "district-officer"
          },
          "kind": "approver",
          "required": false,
          "id": "text"
        }
      ],
      "id": "text"
    }
  ]
}

Edit a draft version in place (drafts only)

patch

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

policy_keystringRequired

versionintegerRequired

Body

application/json

policy_keystringRequiredExample: registry.change_request.v1

namestringRequiredExample: Registry CR approval

descriptionany ofOptional

stringOptional

or

nullOptional

artifact_typestringRequiredExample: registry.change_request

forbid_self_approvalbooleanOptional

Filter the request's requester out of every stage's approver list.

Default: false

forbid_repeat_approversbooleanOptional

Filter users who approved an earlier stage out of later stages.

Default: false

Responses

200

Successful Response

application/json

idstringRequired

policy_keystringRequired

versionintegerRequired

namestringRequired

descriptionany ofOptional

stringOptional

or

nullOptional

statusstringRequired

artifact_typestringRequired

forbid_self_approvalbooleanOptionalDefault: false

forbid_repeat_approversbooleanOptionalDefault: false

created_byany ofOptional

stringOptional

or

nullOptional

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

422

Validation Error

application/json

patch

/v1/awe/policies/{policy_key}/versions/{version}

HTTPcURLJavaScriptPython

PATCH /v1/awe/policies/{policy_key}/versions/{version} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 628

{
  "policy_key": "registry.change_request.v1",
  "name": "Registry CR approval",
  "description": "text",
  "artifact_type": "registry.change_request",
  "forbid_self_approval": false,
  "forbid_repeat_approvers": false,
  "stages": [
    {
      "name": "District officers",
      "stage_order": 1,
      "mode": "any-n",
      "mode_value": 1,
      "sla_hours": 1,
      "skip_if": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "on_empty": "block",
      "parallel_group": 1,
      "on_breach": "text",
      "escalation_rules": [
        {
          "rule_type": "role",
          "rule_value": {
            "role": "district-officer"
          },
          "kind": "approver",
          "required": false
        }
      ],
      "rules": [
        {
          "rule_type": "role",
          "rule_value": {
            "role": "district-officer"
          },
          "kind": "approver",
          "required": false
        }
      ]
    }
  ]
}

{
  "id": "text",
  "policy_key": "text",
  "version": 1,
  "name": "text",
  "description": "text",
  "status": "text",
  "artifact_type": "text",
  "forbid_self_approval": false,
  "forbid_repeat_approvers": false,
  "created_by": "text",
  "created_at": "2026-05-09T16:39:20.717Z",
  "updated_at": "2026-05-09T16:39:20.717Z",
  "stages": [
    {
      "name": "District officers",
      "stage_order": 1,
      "mode": "any-n",
      "mode_value": 1,
      "sla_hours": 1,
      "skip_if": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "on_empty": "block",
      "parallel_group": 1,
      "on_breach": "text",
      "escalation_rules": [
        {
          "rule_type": "role",
          "rule_value": {
            "role": "district-officer"
          },
          "kind": "approver",
          "required": false,
          "id": "text"
        }
      ],
      "rules": [
        {
          "rule_type": "role",
          "rule_value": {
            "role": "district-officer"
          },
          "kind": "approver",
          "required": false,
          "id": "text"
        }
      ],
      "id": "text"
    }
  ]
}

Activate a specific version (archives the previously active one)

post

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

policy_keystringRequired

versionintegerRequired

Responses

200

Successful Response

application/json

idstringRequired

policy_keystringRequired

versionintegerRequired

namestringRequired

descriptionany ofOptional

stringOptional

or

nullOptional

statusstringRequired

artifact_typestringRequired

forbid_self_approvalbooleanOptionalDefault: false

forbid_repeat_approversbooleanOptionalDefault: false

created_byany ofOptional

stringOptional

or

nullOptional

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

422

Validation Error

application/json

post

/v1/awe/policies/{policy_key}/versions/{version}/activate

HTTPcURLJavaScriptPython

POST /v1/awe/policies/{policy_key}/versions/{version}/activate HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "policy_key": "text",
  "version": 1,
  "name": "text",
  "description": "text",
  "status": "text",
  "artifact_type": "text",
  "forbid_self_approval": false,
  "forbid_repeat_approvers": false,
  "created_by": "text",
  "created_at": "2026-05-09T16:39:20.717Z",
  "updated_at": "2026-05-09T16:39:20.717Z",
  "stages": [
    {
      "name": "District officers",
      "stage_order": 1,
      "mode": "any-n",
      "mode_value": 1,
      "sla_hours": 1,
      "skip_if": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "on_empty": "block",
      "parallel_group": 1,
      "on_breach": "text",
      "escalation_rules": [
        {
          "rule_type": "role",
          "rule_value": {
            "role": "district-officer"
          },
          "kind": "approver",
          "required": false,
          "id": "text"
        }
      ],
      "rules": [
        {
          "rule_type": "role",
          "rule_value": {
            "role": "district-officer"
          },
          "kind": "approver",
          "required": false,
          "id": "text"
        }
      ],
      "id": "text"
    }
  ]
}

Add a new draft version under an existing policy_key

put

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

policy_keystringRequired

Body

application/json

policy_keystringRequiredExample: registry.change_request.v1

namestringRequiredExample: Registry CR approval

descriptionany ofOptional

stringOptional

or

nullOptional

artifact_typestringRequiredExample: registry.change_request

forbid_self_approvalbooleanOptional

Filter the request's requester out of every stage's approver list.

Default: false

forbid_repeat_approversbooleanOptional

Filter users who approved an earlier stage out of later stages.

Default: false

Responses

201

Successful Response

application/json

422

Validation Error

application/json

put

/v1/awe/policies/{policy_key}

HTTPcURLJavaScriptPython

PUT /v1/awe/policies/{policy_key} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 628

{
  "policy_key": "registry.change_request.v1",
  "name": "Registry CR approval",
  "description": "text",
  "artifact_type": "registry.change_request",
  "forbid_self_approval": false,
  "forbid_repeat_approvers": false,
  "stages": [
    {
      "name": "District officers",
      "stage_order": 1,
      "mode": "any-n",
      "mode_value": 1,
      "sla_hours": 1,
      "skip_if": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "on_empty": "block",
      "parallel_group": 1,
      "on_breach": "text",
      "escalation_rules": [
        {
          "rule_type": "role",
          "rule_value": {
            "role": "district-officer"
          },
          "kind": "approver",
          "required": false
        }
      ],
      "rules": [
        {
          "rule_type": "role",
          "rule_value": {
            "role": "district-officer"
          },
          "kind": "approver",
          "required": false
        }
      ]
    }
  ]
}

{
  "id": "text",
  "policy_key": "text",
  "version": 1,
  "name": "text",
  "description": "text",
  "status": "text",
  "artifact_type": "text",
  "forbid_self_approval": false,
  "forbid_repeat_approvers": false,
  "created_by": "text",
  "created_at": "2026-05-09T16:39:20.717Z",
  "updated_at": "2026-05-09T16:39:20.717Z",
  "stages": [
    {
      "name": "District officers",
      "stage_order": 1,
      "mode": "any-n",
      "mode_value": 1,
      "sla_hours": 1,
      "skip_if": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "on_empty": "block",
      "parallel_group": 1,
      "on_breach": "text",
      "escalation_rules": [
        {
          "rule_type": "role",
          "rule_value": {
            "role": "district-officer"
          },
          "kind": "approver",
          "required": false,
          "id": "text"
        }
      ],
      "rules": [
        {
          "rule_type": "role",
          "rule_value": {
            "role": "district-officer"
          },
          "kind": "approver",
          "required": false,
          "id": "text"
        }
      ],
      "id": "text"
    }
  ]
}

Search requests by artifact reference and/or status

get

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

artifact_typeany ofOptional

stringOptional

or

nullOptional

artifact_idany ofOptional

stringOptional

or

nullOptional

statusany ofOptional

stringOptional

or

nullOptional

limitinteger · min: 1 · max: 500OptionalDefault: 50

Responses

200

Successful Response

application/json

idstringRequired

policy_idstringRequired

policy_keystringRequired

policy_versionintegerRequired

artifact_typestringRequired

artifact_idstringRequired

source_servicestringRequired

requesterany ofOptional

stringOptional

or

nullOptional

statusstringRequired

current_stage_orderintegerRequired

callback_urlany ofOptional

stringOptional

or

nullOptional

completed_atany ofOptional

string · date-timeOptional

or

nullOptional

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

422

Validation Error

application/json

get

/v1/awe/requests

HTTPcURLJavaScriptPython

GET /v1/awe/requests HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "id": "text",
    "policy_id": "text",
    "policy_key": "text",
    "policy_version": 1,
    "artifact_type": "text",
    "artifact_id": "text",
    "source_service": "text",
    "requester": "text",
    "context": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "status": "text",
    "current_stage_order": 1,
    "callback_url": "text",
    "completed_at": "2026-05-09T16:39:20.717Z",
    "created_at": "2026-05-09T16:39:20.717Z",
    "updated_at": "2026-05-09T16:39:20.717Z"
  }
]

Resolve approvers for a sample context — no DB writes

post

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

policy_keystringRequired

versionintegerRequired

Body

application/json

Responses

200

Successful Response

application/json

policy_idstringRequired

policy_versionintegerRequired

422

Validation Error

application/json

post

/v1/awe/policies/{policy_key}/versions/{version}/simulate

HTTPcURLJavaScriptPython

POST /v1/awe/policies/{policy_key}/versions/{version}/simulate HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 44

{
  "context": {
    "amount": 15000,
    "district": "D1"
  }
}

{
  "policy_id": "text",
  "policy_version": 1,
  "stages": [
    {
      "stage_order": 1,
      "name": "text",
      "mode": "text",
      "mode_value": 1,
      "resolved_approvers": [
        "text"
      ],
      "skipped": false,
      "skip_reason": "text"
    }
  ]
}

Create an approval request for a caller-owned artifact

post

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Header parameters

Idempotency-Keyany ofOptional

stringOptional

or

nullOptional

Body

application/json

policy_keystringRequiredExample: registry.change_request.v1

artifact_typestringRequiredExample: registry.change_request

artifact_idstringRequiredExample: cr-42

callback_urlany ofOptionalExample: https://registry/internal/approval-callbacks

stringOptional

or

nullOptional

callback_secret_idany ofOptional

stringOptional

or

nullOptional

requesterany ofOptionalExample: u-alice

stringOptional

or

nullOptional

Responses

201

Successful Response

application/json

422

Validation Error

application/json

post

/v1/awe/requests

HTTPcURLJavaScriptPython

POST /v1/awe/requests HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 262

{
  "policy_key": "registry.change_request.v1",
  "artifact_type": "registry.change_request",
  "artifact_id": "cr-42",
  "context": {
    "amount": 15000,
    "district": "D1"
  },
  "callback_url": "https://registry/internal/approval-callbacks",
  "callback_secret_id": "text",
  "requester": "u-alice"
}

{
  "request_id": "text",
  "status": "text",
  "current_stage_order": 1,
  "tasks": [
    {
      "id": "text",
      "request_id": "text",
      "stage_id": "text",
      "stage_order": 1,
      "assignee": "text",
      "kind": "approver",
      "delegated_from": "text",
      "reassigned_from": "text",
      "status": "text",
      "claimed_at": "2026-05-09T16:39:20.717Z",
      "completed_at": "2026-05-09T16:39:20.717Z",
      "due_at": "2026-05-09T16:39:20.717Z",
      "decision_id": "text",
      "created_at": "2026-05-09T16:39:20.717Z"
    }
  ]
}

Fetch an approval request by id

get

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

request_idstringRequired

Responses

200

Successful Response

application/json

idstringRequired

policy_idstringRequired

policy_keystringRequired

policy_versionintegerRequired

artifact_typestringRequired

artifact_idstringRequired

source_servicestringRequired

requesterany ofOptional

stringOptional

or

nullOptional

statusstringRequired

current_stage_orderintegerRequired

callback_urlany ofOptional

stringOptional

or

nullOptional

completed_atany ofOptional

string · date-timeOptional

or

nullOptional

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

422

Validation Error

application/json

get

/v1/awe/requests/{request_id}

HTTPcURLJavaScriptPython

GET /v1/awe/requests/{request_id} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "policy_id": "text",
  "policy_key": "text",
  "policy_version": 1,
  "artifact_type": "text",
  "artifact_id": "text",
  "source_service": "text",
  "requester": "text",
  "context": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "status": "text",
  "current_stage_order": 1,
  "callback_url": "text",
  "completed_at": "2026-05-09T16:39:20.717Z",
  "created_at": "2026-05-09T16:39:20.717Z",
  "updated_at": "2026-05-09T16:39:20.717Z"
}

Cancel an in-flight approval request (admin only)

post

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

request_idstringRequired

Body

application/json

reasonany ofOptional

stringOptional

or

nullOptional

actorany ofOptional

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

idstringRequired

policy_idstringRequired

policy_keystringRequired

policy_versionintegerRequired

artifact_typestringRequired

artifact_idstringRequired

source_servicestringRequired

requesterany ofOptional

stringOptional

or

nullOptional

statusstringRequired

current_stage_orderintegerRequired

callback_urlany ofOptional

stringOptional

or

nullOptional

completed_atany ofOptional

string · date-timeOptional

or

nullOptional

created_atstring · date-timeRequired

updated_atstring · date-timeRequired

422

Validation Error

application/json

post

/v1/awe/requests/{request_id}/cancel

HTTPcURLJavaScriptPython

POST /v1/awe/requests/{request_id}/cancel HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 32

{
  "reason": "text",
  "actor": "text"
}

{
  "id": "text",
  "policy_id": "text",
  "policy_key": "text",
  "policy_version": 1,
  "artifact_type": "text",
  "artifact_id": "text",
  "source_service": "text",
  "requester": "text",
  "context": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "status": "text",
  "current_stage_order": 1,
  "callback_url": "text",
  "completed_at": "2026-05-09T16:39:20.717Z",
  "created_at": "2026-05-09T16:39:20.717Z",
  "updated_at": "2026-05-09T16:39:20.717Z"
}

Timeline of every event for a request (audit log)

get

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

request_idstringRequired

Responses

200

Successful Response

application/json

idstringRequired

request_idstringRequired

event_typestringRequired

created_atstring · date-timeRequired

422

Validation Error

application/json

get

/v1/awe/requests/{request_id}/events

HTTPcURLJavaScriptPython

GET /v1/awe/requests/{request_id}/events HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "id": "text",
    "request_id": "text",
    "event_type": "text",
    "payload": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "created_at": "2026-05-09T16:39:20.717Z"
  }
]

List tasks — by assignee (default = me) and/or by request_id

get

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Query parameters

assigneeany ofOptional

Filter by assignee. Default me resolves to the token's sub. Pass * (or any non-me value) plus request_id to enumerate all tasks for a given request — used by the admin Request Detail page.

Default: me

stringOptional

or

nullOptional

request_idany ofOptional

stringOptional

or

nullOptional

statusany ofOptional

stringOptional

or

nullOptional

limitinteger · min: 1 · max: 500OptionalDefault: 100

Responses

200

Successful Response

application/json

idstringRequired

request_idstringRequired

stage_idstringRequired

stage_orderintegerRequired

assigneestringRequired

kindstringOptionalDefault: approver

delegated_fromany ofOptional

stringOptional

or

nullOptional

reassigned_fromany ofOptional

stringOptional

or

nullOptional

statusstringRequired

claimed_atany ofOptional

string · date-timeOptional

or

nullOptional

completed_atany ofOptional

string · date-timeOptional

or

nullOptional

due_atany ofOptional

string · date-timeOptional

or

nullOptional

decision_idany ofOptional

stringOptional

or

nullOptional

created_atstring · date-timeRequired

422

Validation Error

application/json

get

/v1/awe/tasks

HTTPcURLJavaScriptPython

GET /v1/awe/tasks HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

[
  {
    "id": "text",
    "request_id": "text",
    "stage_id": "text",
    "stage_order": 1,
    "assignee": "text",
    "kind": "approver",
    "delegated_from": "text",
    "reassigned_from": "text",
    "status": "text",
    "claimed_at": "2026-05-09T16:39:20.717Z",
    "completed_at": "2026-05-09T16:39:20.717Z",
    "due_at": "2026-05-09T16:39:20.717Z",
    "decision_id": "text",
    "created_at": "2026-05-09T16:39:20.717Z"
  }
]

Claim a task (intent-to-act marker; not required for decision)

post

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

task_idstringRequired

Responses

200

Successful Response

application/json

idstringRequired

request_idstringRequired

stage_idstringRequired

stage_orderintegerRequired

assigneestringRequired

kindstringOptionalDefault: approver

delegated_fromany ofOptional

stringOptional

or

nullOptional

reassigned_fromany ofOptional

stringOptional

or

nullOptional

statusstringRequired

claimed_atany ofOptional

string · date-timeOptional

or

nullOptional

completed_atany ofOptional

string · date-timeOptional

or

nullOptional

due_atany ofOptional

string · date-timeOptional

or

nullOptional

decision_idany ofOptional

stringOptional

or

nullOptional

created_atstring · date-timeRequired

422

Validation Error

application/json

post

/v1/awe/tasks/{task_id}/claim

HTTPcURLJavaScriptPython

POST /v1/awe/tasks/{task_id}/claim HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "id": "text",
  "request_id": "text",
  "stage_id": "text",
  "stage_order": 1,
  "assignee": "text",
  "kind": "approver",
  "delegated_from": "text",
  "reassigned_from": "text",
  "status": "text",
  "claimed_at": "2026-05-09T16:39:20.717Z",
  "completed_at": "2026-05-09T16:39:20.717Z",
  "due_at": "2026-05-09T16:39:20.717Z",
  "decision_id": "text",
  "created_at": "2026-05-09T16:39:20.717Z"
}

Record a decision (approve / reject / abstain) on a task

post

Authorizations

HTTPBearer

AuthorizationstringRequired

Bearer authentication header of the form Bearer <token>.

Path parameters

task_idstringRequired

Body

application/json

actionstringRequiredExample: approve

commentany ofOptional

stringOptional

or

nullOptional

attachments_refany ofOptional

stringOptional

or

nullOptional

Responses

201

Successful Response

application/json

422

Validation Error

application/json

post

/v1/awe/tasks/{task_id}/decision

HTTPcURLJavaScriptPython

POST /v1/awe/tasks/{task_id}/decision HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 62

{
  "action": "approve",
  "comment": "text",
  "attachments_ref": "text"
}

{
  "id": "text",
  "request_id": "text",
  "task_id": "text",
  "stage_order": 1,
  "actor": "text",
  "action": "text",
  "comment": "text",
  "attachments_ref": "text",
  "created_at": "2026-05-09T16:39:20.717Z"
}

Webhook (outbound from AWE → Caller)

AWE POSTs to whatever callback_url was set on the request whenever a status-changing event occurs. The contract — body schema and the three signed headers — is declared in the OpenAPI spec under the top-level webhooks: field (OpenAPI 3.1 feature) so it's discoverable from the same artifact as the rest of the API.

Approval workflow state change

Sent by AWE to the caller's callback_url whenever a status-changing event occurs on an approval request — request_created, stage_started, stage_completed, request_approved, request_rejected, request_cancelled, or task_expired.

Signature scheme: X-Approval-Signature is sha256= + HMAC-SHA256 over <X-Approval-Timestamp>.<raw body> using the per-caller shared secret. The caller must verify the signature, dedup on X-Approval-Event-Id, and return any 2xx within the configured timeout (default 10s). Non-2xx triggers retries on the schedule documented in functional-specifications (1m → 5m → 15m → 1h → 6h, ~27h total).

Header parameters

X-Approval-Event-IdstringRequired

X-Approval-TimestampstringRequired

X-Approval-SignaturestringRequired

Payload

application/json

The body POSTed to the caller's callback_url.

Headers (set by the dispatcher, not part of this body): X-Approval-Event-Id — same as event_id below X-Approval-Signature — sha256=<hex>, HMAC over the raw body X-Approval-Timestamp — Unix seconds, included in the signed payload

event_idstringRequiredExample: 7f3e...

event_typestringRequired

request_created | stage_started | stage_completed | request_approved | request_rejected | request_cancelled

Example: request_approved

request_idstringRequired

artifact_typestringRequired

artifact_idstringRequired

statusstringRequired

stage_orderany ofOptional

integerOptional

or

nullOptional

actorany ofOptional

stringOptional

or

nullOptional

occurred_atstring · date-timeRequired

Responses

200

Successful Response

application/json

anyOptional

422

Validation Error

application/json

Payload

{
  "event_id": "7f3e...",
  "event_type": "request_approved",
  "request_id": "text",
  "artifact_type": "text",
  "artifact_id": "text",
  "status": "text",
  "stage_order": 1,
  "actor": "text",
  "occurred_at": "2026-05-09T16:39:20.717Z"
}