# Permissions HTTP API

Inputs, results, permissions and errors for the permissions endpoints.

Use the server URL of your own deployment. Worker examples require a currently valid bearer token; provider callbacks use native signatures. `REPLACE_WITH_RETURNED_ID` values refer to IDs obtained through setup or prior operations. [Headless setup](https://beepgrid.com/docs/start/headless.md) supplies the credentials and entities.

<a id="post-api-v1-contact-permissions-preview"></a>

## Preview current contact permissions or a proposed versioned edit without saving

`POST /api/v1/contact-permissions/preview`

Preview current contact permissions or a proposed versioned edit without saving. Explicit blocks override matching role grants.

**Authorization:** The subject, an authorized access inspector or the administrator. Proposed edits require current management and assignment authority.


### Input

Content-Type: `application/json`.

| Field | Type | Usage |
| --- | --- | --- |
| `subject` (required) | [Target](https://beepgrid.com/docs/reference/models/#target) | Authorized subject projection of the access inspection. |
| `rules` | array of [Rule](https://beepgrid.com/docs/reference/models/#rule) | Directional permission rules granted by this policy role. |
| `version` | `integer` | Current optimistic-concurrency version. Read the object before a guarded change; a stale version conflicts. |
| `targets` | array of [Target](https://beepgrid.com/docs/reference/models/#target) | Explicit targets for a private batch or shared chat. These have different audience semantics. maxItems=100. |

### Result and recovery

The current direct policy, effective action cells and sources for up to 100 contacts, warnings and save eligibility.

Reload on version conflict. Visibility and assignment authority remain separate. A preview is never a grant.

Response media type: `application/json`. `object`. See the operation-specific result contract.


### HTTP usage

Fill the shown IDs and operation fields for your own test workspace. Keep the same saved operation key for a retry.

```sh
curl --fail-with-body --silent --show-error -X POST "$BEEPGRID_URL/api/v1/contact-permissions/preview" \
  -H "Authorization: Bearer $BEEPGRID_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"subject":{"kind":"person","id":"REPLACE_WITH_RETURNED_ID"}}'
```