> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shieldhq.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Policy

> Retrieve policy and content metadata

# Get Policy

Retrieve policy information and associated IPFS CID for accessing content.

## Endpoint

```http theme={null}
GET /api/getPolicy/{policyId}
Authorization: Bearer {token}
```

## Parameters

| Parameter  | Type   | Required | Description                    |
| ---------- | ------ | -------- | ------------------------------ |
| `policyId` | string | ✅        | Policy identifier (path param) |

## Response

### Success (200)

```json theme={null}
{
  "success": true,
  "policy": {
    "policyId": "0xabc123...",
    "cid": "QmXyz...",
    "sender": "0x742d...",
    "recipient": "0x1234...",
    "expiry": 1708608000,
    "maxAttempts": 3,
    "attempts": 1,
    "contentType": "file",
    "fileName": "document.pdf",
    "fileSize": 1048576,
    "valid": true,
    "createdAt": "2025-02-22T10:00:00Z"
  }
}
```

### Policy Expired (410)

```json theme={null}
{
  "error": "Policy expired",
  "expiry": 1708608000
}
```

### Policy Not Found (404)

```json theme={null}
{
  "error": "Policy not found"
}
```

### Unauthorized (401)

```json theme={null}
{
  "error": "Unauthorized"
}
```

### Max Attempts Reached (403)

```json theme={null}
{
  "error": "Max attempts reached",
  "attempts": 3,
  "maxAttempts": 3
}
```

## Example Usage

### JavaScript

```typescript theme={null}
async function getPolicy(policyId: string) {
  const response = await fetch(`/api/getPolicy/${policyId}`, {
    headers: {
      'Authorization': `Bearer ${token}`,
    },
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error);
  }

  return await response.json();
}

// Usage
const { policy } = await getPolicy('0xabc123...');
console.log(`CID: ${policy.cid}`);
console.log(`Expires: ${new Date(policy.expiry * 1000)}`);
```

### cURL

```bash theme={null}
curl https://app.shieldhq.xyz/api/getPolicy/0xabc123... \
  -H "Authorization: Bearer $TOKEN"
```

## Policy Status Checks

The endpoint performs multiple validations:

| Check            | HTTP Status | Response                            |
| ---------------- | ----------- | ----------------------------------- |
| Policy exists    | 200         | Full policy data                    |
| Policy not found | 404         | `{ error: "Policy not found" }`     |
| Expired          | 410         | `{ error: "Policy expired" }`       |
| Revoked          | 403         | `{ error: "Policy revoked" }`       |
| Max attempts     | 403         | `{ error: "Max attempts reached" }` |

## Access Flow Integration

```typescript theme={null}
async function accessContent(policyId: string, secretKey: string) {
  // 1. Get policy metadata
  const { policy } = await getPolicy(policyId);

  // 2. Authenticate with SIWE (recipient)
  const token = await authenticate(recipientAddress);

  // 3. Log access on-chain
  await logAccessAttempt(policyId);

  // 4. Fetch encrypted content from IPFS
  const encrypted = await fetchFromIPFS(policy.cid);

  // 5. Decrypt with secret key
  const decrypted = await decryptContent(encrypted, secretKey);

  return decrypted;
}
```

## Response Fields

| Field         | Type    | Description                   |
| ------------- | ------- | ----------------------------- |
| `policyId`    | string  | Policy identifier             |
| `cid`         | string  | IPFS Content Identifier       |
| `sender`      | address | Creator's wallet address      |
| `recipient`   | address | Authorized recipient address  |
| `expiry`      | number  | Unix timestamp                |
| `maxAttempts` | number  | Maximum allowed attempts      |
| `attempts`    | number  | Current attempt count         |
| `contentType` | string  | `"file"` or `"message"`       |
| `fileName`    | string  | Original filename             |
| `fileSize`    | number  | Size in bytes                 |
| `valid`       | boolean | Whether policy is still valid |
| `createdAt`   | string  | ISO timestamp of creation     |

## Rate Limits

| Limit      | Value         |
| ---------- | ------------- |
| Requests   | 60 per minute |
| Per policy | No limit      |

## Caching

Policies are cached for 30 seconds to reduce database load. The cache is invalidated on:

* Policy revocation
* Access attempt logged

## Error Handling

```typescript theme={null}
try {
  const { policy } = await getPolicy(policyId);
} catch (error) {
  switch (error.message) {
    case 'Policy not found':
      // Invalid policy ID
      break;
    case 'Policy expired':
      // Link has expired
      break;
    case 'Max attempts reached':
      // No more access allowed
      break;
    case 'Policy revoked':
      // Sender revoked access
      break;
    default:
      // Network or server error
  }
}
```