> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plainid.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Create a Policy Report
> This API call begins the report generation process. Use the reportId returned in the response in the Get Request to generate a link to the report PDF.
## OpenAPI
````json POST /api/1.0/reports/{envId}/{reportType}
{
"openapi": "3.0.3",
"info": {
"title": "Management APIs",
"version": "1.0.0",
"contact": {
"name": "PlainID",
"url": "https://plainid.com",
"email": "contact@plainid.com"
},
"license": {
"name": "Commercial",
"url": "https://plainid.com/license"
},
"termsOfService": "https://www.plainid.com/terms/",
"description": "
The PlainID Authorization Platform provides Management capabilities through the APIs below.
To access the Management APIs, make sure to enter your dedicated domain according to your PlainID Tenant Location:
Region
Base URL
United States (US)
https://api.us1.plainid.io
Canada (CA)
https://api.ca1.plainid.io
Europe (EU)
https://api.eu1.plainid.io
Local PAA
https://api.plainid.local
"
},
"servers": [
{
"description": "United States",
"url": "https://api.us1.plainid.io"
},
{
"description": "Europe",
"url": "https://api.eu1.plainid.io"
},
{
"description": "Canada",
"url": "https://api.ca1.plainid.io"
},
{
"description": "Local PAA",
"url": "https://api.plainid.local"
}
],
"tags": [
{
"name": "access-file-authorizer-oas",
"description": "access-file-authorizer-oas"
},
{
"name": "authz-packager-oas",
"description": "authz-packager-oas"
},
{
"name": "SQL Database Authorizer",
"description": "API for modifying SQL queries based on authorization policies"
},
{
"name": "delegated-admin-oas",
"description": "delegated-admin-oas"
},
{
"name": "Discovery",
"description": "Discovery APIs"
},
{
"name": "Enrichment",
"description": "Enrichment APIs"
},
{
"name": "env-mgmt-oas",
"description": "env-mgmt-oas"
},
{
"name": "hybrid-commander-oas",
"description": "hybrid-commander-oas"
},
{
"name": "auth-keys",
"description": "Auth key operations"
},
{
"name": "components",
"description": "Component operations"
},
{
"name": "paas",
"description": "PAA operations"
},
{
"name": "paa-groups",
"description": "PAA group operations"
},
{
"name": "packages",
"description": "Package configuration operations"
},
{
"name": "secret-stores",
"description": "Secret store operations"
},
{
"name": "Table Mapping",
"description": "Table Mapping"
},
{
"name": "Column Mapping",
"description": "Column Mapping"
},
{
"name": "Api Mapping",
"description": "Api Mapping"
},
{
"name": "notifier-oas",
"description": "notifier-oas"
},
{
"name": "shadow-tracker",
"description": "Shadow tracker SSE stream"
},
{
"name": "orchestrator-oas",
"description": "orchestrator-oas"
},
{
"name": "POP",
"description": "pop operations"
},
{
"name": "org-mgmt-oas",
"description": "org-mgmt-oas"
},
{
"name": "pip-mgmt-oas",
"description": "pip-mgmt-oas"
},
{
"name": "monitor-loggers",
"description": "monitor-loggers"
},
{
"name": "Policy Management APIs",
"description": "Policy Management APIs"
},
{
"name": "Policy Management APIs 1.0",
"description": "Policy Management APIs 1.0"
},
{
"name": "Policy Management APIs 2.0",
"description": "Policy Management APIs 2.0"
},
{
"name": "Policy Building Blocks Management APIs 2.0",
"description": "Policy Building Blocks Management APIs 2.0"
},
{
"name": "Audit",
"description": "Audit"
},
{
"name": "Asset Template",
"description": "Asset Template"
},
{
"name": "Application",
"description": "Application"
},
{
"name": "Api Mapper",
"description": "Api Mapper"
},
{
"name": "Identity Template",
"description": "Identity Template"
},
{
"name": "Identity Sources",
"description": "Identity Sources"
},
{
"name": "Mapper Sets",
"description": "Mapper Sets"
},
{
"name": "Identity Template V2",
"description": "Identity Template V2"
},
{
"name": "PAA Sources",
"description": "PAA Sources"
},
{
"name": "PAA Views",
"description": "PAA Views"
},
{
"name": "PAA Groups",
"description": "PAA Groups"
},
{
"name": "Scope",
"description": "Managed Scope APIs"
},
{
"name": "Authentication for Management APIs",
"description": "Authentication for Management APIs"
},
{
"name": "runtime",
"description": "runtime"
},
{
"name": "Cache Management",
"description": "Cache invalidation operations for Runtime service"
}
],
"externalDocs": {
"url": "https://docs.plainid.io/apidocs/policy-management-apis"
},
"paths": {
"/api/1.0/reports/{envId}/{reportType}": {
"post": {
"tags": [
"env-mgmt-oas"
],
"summary": "Create a Policy Report",
"security": [
{
"bearerAuth": []
}
],
"description": "This API call begins the report generation process. Use the reportId returned in the response in the Get Request to generate a link to the report PDF.",
"operationId": "createPlatformReport",
"parameters": [
{
"name": "envId",
"in": "path",
"description": "The Environment ID can be found under the Details Tab in the Environment Settings. If your PAA is installed on the Tenant level, input - as your envId.",
"required": "true",
"schema": {
"type": "string",
"format": "uuid"
}
},
{
"name": "reportType",
"in": "path",
"description": "Identifies which report to generate.",
"required": "true",
"schema": {
"type": "string",
"enum": [
"policy_by_attribute"
]
}
}
],
"requestBody": {
"required": "true",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/createPlatformReportRequest"
},
"examples": {
"Policies by multiple attributes (all filters)": {
"summary": "Policies grouped by regulatoryTags and Policy-Workflow (two Applications)",
"value": {
"attributes": [
{
"attributeId": "regulatoryTags"
},
{
"attributeId": "Policy-Workflow"
}
],
"filters": {
"applicationIds": [
"HR-Application",
"internal-platform"
],
"state": "Active",
"completed": "true",
"accessType": "Allow"
}
}
}
}
}
}
},
"responses": {
"202": {
"description": "Report job accepted",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"description": "Report job details returned when the request is accepted.",
"properties": {
"reportId": {
"type": "string",
"format": "uuid",
"description": "Unique identifier for the report job. Use in GET /reports/{envId}/{reportId} to poll for status."
},
"reportName": {
"type": "string",
"description": "Auto-generated report file name, derived from the report type, environment ID, and creation timestamp."
},
"reportType": {
"type": "string",
"description": "The type of report that was requested (e.g. policies_by_attribute)."
},
"status": {
"type": "string",
"enum": [
"processing",
"ready",
"failed"
],
"description": "Current generation status. On creation this is always \"processing\". Poll GET until \"ready\"."
},
"dateTime": {
"type": "string",
"description": "Date and time the report job was created (UTC, format \"YYYY-MM-DD HH:mm\")."
},
"anchor": {
"type": "object",
"description": "Context anchor for the report, identifying the environment it belongs to.",
"properties": {
"envId": {
"type": "string",
"format": "uuid",
"description": "The environment ID the report was generated for."
}
}
}
}
}
}
},
"examples": {
"Accepted (status=processing)": {
"summary": "Job accepted; poll GET /api/1.0/reports/{envId}/{reportId} until status is \"ready\"",
"value": {
"data": {
"reportId": "c3100ddd-e77d-4bb3-8704-d03e01f36443",
"reportName": "policies_by_attribute_7c04f99f-ddf4-4425-97c0-8fd9d2f9ea38_2026-05-11_13-15",
"reportType": "policies_by_attribute",
"status": "processing",
"dateTime": "2026-05-11 13:15",
"anchor": {
"envId": "7c04f99f-ddf4-4425-97c0-8fd9d2f9ea38"
}
}
}
}
}
}
}
},
"400": {
"description": "Validation error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emptyError"
},
"examples": {
"Invalid attribute id": {
"summary": "attributeId is not present in the environment's policy custom schema",
"value": {
"id": "EW70XA",
"status": "400",
"name": "badRequestError",
"message": "regulatoryTags is not a valid attribute for env 7c04f99f-ddf4-4425-97c0-8fd9d2f9ea38"
}
},
"Attribute not groupable": {
"summary": "attributeId exists but is not a value-list (enum) attribute",
"value": {
"id": "EW71XA",
"status": "400",
"name": "badRequestError",
"message": "Attribute 'policyOwner' is not supported for this report type."
}
},
"Unknown applicationIds": {
"summary": "one or more applicationIds values are not known external Application IDs in this env",
"value": {
"id": "EW79XA",
"status": "400",
"name": "badRequestError",
"message": "unknown applicationIds: ghost-app"
}
}
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emptyError"
},
"examples": {
"Feature disabled for tenant": {
"summary": "platform.reports.use feature toggle is off for this tenant",
"value": {
"id": "EW72XA",
"code": "C-011",
"status": "403",
"name": "featureNotAllowedError",
"message": "Platform reports are not enabled for this tenant"
}
},
"Insufficient permissions on environment": {
"summary": "The current user lacks insert permission on the target environment",
"value": {
"id": "EW73XA",
"status": "403",
"name": "forbiddenEnvironment",
"message": "operation insert for resource Environment 7c04f99f-ddf4-4425-97c0-8fd9d2f9ea38 isn't allowed due to: the current user has no appropriate permissions"
}
}
}
}
}
},
"404": {
"description": "Environment not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emptyError"
},
"examples": {
"Environment not found": {
"summary": "envId path parameter does not exist for the current tenant",
"value": {
"code": "EVM-002",
"id": "EW74XA",
"status": "404",
"name": "environmentNotFoundError",
"message": "environment id: 7c04f99f-ddf4-4425-97c0-8fd9d2f9ea38 doesn't exist"
}
}
}
}
}
},
"422": {
"description": "Unsupported report type",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/emptyError"
},
"examples": {
"Unsupported report type": {
"summary": "reportType path segment is not a known report type",
"value": {
"id": "EW75XA",
"status": "422",
"name": "unprocessableEntityError",
"message": "unsupported report type: policies_by_unknown_attribute"
}
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"createPlatformReportRequest": {
"type": "object",
"required": [
"attributes"
],
"properties": {
"attributes": {
"type": "array",
"description": "One or more policy attributes to group report results by. Each entry must reference an attribute ID that exists in the environment's policy custom schema and is a value-list (enum) type. At least one attribute is required.",
"minItems": "1",
"items": {
"type": "object",
"required": [
"attributeId"
],
"properties": {
"attributeId": {
"type": "string",
"description": "The Attribute ID. This can be found in Identity Settings."
},
"values": {
"type": "array",
"description": "Optional list of specific values to filter by for this attribute. When provided, only policies whose attribute value matches one of these entries are included. If omitted, all values for this attribute are included.",
"items": {
"type": "string"
}
}
}
}
},
"filters": {
"type": "object",
"description": "Optional filters to narrow the set of policies included in the report. All filter fields are optional; omitting a field includes policies regardless of that field's value. All filter conditions are combined with AND logic.",
"properties": {
"applicationIds": {
"type": "array",
"description": "Application ID(s) as shown in the Application section of the Platform. Note: This input is case-sensitive.",
"items": {
"type": "string"
}
},
"state": {
"type": "string",
"description": "Specifies whether the Policy is Active or Inactive.",
"enum": [
"Active",
"Inactive"
]
},
"accessType": {
"type": "string",
"description": "Specifies whether the Policy is set to allow or deny.",
"enum": [
"Allow",
"Restrict"
],
"example": "Allow"
},
"completed": {
"description": "Specifies whether the Policy is complete or incomplete.",
"type": "boolean"
}
}
}
}
},
"emptyError": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"id": {
"type": "string"
},
"status": {
"type": "integer"
},
"name": {
"type": "string"
},
"message": {
"type": "string"
},
"args": {
"type": "object",
"properties": {
"path": {
"type": "string"
}
}
}
}
}
},
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": " For more details about Administration API Authentication, check out the Authentication APIs documentation Provide your bearer token in the Authorization header when making requests to protected resources. Example: `Authorization: Bearer 123`"
}
}
}
}
````