Compliance API

Compliance records, every day, the state of the API controls ApiTraffic can see, and maps them to the controls of the frameworks you are audited against. See Compliance for how it works in the app, and Compliance platforms for pushing evidence to Drata or Sprinto.

Availability: on for every account. While it is switched off for an account, every route here answers 404 with COMPLIANCE_NOT_ENABLED. Plan: the view needs Compliance (complianceView), packs need Evidence packs (complianceEvidencePacks) too, and the compliance platform routes need Compliance platform push (complianceGrcPush). Permissions: any member, or an API token, reads the evidence and asks for and downloads packs. Changing the settings, and connecting, mapping (with listing the platform’s controls) and pushing packs to compliance platforms, are for owners and admins, signed in: an API token cannot. A token with access scopes needs security:read to read and security:write to ask for a pack.

Scope: evidence is kept for the whole account and for each environment, never per bucket. The routes that read evidence take environmentSid; without it, a signed-in member reads the whole account. An API token belongs to one environment: without environmentSid, or with its own, it reads that environment, and asking for another environment is refused. Listing packs and asking for one also refuse it the account-wide packs (an empty environmentSid). A credential tied to no environment reads them all, and one limited to some buckets is refused.

Control states #

A control’s state on a day comes from its evidence checks, or its supporting checks when it has none:

Counts are counts of controls, never a percentage.

Frameworks #

GET https://api.apitraffic.io/v1/accounts/{accountSid}/compliance/frameworks

The frameworks in the compliance library: frameworks, each with id (soc2, pci-dss, hecvat), name, version, kind (controls, or questionnaire for HECVAT), enabled (on for the account) and items (its controls or questions).

Overview #

GET https://api.apitraffic.io/v1/accounts/{accountSid}/compliance/overview

Each framework that is on, with items (how many controls it has) and counts of controls in each state on asOf (the last day of the period with evidence), and the period’s exceptions. Also period, libraryVersion (the compliance library in use), snapshotLibraryVersions (those the period’s evidence was recorded with), notes (why a check’s state changed when the library changed) and cannotSee: what ApiTraffic cannot see for you.

Query parameters #

• environmentSid (query, string): One environment’s evidence. Omit for the whole account (an API token reads its own environment; see Scope above).

• from (query, string): First day of the period (YYYY-MM-DD, UTC). Default: the saved audit period, or the last 12 months.

• to (query, string): Last day of the period. Default: yesterday, or today once the checks have been run today.

Run the checks now #

POST https://api.apitraffic.io/v1/accounts/{accountSid}/compliance/run

Asks for the checks to run now, for every environment and the whole account, instead of waiting for the daily run. Within a minute or two, today is recorded as it stands. The next daily run records the same day again, in full. Asking while a run is waiting or under way, or within a minute of the last one finishing, returns that run. Owners and admins, or an administrator API token; a credential limited to some buckets is refused.

• status (string, required): requested (waiting for the processor), running, done or failed (with error; ask again).

• requestedBy (string | null, required): The person who asked, or null when the first visit to an account with no evidence asked.

• day (string | null, required): The UTC day the run recorded, once it is done.

The overview returns the latest run as run. The first time it is read for an account with no evidence, it asks for one.

Exceptions #

GET https://api.apitraffic.io/v1/accounts/{accountSid}/compliance/exceptions

Takes the same query parameters as the overview. Returns period and exceptions: every check in attention on any day of the period.

• checkId (string, required): The check.

• title (string, required): Its title.

• attentionDays (integer, required): Days in attention in the period.

• open (boolean, required): Still in attention on the period’s last day.

• spans (object[], required): Each run of days in attention: from, to, reason, and resolvedOn, the day it passed again.

• usedBy (object[]): The controls it backs: framework, item and coverage (evidence or supporting).

A framework’s controls #

GET https://api.apitraffic.io/v1/accounts/{accountSid}/compliance/frameworks/{frameworkId}

Takes environmentSid, from (default: 90 days before yesterday) and to. Returns the framework with counts and controls, each with:

• id (string, required): The control or question id (CC6.1, 6.3.3).

• title (string, required): Its title, and section when the framework has sections.

• state (string, required): Its state on asOf.

• strip (object[], required): Its state on each day of the period: day and state. days counts the days in each state.

• checks (object[], required): The checks and exports behind it: kind (check or export), id, title, coverage, state and reason. counted lists the checks its state comes from.

• shows (string | null): What ApiTraffic shows for it.

• stillNeed (string | null): What you still need: the part of the control you cover yourself.

• suggestedAnswer (object | null): For a questionnaire (HECVAT): answer to copy, for state. Check it against your copy of the workbook before you send it.

One check on one day #

GET https://api.apitraffic.io/v1/accounts/{accountSid}/compliance/checks/{checkId}

Takes environmentSid and day (default: yesterday). Returns the check’s state, reason and detail on that day, productionOnly, usedBy, and records: each record behind it as it was that day, with kind, key, state, since (the day it took that state) and data. Records never hold request data. truncated is true when there were more records than the 1,000 listed.

Evidence packs #

A pack is a zip file for one framework (or all of them) and one period, with summary.pdf, CSV files, manifest.json and manifest.sig. See Evidence packs.

• sid (string, required): The pack’s identifier (cpk_ and 24 hex digits).

• frameworkId (string, required): A framework id, or all.

• environmentSid (string | null): The environment, or null for the whole account.

• periodStart (string, required): First day, and periodEnd the last.

• kind (string, required): monthly: the canonical pack generated on the 2nd of each month; on_demand: asked for.

• status (string, required): queued, building, ready or failed (with error).

• manifestSha256 (string | null): The SHA-256 of manifest.json, which manifest.sig signs with signatureAlgorithm and the key keyId.

• libraryVersion (string | null): The compliance library it was built with.

• fileCount (integer | null): Files in the pack, and byteSize its size.

• requestedBy (string | null): Who asked for it; null for a monthly pack.

• retainUntil (string | null): Kept until then: six years. Locked until then too where the storage has Object Lock (Amazon S3), not on storage without it (DigitalOcean Spaces).

• bucketSids (string[] | null, required): The buckets a pack asked for covers, or null for every bucket.

List packs #

GET https://api.apitraffic.io/v1/accounts/{accountSid}/compliance/packs

Newest first. Takes environmentSid (empty for account-wide packs only), limit (1 to 100, default 50) and before (packs created before this time, for paging). A token lists its own environment’s packs. Returns packs and configured: false when this installation has no storage for evidence packs, so none can be built or asked for (COMPLIANCE_PACKS_NOT_CONFIGURED).

Get a pack #

GET https://api.apitraffic.io/v1/accounts/{accountSid}/compliance/packs/{packSid}

Ask for a pack #

POST https://api.apitraffic.io/v1/accounts/{accountSid}/compliance/packs

• frameworkId (body, string, required): A framework id, or all for every framework that is on.

• environmentSid (body, string): One environment. Omit for the whole account (an API token gets a pack for its own environment).

• bucketSids (body, string[]): Some buckets only (1 to 50): their records, each check judged again from them, and the account-wide checks (account settings, posture) as the account’s. Omit for every bucket. The pack’s manifest.json lists scope.bucketSids, scope.accountWideChecks and scope.recordsWithoutBucket.

• from (body, string, required): First day (YYYY-MM-DD), within the six years evidence is kept.

• to (body, string, required): Last day, up to yesterday.

Returns the pack, queued. It is built within a few minutes. A pack asked for never replaces a month’s canonical pack. An account may ask for a limited number of packs a day; past it the answer is 429 with COMPLIANCE_PACK_LIMIT.

Download a pack #

GET https://api.apitraffic.io/v1/accounts/{accountSid}/compliance/packs/{packSid}/download

Records the download in the account history, then redirects (302) to a link valid for 60 seconds. With link=true it answers 200 with url and expiresInSeconds instead. A pack that is not ready answers 409.

Settings #

GET https://api.apitraffic.io/v1/accounts/{accountSid}/compliance/settings

PATCH https://api.apitraffic.io/v1/accounts/{accountSid}/compliance/settings

• frameworks (string[], required): The frameworks on. frameworksSet is false while following the default: every framework.

• slaDays (object, required): critical (critical and KEV findings, 30 by default) and high (90 by default): days a finding may stay open.

• auditPeriod (object, required): start and end of the default period, or null.

• separatePackEnvironments (string[], required): Environments that also get their own monthly pack.

A change takes any of frameworks (null for the default), slaCritical and slaHigh (1 to 365, null for the default), auditPeriodStart, auditPeriodEnd and separatePackEnvironments. Owners and admins, signed in. Every change is recorded in the account history.

Compliance platforms #

{provider} is drata or sprinto.

List platforms #

GET https://api.apitraffic.io/v1/accounts/{accountSid}/compliance/integrations

Returns platforms, each with key, name, auth (what connecting needs: fields, each with key, label, secret, required and options), targetLabel (control or monitor), maxFileBytes, and connection: the account’s connection, or null. A credential is never returned.

The connection object #

• provider (string, required): The platform.

• status (string, required): connected (pushing), needs_mapping (no control mapped, so nothing is pushed), failing (three days of failures in a row) or revoked (the platform refused the credential: connect again).

• config (object, required): Settings that are not secret: region, workspaceId.

• credentialHint (string | null): The credential’s last four characters.

• failedDays (integer, required): Days in a row pushing failed, with lastFailureDay and lastError.

• lastSyncedAt (string | null): The last successful push.

Get a connection #

GET https://api.apitraffic.io/v1/accounts/{accountSid}/compliance/integrations/{provider}

The connection with its mappings and recent pushes (packSid, status: queued, pushing, pushed, failed or skipped, attempts, error, remoteId, pushedAt).

Connect #

PUT https://api.apitraffic.io/v1/accounts/{accountSid}/compliance/integrations/{provider}

• credentials.apiKey (body, string): The platform’s API key or token. Omit to keep the stored one and change only config.

• config.region (body, string): The platform’s region.

• config.workspaceId (body, string): Drata: the workspace evidence goes to.

The credential is checked with the platform before it is stored, encrypted. Returns the connection and, for Drata, workspaces the key can see. Owners and admins, signed in.

Disconnect #

DELETE https://api.apitraffic.io/v1/accounts/{accountSid}/compliance/integrations/{provider}

Destroys the credential and removes the mappings and push history. Evidence already in the platform stays there.

Map controls #

GET https://api.apitraffic.io/v1/accounts/{accountSid}/compliance/integrations/{provider}/targets

GET https://api.apitraffic.io/v1/accounts/{accountSid}/compliance/integrations/{provider}/mappings

PUT https://api.apitraffic.io/v1/accounts/{accountSid}/compliance/integrations/{provider}/mappings

targets lists the platform’s controls (Drata) or monitors (Sprinto), each with id, code and label, searched with q. With suggest=true, suggestions holds a suggested target for each control of the frameworks on.

PUT mappings replaces the mappings with mappings, each with frameworkId, controlId, targetId and targetLabel (up to 1,000). With none, the connection needs mapping and nothing is pushed. Every change is recorded in the account history.

Push a pack now #

POST https://api.apitraffic.io/v1/accounts/{accountSid}/compliance/integrations/{provider}/push

• packSid (body, string, required): A ready, account-wide pack.

Queues the push and returns queued. Monthly packs are pushed on their own. Owners and admins, signed in.

Errors #