Documentation

PolicyCortex GraphQL API: Query Policies, Compliance & Governance

Powerful, flexible GraphQL interface for querying policies, compliance data, and governance analytics with precise data fetching and real-time subscriptions.

PolicyCortex GraphQL API Documentation & Getting Started

Quick Start

GraphQL Endpoint

Access the PolicyCortex GraphQL API at a single endpoint with full introspection support.

https://api.policycortex.com/graphql
GraphQL Query Examplegraphql
query GetPolicies($framework: String, $severity: Severity, $limit: Int) {
  policies(framework: $framework, severity: $severity, limit: $limit) {
    edges {
      node {
        id
        name
        description
        framework
        severity
        resourceTypes
        violationCount
        createdAt
        updatedAt
      }
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
    totalCount
  }
}

Authentication

API Key Authentication

Include your API key in the Authorization header for all GraphQL requests.

cURL with GraphQL Querybash
curl -X POST https://api.policycortex.com/graphql \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "query { policies { edges { node { id name } } } }"
  }'

Schema Overview

📋 Core Types

Primary data structures and entities

• Policy
• Violation
• Resource
• ComplianceReport

🔍 Query Operations

Read operations for data retrieval

• policies
• violations
• resources
• complianceReports

✏️ Mutations

Write operations for data modification

• createPolicy
• updateViolation
• exemptResource
• triggerScan

🔄 Subscriptions

Real-time data streaming

• violationCreated
• policyUpdated
• scanCompleted
• complianceChanged

Query Examples

Policy Violations Query

Get Violations with Resource Detailsgraphql
query GetViolations($severity: [Severity!], $status: ViolationStatus) {
  violations(severity: $severity, status: $status, orderBy: DETECTED_AT_DESC) {
    edges {
      node {
        id
        policy {
          id
          name
          description
          framework
        }
        resource {
          id
          type
          name
          region
          accountId
          tags {
            key
            value
          }
        }
        severity
        status
        message
        detectedAt
        resolvedAt
        exemption {
          reason
          expiresAt
          createdBy
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Compliance Dashboard Query

Compliance Score and Trend Datagraphql
query ComplianceDashboard($framework: String!, $timeRange: TimeRange!) {
  complianceReport(framework: $framework) {
    id
    framework
    overallScore
    status
    generatedAt

    controls {
      id
      name
      status
      score
      failedChecks
      totalChecks
      description
    }

    trends(timeRange: $timeRange) {
      date
      score
      violationCount
    }

    topViolations(limit: 10) {
      policy {
        name
        severity
      }
      count
      resources {
        type
        count
      }
    }
  }
}

Resource Discovery Query

List Resources with Filtersgraphql
query GetResources($type: String, $provider: CloudProvider) {
  resources(type: $type, provider: $provider, limit: 50) {
    edges {
      node {
        id
        name
        type
        provider
        region
        accountId
        createdAt
        violations {
          id
          severity
          status
        }
        tags {
          key
          value
        }
      }
    }
    totalCount
  }
}

Mutations

Create Policy

Create New Policy Mutationgraphql
mutation CreatePolicy($input: CreatePolicyInput!) {
  createPolicy(input: $input) {
    policy {
      id
      name
      description
      resourceTypes
      framework
      severity
      rules {
        condition
        message
      }
    }
    errors {
      field
      message
    }
  }
}

# Variables
{
  "input": {
    "name": "require-s3-encryption",
    "description": "S3 buckets must have encryption enabled",
    "resourceTypes": ["AWS::S3::Bucket"],
    "framework": "SOC2",
    "severity": "HIGH",
    "rules": [
      {
        "condition": "resource.encryption == null",
        "message": "S3 bucket must have server-side encryption enabled"
      }
    ]
  }
}

Update Violation Status

Resolve Violation Mutationgraphql
mutation ResolveViolation($violationId: ID!, $resolution: String!) {
  updateViolation(
    id: $violationId,
    input: {
      status: RESOLVED,
      resolutionNote: $resolution
    }
  ) {
    violation {
      id
      status
      resolvedAt
      resolutionNote
    }
    errors {
      field
      message
    }
  }
}

Trigger Scan

Trigger Compliance Scan Mutationgraphql
mutation TriggerScan($input: TriggerScanInput!) {
  triggerScan(input: $input) {
    scan {
      id
      name
      status
      estimatedDuration
      createdAt
    }
    errors {
      field
      message
    }
  }
}

# Variables
{
  "input": {
    "name": "Production Security Scan",
    "scanType": "FULL",
    "environment": "production",
    "cloudProviders": ["AWS", "AZURE"]
  }
}

Real-time Subscriptions

WebSocket Subscriptions

Subscribe to real-time events using GraphQL subscriptions over WebSocket.

Subscribe to New Violationsgraphql
subscription ViolationAlerts($severity: [Severity!]) {
  violationCreated(severity: $severity) {
    violation {
      id
      policy {
        name
        framework
      }
      resource {
        name
        type
        accountId
      }
      severity
      message
      detectedAt
    }
  }
}

JavaScript Client Example

WebSocket Subscription Clientjavascript
const client = new ApolloClient({
  uri: 'https://api.policycortex.com/graphql',
  wsUri: 'wss://api.policycortex.com/graphql',
  connectionParams: {
    authorization: `Bearer ${apiKey}`
  }
});

const subscription = client.subscribe({
  query: VIOLATION_ALERTS_SUBSCRIPTION,
  variables: { severity: ['HIGH', 'CRITICAL'] }
}).subscribe({
  next: ({ data }) => {
    console.log('New violation:', data.violationCreated.violation);
  },
  error: (err) => console.error(err)
});

Pagination & Filtering

Cursor-based Pagination

Paginated Query Examplegraphql
query GetPolicies($after: String, $first: Int = 20) {
  policies(after: $after, first: $first) {
    edges {
      cursor
      node {
        id
        name
        severity
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
    totalCount
  }
}

Filter Options

  • • Severity levels (LOW, MEDIUM, HIGH, CRITICAL)
  • • Status filters (OPEN, RESOLVED, EXEMPTED)
  • • Framework types (SOC2, HIPAA, ISO27001)
  • • Cloud providers (AWS, AZURE, GCP)
  • • Date ranges and time windows

Sorting Options

  • • CREATED_AT_ASC / CREATED_AT_DESC
  • • UPDATED_AT_ASC / UPDATED_AT_DESC
  • • DETECTED_AT_ASC / DETECTED_AT_DESC
  • • SEVERITY_ASC / SEVERITY_DESC
  • • NAME_ASC / NAME_DESC

Error Handling

GraphQL Error Response

Error Response Formatjson
{
  "errors": [
    {
      "message": "Policy with name 'require-s3-encryption' already exists",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["createPolicy"],
      "extensions": {
        "code": "RESOURCE_ALREADY_EXISTS",
        "field": "name",
        "timestamp": "2024-01-21T16:00:00Z"
      }
    }
  ],
  "data": {
    "createPolicy": null
  }
}

Best Practices

Query Optimization

  • • Request only needed fields
  • • Use fragments for reusable selections
  • • Implement proper pagination
  • • Batch queries when possible
  • • Cache responses appropriately

Security

  • • Never expose API keys in client code
  • • Implement proper error handling
  • • Use HTTPS for all connections
  • • Validate user input before queries
  • • Monitor query complexity