Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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.

Caller API surface — what an integrator actually uses

The full reference below covers every endpoint, including the admin surface that powers AWE's own portal (policy CRUD, simulate, delegations, audit log, delivery retry). Caller services do not call any of those.

A Caller integration touches only the five endpoints below, plus implements one inbound webhook handler.

Outbound — Caller → AWE

API
When the Caller calls it

POST /v1/awe/requests

A Caller-owned artifact has been created and needs approval. Pass policy_key, artifact_type, artifact_id, context, callback_url, requester.

POST /v1/awe/requests/{id}/cancel

The underlying artifact was withdrawn, or the Caller wants to abort an in-flight flow.

GET /v1/awe/tasks?assignee=me (forwarding the approver's JWT)

When an approver opens the Caller's UI — returns every open AWE task assigned to the user whose JWT is on the request, across all requests and policies. me expands to the token's sub claim. The Caller joins this list with its own artifact rows (by awe_request_id) to build the per-Caller inbox.

POST /v1/awe/tasks/{task_id}/decision (forwarding the approver's JWT)

Records the approver's approve / reject / abstain.

GET /v1/awe/requests/{id} (optional)

Per-request lookup — full state of one approval flow by id (current stage, resolved approvers, history, context snapshot). Used when a user opens an artifact detail page in the Caller's UI and the Caller wants to render an "approval state" panel inline. Not an admin list view; takes a single id, returns one request. Skip it if you'd rather rely solely on the webhook to drive UI state. The Caller decides which users see this panel — AWE itself does not restrict reads.

Inbound — AWE → Caller (implemented by the Caller, not called)

Endpoint
What the Caller does

POST {callback_url}

Receives signed AWE webhooks. On request_approved apply the artifact-side effect; on request_rejected / request_cancelled close out the artifact accordingly. Validate the X-Approval-Signature HMAC, dedup on X-Approval-Event-Id, return 2xx within the configured timeout.

Everything else in the reference below is admin / operator surface served from AWE's bundled portal.

Error responses

Every non-2xx response returns AWE's standard error envelope with an AWE-NNN code in errors[0].errorCode. See the Error codes page for the full catalog — what each code means, the HTTP status it ships with, and whether to retry.


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
get/v1/awe/health
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
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
GET /v1/awe/config HTTP/1.1
Accept: */*
200

Successful Response

No content

Create the first draft of a new policy

post
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Body
policy_keystringRequiredExample: registry.change_request.v1
namestringRequiredExample: Registry CR approval
descriptionstring · nullableOptional
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
idstringRequired
policy_keystringRequired
versionintegerRequired
namestringRequired
descriptionstring · nullableOptional
statusstringRequired
artifact_typestringRequired
forbid_self_approvalbooleanOptionalDefault: false
forbid_repeat_approversbooleanOptionalDefault: false
created_bystring · nullableOptional
created_atstring · date-timeRequired
updated_atstring · date-timeRequired
post/v1/awe/policies
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-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "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
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Responses
200

Successful Response

application/json
idstringRequired
policy_keystringRequired
versionintegerRequired
namestringRequired
descriptionstring · nullableOptional
statusstringRequired
artifact_typestringRequired
forbid_self_approvalbooleanOptionalDefault: false
forbid_repeat_approversbooleanOptionalDefault: false
created_bystring · nullableOptional
created_atstring · date-timeRequired
updated_atstring · date-timeRequired
get/v1/awe/policies
GET /v1/awe/policies 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-01-01T00:00:00.000Z",
    "updated_at": "2026-01-01T00:00:00.000Z",
    "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
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
get/v1/awe/policies/{policy_key}/versions
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-01-01T00:00:00.000Z"
  }
]

Fetch a specific policy version with stages and rules

get
Authorizations
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
descriptionstring · nullableOptional
statusstringRequired
artifact_typestringRequired
forbid_self_approvalbooleanOptionalDefault: false
forbid_repeat_approversbooleanOptionalDefault: false
created_bystring · nullableOptional
created_atstring · date-timeRequired
updated_atstring · date-timeRequired
get/v1/awe/policies/{policy_key}/versions/{version}
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-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "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
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
policy_keystringRequired
versionintegerRequired
Body
policy_keystringRequiredExample: registry.change_request.v1
namestringRequiredExample: Registry CR approval
descriptionstring · nullableOptional
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
descriptionstring · nullableOptional
statusstringRequired
artifact_typestringRequired
forbid_self_approvalbooleanOptionalDefault: false
forbid_repeat_approversbooleanOptionalDefault: false
created_bystring · nullableOptional
created_atstring · date-timeRequired
updated_atstring · date-timeRequired
patch/v1/awe/policies/{policy_key}/versions/{version}
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-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "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
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
descriptionstring · nullableOptional
statusstringRequired
artifact_typestringRequired
forbid_self_approvalbooleanOptionalDefault: false
forbid_repeat_approversbooleanOptionalDefault: false
created_bystring · nullableOptional
created_atstring · date-timeRequired
updated_atstring · date-timeRequired
post/v1/awe/policies/{policy_key}/versions/{version}/activate
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-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "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
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
policy_keystringRequired
Body
policy_keystringRequiredExample: registry.change_request.v1
namestringRequiredExample: Registry CR approval
descriptionstring · nullableOptional
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
idstringRequired
policy_keystringRequired
versionintegerRequired
namestringRequired
descriptionstring · nullableOptional
statusstringRequired
artifact_typestringRequired
forbid_self_approvalbooleanOptionalDefault: false
forbid_repeat_approversbooleanOptionalDefault: false
created_bystring · nullableOptional
created_atstring · date-timeRequired
updated_atstring · date-timeRequired
put/v1/awe/policies/{policy_key}
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-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z",
  "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
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Query parameters
artifact_typestring · nullableOptional
artifact_idstring · nullableOptional
statusstring · nullableOptional
limitinteger · min: 1 · max: 100OptionalDefault: 50
Responses
200

Successful Response

application/json
idstringRequired
policy_idstringRequired
policy_keystringRequired
policy_versionintegerRequired
artifact_typestringRequired
artifact_idstringRequired
source_servicestringRequired
requesterstring · nullableOptional
statusstringRequired
current_stage_orderintegerRequired
callback_urlstring · nullableOptional
completed_atstring · date-time · nullableOptional
created_atstring · date-timeRequired
updated_atstring · date-timeRequired
get/v1/awe/requests
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-01-01T00:00:00.000Z",
    "created_at": "2026-01-01T00:00:00.000Z",
    "updated_at": "2026-01-01T00:00:00.000Z"
  }
]

Resolve approvers for a sample context — no DB writes

post
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
policy_keystringRequired
versionintegerRequired
Body
Responses
200

Successful Response

application/json
policy_idstringRequired
policy_versionintegerRequired
post/v1/awe/policies/{policy_key}/versions/{version}/simulate
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
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Header parameters
Idempotency-Keystring · nullableOptional
Body
policy_keystringRequiredExample: registry.change_request.v1
artifact_typestringRequiredExample: registry.change_request
artifact_idstringRequiredExample: cr-42
callback_urlstring · nullableOptionalExample: https://registry/internal/approval-callbacks
callback_secret_idstring · nullableOptional
requesterstring · nullableOptionalExample: u-alice
Responses
201

Successful Response

application/json
request_idstringRequired
statusstringRequired
current_stage_orderintegerRequired
post/v1/awe/requests
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",
      "assignee_name": "text",
      "kind": "approver",
      "delegated_from": "text",
      "reassigned_from": "text",
      "status": "text",
      "claimed_at": "2026-01-01T00:00:00.000Z",
      "completed_at": "2026-01-01T00:00:00.000Z",
      "due_at": "2026-01-01T00:00:00.000Z",
      "decision_id": "text",
      "decision_action": "text",
      "decision_comment": "text",
      "created_at": "2026-01-01T00:00:00.000Z",
      "context": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "artifact_type": "text",
      "artifact_id": "text",
      "policy_key": "text",
      "search_text": "text"
    }
  ]
}

Fetch an approval request by id

get
Authorizations
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
requesterstring · nullableOptional
statusstringRequired
current_stage_orderintegerRequired
callback_urlstring · nullableOptional
completed_atstring · date-time · nullableOptional
created_atstring · date-timeRequired
updated_atstring · date-timeRequired
get/v1/awe/requests/{request_id}
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-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Cancel an in-flight approval request (admin only)

post
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
request_idstringRequired
Body
reasonstring · nullableOptional
actorstring · nullableOptional
Responses
200

Successful Response

application/json
idstringRequired
policy_idstringRequired
policy_keystringRequired
policy_versionintegerRequired
artifact_typestringRequired
artifact_idstringRequired
source_servicestringRequired
requesterstring · nullableOptional
statusstringRequired
current_stage_orderintegerRequired
callback_urlstring · nullableOptional
completed_atstring · date-time · nullableOptional
created_atstring · date-timeRequired
updated_atstring · date-timeRequired
post/v1/awe/requests/{request_id}/cancel
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-01-01T00:00:00.000Z",
  "created_at": "2026-01-01T00:00:00.000Z",
  "updated_at": "2026-01-01T00:00:00.000Z"
}

Timeline of every event for a request (audit log)

get
Authorizations
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
get/v1/awe/requests/{request_id}/events
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-01-01T00:00:00.000Z"
  }
]

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

get
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Query parameters
assigneestring · nullableOptional

Filter by assignee. Default me resolves to preferred_username, then username, then 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
request_idstring · nullableOptional
statusstring · nullableOptional
artifact_typestring · nullableOptional
policy_keystring · nullableOptional
search_textstring · nullableOptional

Case-insensitive substring match against task search_text.

pageinteger · min: 1OptionalDefault: 1
page_sizeinteger · min: 1 · max: 100OptionalDefault: 25
Responses
200

Successful Response

application/json
totalintegerRequired
pageintegerRequired
page_sizeintegerRequired
pagesintegerRequired
get/v1/awe/tasks
GET /v1/awe/tasks HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
  "items": [
    {
      "id": "text",
      "request_id": "text",
      "stage_id": "text",
      "stage_order": 1,
      "assignee": "text",
      "assignee_name": "text",
      "kind": "approver",
      "delegated_from": "text",
      "reassigned_from": "text",
      "status": "text",
      "claimed_at": "2026-01-01T00:00:00.000Z",
      "completed_at": "2026-01-01T00:00:00.000Z",
      "due_at": "2026-01-01T00:00:00.000Z",
      "decision_id": "text",
      "decision_action": "text",
      "decision_comment": "text",
      "created_at": "2026-01-01T00:00:00.000Z",
      "context": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "artifact_type": "text",
      "artifact_id": "text",
      "policy_key": "text",
      "search_text": "text"
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 1,
  "pages": 1
}

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

post
Authorizations
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
assignee_namestring · nullableOptional
kindstringOptionalDefault: approver
delegated_fromstring · nullableOptional
reassigned_fromstring · nullableOptional
statusstringRequired
claimed_atstring · date-time · nullableOptional
completed_atstring · date-time · nullableOptional
due_atstring · date-time · nullableOptional
decision_idstring · nullableOptional
decision_actionstring · nullableOptional
decision_commentstring · nullableOptional
created_atstring · date-timeRequired
artifact_typestring · nullableOptional
artifact_idstring · nullableOptional
policy_keystring · nullableOptional
search_textstring · nullableOptional
post/v1/awe/tasks/{task_id}/claim
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",
  "assignee_name": "text",
  "kind": "approver",
  "delegated_from": "text",
  "reassigned_from": "text",
  "status": "text",
  "claimed_at": "2026-01-01T00:00:00.000Z",
  "completed_at": "2026-01-01T00:00:00.000Z",
  "due_at": "2026-01-01T00:00:00.000Z",
  "decision_id": "text",
  "decision_action": "text",
  "decision_comment": "text",
  "created_at": "2026-01-01T00:00:00.000Z",
  "context": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "artifact_type": "text",
  "artifact_id": "text",
  "policy_key": "text",
  "search_text": "text"
}

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

post
Authorizations
AuthorizationstringRequired
Bearer authentication header of the form Bearer <token>.
Path parameters
task_idstringRequired
Body
actionstringRequiredExample: approve
commentstring · nullableOptional
attachments_refstring · nullableOptional
Responses
201

Successful Response

application/json
idstringRequired
request_idstringRequired
task_idstringRequired
stage_orderintegerRequired
actorstringRequired
actionstringRequired
commentstring · nullableOptional
attachments_refstring · nullableOptional
created_atstring · date-timeRequired
post/v1/awe/tasks/{task_id}/decision
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-01-01T00:00:00.000Z"
}

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

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_orderinteger · nullableOptional
actorstring · nullableOptional
occurred_atstring · date-timeRequired
Responses
200

Successful Response

application/json
anyOptional

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-01-01T00:00:00.000Z"
}

Last updated

Was this helpful?