> For the complete documentation index, see [llms.txt](https://guardian.hedera.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guardian.hedera.com/docs/develop/developer-tools-and-resources/api-reference/policy-grid-actions.md).

# Policy Grid Actions APIs

The Policy Grid Actions API lets external integrators discover and execute workflow actions (e.g. **Approve**, **Reject**) defined inside Guardian policy grid containers — without reverse-engineering the internal policy block structure or touching any ephemeral block UUID.

## Concept

A Guardian policy organises its UI into **grid containers** (`interfaceDocumentsSourceBlock`). Each grid contains **rows** (VC documents) and **action controls** bound to individual columns. Three kinds of controls are supported:

* **Selector / button actions** (Approve/Reject-style) — apply a fixed field mutation, body is `{}`.
* **Dropdown actions** — assign a value chosen from a live list (e.g. assigning a VVB to a project), body is `{ "value": "..." }`.
* **Request-VC-document actions** — submit a form that mints a brand-new signed VC referencing the row (e.g. "Submit Final Amount"), body is `{ "document": { ... } }`.

The exact body shape for a given action is always described by its `inputSchema`, returned by [List Actions](/docs/develop/developer-tools-and-resources/api-reference/policy-grid-actions/list-actions.md) — check it rather than assuming an empty body works.

The Grid Actions API exposes three stable abstractions:

| Concept    | Stable identifier                                                                         | Notes                               |
| ---------- | ----------------------------------------------------------------------------------------- | ----------------------------------- |
| **Grid**   | `gridId` — the block's author-assigned `.tag`, or `sha256(uuid).slice(0,16)` fallback     | Stable across policy redeploys      |
| **Action** | `actionId` — the option `.tag` (for selector actions) or the block `.tag` / hash fallback | Returned by List Actions            |
| **Record** | `_id` — the MongoDB document `_id` returned by Get Records                                | Use verbatim in Execute Action call |

Block UUIDs are never exposed in any request or response.

## Authentication

All endpoints require a valid Guardian JWT bearer token in the `Authorization` header. The caller must hold at least one of:

* `POLICIES_POLICY_EXECUTE`
* `POLICIES_POLICY_MANAGE`

Actions are further filtered by the caller's policy role — the API never returns or allows execution of actions whose `requiredRoles` the caller does not hold.

***

## Endpoints

| # | Endpoint                                                                                                          | Description                                |
| - | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| 1 | [List Grids](/docs/develop/developer-tools-and-resources/api-reference/policy-grid-actions/list-grids.md)         | Discover all grids visible to the caller   |
| 2 | [List Actions](/docs/develop/developer-tools-and-resources/api-reference/policy-grid-actions/list-actions.md)     | List executable actions on a specific grid |
| 3 | [Get Records](/docs/develop/developer-tools-and-resources/api-reference/policy-grid-actions/get-records.md)       | Fetch paginated records from a grid        |
| 4 | [Execute Action](/docs/develop/developer-tools-and-resources/api-reference/policy-grid-actions/execute-action.md) | Trigger a workflow action on a record      |

***

## Workflow Example — Approve a Document

**Step 1 — Discover grids**

`GET /policies/{policyId}/grids`

```json
[
  {
    "gridId": "installer_documents_grid",
    "title": "Installer Activity Reports",
    "columnSchema": [
      { "name": "status", "title": "Status", "type": "text", "bindActions": ["approve_action", "reject_action"] }
    ]
  }
]
```

**Step 2 — List available actions**

`GET /policies/{policyId}/grids/installer_documents_grid/actions`

```json
[
  { "actionId": "approve_action", "label": "Approved", "requiredRoles": ["Standard Registry"], "appliesTo": "row" },
  { "actionId": "reject_action",  "label": "Rejected",  "requiredRoles": ["Standard Registry"], "appliesTo": "row" }
]
```

**Step 3 — Fetch records**

`GET /policies/{policyId}/grids/installer_documents_grid/records?pageSize=1`

```json
{
  "data": [
    {
      "_id": "6627f3b2e4b0c1a2b3c4d5e6",
      "owner": "did:hedera:testnet:z...",
      "option": { "status": "Submitted" },
      "_actions": ["approve_action", "reject_action"]
    }
  ],
  "page": 1,
  "pageSize": 1,
  "totalCount": 42,
  "hasNextPage": true,
  "hasPreviousPage": false
}
```

**Step 4 — Execute the approve action**

`POST /policies/{policyId}/grids/installer_documents_grid/records/6627f3b2e4b0c1a2b3c4d5e6/actions/approve_action`

Request body:

```json
{}
```

Response `200 OK`:

```json
{}
```

**Step 5 — Confirm the change**

Re-fetch the record — `option.status` is now `"Approved"`:

```json
{
  "data": [
    {
      "_id": "6627f3b2e4b0c1a2b3c4d5e6",
      "option": { "status": "Approved" },
      "_actions": ["approve_action", "reject_action"]
    }
  ]
}
```

***

## Error Reference

| HTTP status | Meaning                                                                                                                    |
| ----------- | -------------------------------------------------------------------------------------------------------------------------- |
| 400         | Execute Action call is missing a body field the action requires (`value` for dropdown, `document` for request-VC-document) |
| 401         | Missing or invalid JWT                                                                                                     |
| 403         | Caller lacks required permission (`POLICIES_POLICY_EXECUTE` / `POLICIES_POLICY_MANAGE`)                                    |
| 404         | `gridId`, `actionId`, or `recordId` not found                                                                              |
| 503         | Policy instance not running, or grid / action not available to the caller's role                                           |
| 500         | Unexpected internal error                                                                                                  |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://guardian.hedera.com/docs/develop/developer-tools-and-resources/api-reference/policy-grid-actions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.