Catalog, Compilation, and Preview Operations

Reference the request, response, and failure contracts for this operation family.

Use the configured POLICY_API base and protected POLICY_AUTH_HEADER file from authentication. All paths below are relative to that base. Examples read the bearer header from that file. Keep request payloads and logs free of credentials. Consult your deployed /doc document for complete nested schemas. Response examples illustrate relevant fields rather than every optional property.

These application programming interface (API) operations do not save or approve policies. Catalog reads expose discovered vocabulary. Compilation and preview evaluate supplied intent. Require policy:compile for compilation and policy:preview for native preview. Successful operations return 200. For commands using request.json, prepare the complete compile body before running curl. The worked payload construction shows how to build a bounded compileRequest from current catalog identifiers. For compilation or PIM preview, save that nested object’s contents as request.json, without the outer create-policy fields. Policy Integration Manager (PIM) supplies the native Data target.

Build each compile request from current catalog selections. Use classification identifiers from /catalog, principal id values from /catalog/principals, and resource id values from /catalog/resources. Place principal and resource identifiers in the corresponding enforcement row’s principalIds and resourceIds arrays. Use the exact ID returned by the appropriate current catalog. Do not substitute a display label or an identifier from a different API. Catalog retrieval does not populate a server-side authoring session. Send the complete accumulated input with each compile or preview request.

GET /catalog

Retrieve Policy catalog vocabulary bundle.

Path parameters: None.
Request body: None.
Request parameters: None.

Sample request:

curl --fail-with-body -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  "${POLICY_API}/catalog"

Response: Catalog bundle.

Sample response:

{
  "classifications": ["EMAIL_ADDRESS"],
  "classificationDetails": {
    "EMAIL_ADDRESS": {"label": "Email address"}
  },
  "protectionMethods": ["FPE"]
}

Error codes:

Possible error codes are 401, 403, and 500.

POST /catalog/recommend

Recommend protection methods for supplied items.

Path parameters: None.
Request body: Items with classification and profile toggles.

The table lists item fields, their data types, and requirements or defaults:

Item Field	Type	Requirement or Default
`id`, `classification`	Strings	Supply the caller’s correlation key and exact classification identifier.
`reversible`, `protectAtRest`, `formatPreserving`	Booleans	Default to `true`.
`lowEntropy`, `beyondLatin1`	Booleans	Default to `false`.

Place items in the top-level items array. Omission defaults to an empty array. The response omits items whose classification yields no modeled method. Recommendation does not establish that every method supports your selected target.

Request parameters: None.

Sample request:

curl --fail-with-body -X POST \
  -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  -H "Content-Type: application/json" \
  -d '{"items":[{"id":"customer_email","classification":"EMAIL_ADDRESS"}]}' \
  "${POLICY_API}/catalog/recommend"

Response: Recommended methods per item.

Sample response:

{
  "methods": {
    "customer_email": "FPE"
  }
}

Error codes:

Possible error codes are 400, 401, 403, 422, and 500.

GET /catalog/principals

Retrieve principal catalog for the Who step.

Path parameters: None.
Request body: None.
Request parameters: None.

Sample request:

curl --fail-with-body -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  "${POLICY_API}/catalog/principals"

Response: Principal entries and total count. When identity-source provenance is available, entries include normalized provider values, the source-supplied discovery.principalUuid, and pimSupported. Unsupported Data Protection principals include a pimUnsupportedReason. Unknown source compatibility is left unset rather than inferred.

Use each entry’s exact id for policy selection. name is a display label. Do not infer an ID format or reject a UUID that the catalog returns. Select a PIM-supported principal for Data authoring. An unset pimSupported value does not establish support. Directory membership does not grant Policy command authority.

Sample response:

{
  "total": 1,
  "principals": [
    {
      "id": "user-123",
      "name": "Example reader",
      "type": "User",
      "provider": "IDP",
      "discovery": {
        "principalUuid": "{{PRINCIPAL_UUID}}",
        "sourceId": "{{IDENTITY_SOURCE_ID}}",
        "sourceSystem": "idp_ldap"
      },
      "pimSupported": true,
      "pimUnsupportedReason": null
    }
  ]
}

Error codes:

Possible error codes are 401, 403, and 500.

GET /catalog/resources

Retrieve resource catalog for the Protection step.

Path parameters: None.
Request body: None.
Request parameters: None.

Sample request:

curl --fail-with-body -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  "${POLICY_API}/catalog/resources"

Response: Resource entries and total count.

Use the returned resource id in the compile request. Catalog protection labels describe discovered or derived information, not confirmed target activation. If a required resource is missing, ask the discovery integration owner to check its source. Do not fabricate an identifier to bypass missing discovery evidence.

Sample response:

{
  "total": 1,
  "resources": [
    {"id":"schema.table.column","name":"Example column","type":"Column"}
  ]
}

Error codes:

Possible error codes are 401, 403, and 500.

GET /catalog/actions

Retrieve action catalog for permissions matrix. This catalog differs from the native and abstract authoring action vocabularies. Use /schema/authoring-actions for abstract compile actions and /schema/actions for native schema actions.

Path parameters: None.
Request body: None.
Request parameters: None.

Sample request:

curl --fail-with-body -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  "${POLICY_API}/catalog/actions"

Response: Action vocabulary.

Sample response:

{
  "actions": [
    {
      "id": "ca-1",
      "name": "read",
      "category": "data-access",
      "applicableLayers": [1, 2, 3, 4, 5],
      "description": "Read/select rows from a table or column"
    }
  ]
}

Error codes:

Possible error codes are 401, 403, and 500.

POST /policies/compile

Compile a policy and return its validation report and emitted entities.

Path parameters: None.
Request body: Compile request payload. The optional trustedApplications array contains application gates for PIM datastores, separate from user and group permission principals. Each entry has an applicationName and one or more applicationUsers. Refer to deployed OpenAPI document for field constraints.
Request parameters: None.

The public compile body accepts these top-level fields:

Field	Type	Default or Meaning
`classificationsInScope`, `frameworks`	Arrays of strings	Default to empty arrays.
`sensitivityOverrides`, `protectionOverrides`	Objects mapping strings to strings	Default to empty objects.
`sensitivityApproved`	Array of strings	Default to an empty array.
`configOverrides`	Object	Default to empty. Map resource identifiers to typed protection configuration.
`identity`	Boolean	Default to `true`.
`policyName`, `policyUuid`	Nullable strings	Optionally identify compilation context. Saving uses server-owned identity.
`enforcement`	Array of objects	Default to empty. Supply enforcement point, principal/action scope, and resource identifiers.
`protectionIntents`	Array of objects	Default to empty. Supply classification and method-selection signals.
`trustedApplications`	Array of objects	Default to empty. Supply application names and application-user arrays.
`federated_guardrails`	Nullable object	Supply native Federated Guardrails rules or permission matrix.

Use the deployed schema for typed configOverrides and native rule definitions. An empty request can span broad discovery inputs. Prefer explicit bounded scope. Compilation returns findings without creating a draft or changing protection. Inspect the returned report, not only the 200 status. Neither compiled entities nor a successful preview establish submission eligibility or target protection.

Sample request:

curl --fail-with-body -X POST \
  -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  -H "Content-Type: application/json" \
  --data-binary @request.json \
  "${POLICY_API}/policies/compile"

Response: Final compile report plus Cedar and PIM entities.

Sample response:

{
  "report": {},
  "cedarEntities": [],
  "pimEntities": []
}

Error codes:

Possible error codes are 400, 401, 403, 422, and 500.

POST /policies/preview

Preview a policy’s native lowering without applying changes.

Path parameters: None.
Request body: Product-specific preview payload. Use product=PIM for a bare compile request. Use product=FEDX for a Federated Guardrails object with required compile and optional guardrail_rules, dataprotection_rules, content_action_rules, or federated_matrix.
Request parameters: product is required and accepts PIM or FEDX. The optional boolean reuse_existing defaults to true for PIM inventory reuse. Inventory reuse concerns native resource planning. It is not a replay or idempotency guarantee.

Sample request:

curl --fail-with-body -X POST \
  -H "@${POLICY_AUTH_HEADER:?Complete authentication setup}" \
  -H "Content-Type: application/json" \
  --data-binary @request.json \
  "${POLICY_API}/policies/preview?product=PIM&reuse_existing=true"

Response: Product-specific native plan object. For product=PIM, datastore_scopes can contain an individual registration scope or a shared protector-group scope. Group scopes retain each source registration, its approved IPv4 ranges, and source columns, alongside the group’s canonical range union. The plan can also include source-sensitive authorization evidence used to check that sharing a native datastore does not widen permissions.

Sample response:

{
  "plan": {
    "operations": [],
    "datastore_scopes": {
      "{{DATASTORE_GROUP_REF}}": {
        "schema_version": 2,
        "group_id": "{{PROTECTOR_GROUP_ID}}",
        "ranges": [["192.0.2.10", "192.0.2.10"]],
        "sources": [{
          "registration_id": "{{SOURCE_REGISTRATION_ID}}",
          "ranges": [["192.0.2.10", "192.0.2.10"]],
          "source_columns": ["{{SOURCE_COLUMN_ID}}"]
        }]
      }
    },
    "authorization": {
      "schema_version": 1,
      "policy_id": "${POLICY_ID}",
      "resources": [],
      "native_grants": []
    }
  }
}

Error codes:

Possible error codes are 400, 401, 403, 422, and 500.

Last modified : November 03, 2026

Feedback

Was this page helpful?