API Reference | PCIOasis Docs

Authentication

Pass an API key as a Bearer token in the Authorization header with every request.

Authorization: Bearer YOUR_API_KEY

Generate API keys in your dashboard under Settings > API Keys. Keys are scoped to specific environments or to your entire account. Rotate keys at any time without service interruption.

Base URL

https://api.pcioasishq.com

Response format

All responses return JSON. HTTP status codes follow standard conventions: 200 for success, 4xx for client errors, 5xx for server errors. Error responses include a message field with details.

GET /v1/environments

Lists every CDE environment connected to your account.

GET /v1/environments

Query parameters

Parameter	Type	Description
`status`	string	Filter by status. Values: `active`, `paused`, `error`. Optional.
`page`	integer	Page number for pagination. Defaults to 1.
`per_page`	integer	Results per page. Max 100. Defaults to 25.

Example request

curl https://api.pcioasishq.com/v1/environments \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "data": [
    {
      "id": "env_8yTkmp2Q",
      "name": "Production CDE",
      "type": "cloud",
      "status": "active",
      "posture_score": 87,
      "last_scan_at": "2026-08-20T14:12:00Z",
      "created_at": "2026-05-03T09:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 25,
    "total": 1
  }
}

GET /v1/scans/{scan_id}

Returns a specific scan's status and summary results.

GET /v1/scans/{scan_id}

Path parameters

Parameter	Type	Description
`scan_id`	string	The scan identifier returned when a scan is triggered.

Example request

curl https://api.pcioasishq.com/v1/scans/scan_9nRqwZ3 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response

{
  "id": "scan_9nRqwZ3",
  "environment_id": "env_8yTkmp2Q",
  "status": "completed",
  "started_at": "2026-08-20T14:10:00Z",
  "completed_at": "2026-08-20T14:12:00Z",
  "posture_score": 87,
  "findings": {
    "total": 14,
    "critical": 1,
    "high": 3,
    "medium": 7,
    "low": 3
  },
  "controls_tested": 118,
  "controls_passed": 104
}

Scan status values: queued, running, completed, failed. Poll until status is completed or failed.

GET /v1/scans/{scan_id}/evidence

Returns the evidence package for a completed scan. It is grouped by PCI DSS requirement family and available as a ZIP download or structured JSON.

GET /v1/scans/{scan_id}/evidence

Query parameters

Parameter	Type	Description
`format`	string	Response format. Values: `json` (default), `zip`. Zip returns a downloadable archive.
`requirement`	string	Filter to a specific requirement family. Example: `req_1`, `req_8`. Optional.

Example request

# Download full evidence package as ZIP
curl https://api.pcioasishq.com/v1/scans/scan_9nRqwZ3/evidence?format=zip \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o evidence-2026-08-20.zip

JSON response structure

{
  "scan_id": "scan_9nRqwZ3",
  "generated_at": "2026-08-20T14:13:00Z",
  "requirements": {
    "req_1": {
      "label": "Install and Maintain Network Security Controls",
      "controls": [
        {
          "id": "1.2.1",
          "description": "Configuration standards for NSC rulesets",
          "result": "pass",
          "evidence_items": [...]
        }
      ]
    }
  }
}

POST /v1/webhooks

Registers a webhook endpoint for real-time notifications when scans complete, new findings appear, or posture scores change. Available on Professional and Enterprise plans.

POST /v1/webhooks

Request body

{
  "url": "https://yourapp.example.com/hooks/pcioas",
  "events": ["scan.completed", "finding.new_critical"],
  "environment_ids": ["env_8yTkmp2Q"],
  "secret": "YOUR_SIGNING_SECRET"
}

Event types

Event	Description
`scan.completed`	Fired when a scan finishes (success or failure).
`scan.failed`	Fired when a scan fails to complete due to an agent or connectivity issue.
`finding.new_critical`	Fired when a new critical-severity finding is detected.
`finding.new_high`	Fired when a new high-severity finding is detected.
`posture.score_dropped`	Fired when the posture score drops by 5 or more points since the previous scan.

Webhook signature verification

PCIOasis signs each webhook payload with HMAC-SHA256 using your signing secret. Verify the X-PCIOasis-Signature header to confirm authenticity.

import hmac, hashlib

def verify_signature(payload_bytes, secret, signature_header):
    expected = hmac.new(
        secret.encode(), payload_bytes, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header)

Enterprise webhooks: Enterprise plans support additional event types, custom retry policies, and delivery to private network endpoints via VPN or IP allowlisting. Contact us to discuss your requirements.

Rate limits

The API is rate-limited per API key:

Starter: 60 requests per minute
Professional: 300 requests per minute
Enterprise: custom (contact us)

When a rate limit is exceeded, the API returns HTTP 429 with a Retry-After header indicating when you can retry.