> For the complete documentation index, see [llms.txt](https://docs.guardianservice.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.guardianservice.app/technical-information/top-line-apis.md).

# Top Line APIs

## Policy API Documentation & DMRV Aliases

### Summary

Policy authors can define clean, human-readable API endpoint aliases for their policies, giving each integration point a simple, descriptive name instead of a raw internal URL. These aliases, along with descriptions, can be configured directly in the policy editor and are published as browsable documentation, making it easier for external systems and third-party developers to integrate with a policy's API.

***

### 1. Configuring API Documentation

#### 1.1. Open the Configuration Dialog

1. Open any policy in **Draft** status in the Policy Configurator.
2. Click the **API** button in the top toolbar.

<figure><img src="/files/T0XwWNNzabnVE7067HTi" alt=""><figcaption></figcaption></figure>

#### 1.2. Add Endpoints

1. Click **+ Add Endpoint**.
2. Fill in the fields for each row:

<table><thead><tr><th width="225.86328125">Field</th><th>Description</th></tr></thead><tbody><tr><td>Block</td><td>Select a block from the dropdown list</td></tr><tr><td>Method</td><td>Choose <code>BOTH</code>, <code>GET</code> or <code>POST</code></td></tr><tr><td>Name</td><td>Short name (auto-filled from block name)</td></tr><tr><td>Description</td><td>What the endpoint does</td></tr><tr><td>Alias</td><td>URL-friendly identifier, e.g. <code>new-device</code>, <code>create-application</code></td></tr><tr><td>Preview URL</td><td>Read-only: <code>/api/v1/dmrv/{policyId}/{alias}</code></td></tr></tbody></table>

<figure><img src="/files/WHRk7ajnlHlNO6gKgAQX" alt=""><figcaption></figcaption></figure>

#### 1.3. Validation Rules

* **Alias:** only `a-z`, `0-9`, `-` allowed
* **Block** and **Alias** must be unique
* **Block** and **Alias** are required

Errors appear below the corresponding row.

<figure><img src="/files/AiQ9FZPvDbmVD2pSlzfL" alt=""><figcaption></figcaption></figure>

#### 1.4. Save

1. Click **Save** in the modal to apply changes locally.
2. Click **Save** in the toolbar to persist the policy to the database.

> **Note:** URL generation (both technical and DMRV) happens server-side on policy save.

***

### 2. Viewing Documentation

1. Go to **Policies → Manage Policies**.
2. Click the **Documentation** button (book icon) on a policy row.

<figure><img src="/files/brfwxuMXvkdSWy2ey4VJ" alt=""><figcaption></figcaption></figure>

3. The dialog shows all configured endpoints:

<figure><img src="/files/e93DYi63PjpJziIjB7HO" alt=""><figcaption></figcaption></figure>

<table><thead><tr><th width="187.7109375">Column</th><th>Description</th></tr></thead><tbody><tr><td>Name</td><td>Endpoint name</td></tr><tr><td>Description</td><td>User-provided description</td></tr><tr><td>Method</td><td><code>BOTH</code> (blue), <code>GET</code> (green) or <code>POST</code> (orange)</td></tr><tr><td>URL</td><td>Technical URL to block by tag</td></tr><tr><td>Alias URL</td><td>External DMRV URL</td></tr><tr><td>Query Params</td><td>The endpoint parameters</td></tr><tr><td>Copy</td><td>Copies Alias URL to clipboard</td></tr></tbody></table>

***

### 3. Using the DMRV Proxy

#### 3.1. Endpoint

```
ANY /api/v1/dmrv/:policyId/:alias
```

#### 3.2. How It Works

```
Request: GET /api/v1/dmrv/{policyId}/new-device
            │
            ▼
   1. Load policy by policyId
   2. Find entry: alias="new-device", method="GET"
   3. Resolve: target="new_device"
   4. Forward → getBlockByTagName(user, policyId, "new_device")
   5. Return block response
```

#### 3.3. Method Routing

<table><thead><tr><th width="130.65625">Request Method</th><th width="196.7578125">Internal Call</th><th>Equivalent Standard Endpoint</th></tr></thead><tbody><tr><td><code>GET</code></td><td><code>getBlockByTagName</code></td><td><code>GET /api/v1/policies/:id/tag/:tag</code></td></tr><tr><td><code>POST</code></td><td><code>setBlockDataByTag</code></td><td><code>POST /api/v1/policies/:id/tag/:tag/blocks</code></td></tr></tbody></table>

#### 3.4. Authentication

Standard Bearer token. Required permissions: `POLICIES_POLICY_EXECUTE`, `POLICIES_POLICY_MANAGE`.

#### 3.5. Response Codes

<table><thead><tr><th width="134.70703125">Code</th><th>Meaning</th></tr></thead><tbody><tr><td><code>200</code></td><td>Success</td></tr><tr><td><code>401</code></td><td>Unauthorized</td></tr><tr><td><code>404</code></td><td>Policy not found or alias not configured for this method</td></tr><tr><td><code>503</code></td><td>Block Unavailable (block exists but not accessible in current policy state)</td></tr></tbody></table>

#### 3.6. Example

**Request:**

```http
GET /api/v1/dmrv/69c3dbe9a4d2ac84f75cdfc4/choose-role-alias
Authorization: Bearer <token>
```

**Response:**

```json
{
  "id": "2326c495-eb61-4119-aeab-1a5104176457"
}
```

***

### 4. API Reference

`GET /api/v1/policies/:policyId/about`

Returns the configured documentation entries.

**Response example:**

```json
[
  {
    "name": "reg_form",
    "description": "reg form",
    "target": "registrant_form_grid",
    "method": "GET",
    "alias": "reg",
    "url": "/api/v1/policies/69c3dbe9a4d2ac84f75cdfc4/tag/registrant_form_grid",
    "dmrvUrl": "/api/v1/dmrv/69c3dbe9a4d2ac84f75cdfc4/reg",
    "blockType": "interfaceDocumentsSourceBlock",
    "queryParams": [
      { "name": "page",          "type": "number",   "description": "Page number (0-based)" },
      { "name": "itemsPerPage",  "type": "number",   "description": "Items per page" },
      { "name": "sortField",     "type": "string",   "description": "Field name to sort by" },
      { "name": "sortDirection", "type": "string",   "description": "Sort direction (asc/desc)" },
      { "name": "filterByUUID",  "type": "string",   "description": "Filter by document UUID" },
      { "name": "savepointIds",  "type": "string[]", "description": "Savepoint IDs filter (JSON array)" }
    ]
  }
]
```