AI Attack Surface API

Use the AI Attack Surface Management API to automate inventory reporting, finding triage, approval workflows, policy management, and evidence export. All routes use the base URL https://codestax.co/api and are tenant scoped.

Read operations require viewer access or an API key with read:findings. Finding triage requires member access or write:findings. Asset approval, policy changes, and waivers require a signed-in organization admin or owner.

AI BOM routes use the dedicated read:ai-bom API-key scope. Verified BOM declarations can be changed only by a signed-in organization admin or owner; API keys are read-only.

Endpoint summary

Method	Path	Purpose
`GET`	`/api/ai-asm/capabilities`	Return the current principal’s allowed operations
`GET`	`/api/ai-asm/summary`	Return organization or repository totals
`GET`	`/api/ai-asm/repositories`	List inventory freshness by repository
`GET`	`/api/ai-asm/assets`	Search and filter assets
`GET`	`/api/ai-asm/assets/{asset_id}`	Return an asset with observations, relationships, and findings
`PATCH`	`/api/ai-asm/assets/{asset_id}/approval`	Record an asset approval decision
`GET`	`/api/ai-asm/findings`	Search and filter findings
`GET`	`/api/ai-asm/findings/{finding_id}`	Return a finding with evidence
`PATCH`	`/api/ai-asm/findings/{finding_id}/triage`	Change finding status
`GET`	`/api/ai-asm/runs`	List analyzer runs and coverage
`GET`	`/api/ai-asm/graph`	Return active asset nodes and relationships
`GET`	`/api/ai-asm/policy`	Return the organization policy
`PUT`	`/api/ai-asm/policy`	Replace the organization policy
`GET`	`/api/ai-asm/policy/repositories/{repo_id}`	Return a repository override
`PUT`	`/api/ai-asm/policy/repositories/{repo_id}`	Create or update a repository override
`DELETE`	`/api/ai-asm/policy/repositories/{repo_id}`	Delete a repository override
`GET`	`/api/ai-asm/waivers`	List active or historical waivers
`POST`	`/api/ai-asm/waivers`	Create an expiring waiver
`POST`	`/api/ai-asm/waivers/{waiver_id}/revoke`	Revoke a waiver
`GET`	`/api/ai-asm/export`	Export assets or findings as CSV
`GET`	`/api/ai-bom/repositories/{repo_id}`	Return current BOM identity, coverage, field completeness, and format readiness
`GET`	`/api/ai-bom/repositories/{repo_id}/versions`	List complete authoritative BOM generations
`GET`	`/api/ai-bom/repositories/{repo_id}/diff`	Compare two authoritative generations
`GET`	`/api/ai-bom/repositories/{repo_id}/export`	Export the current generation
`GET`	`/api/ai-bom/repositories/{repo_id}/versions/{generation}/export`	Export one historical generation
`GET`	`/api/ai-bom/assets/{asset_id}/declaration`	Return verified metadata used for standards readiness
`PUT`	`/api/ai-bom/assets/{asset_id}/declaration`	Version and audit a BOM metadata declaration

Get a summary


$ curl -H "X-API-Key: $CODESTAX_API_KEY" \
  "https://codestax.co/api/ai-asm/summary?repo_id=<repo_id>"

Omit repo_id for the organization-wide view. The response includes active asset totals, current open findings, OWASP and severity breakdowns, unapproved assets, policy failures, and the latest run.

List assets


$ curl -H "X-API-Key: $CODESTAX_API_KEY" \
  "https://codestax.co/api/ai-asm/assets?asset_type=provider&approval_status=unreviewed&limit=50"

Supported filters are repo_id, asset_type, risk_level, approval_status, status, search, skip, and limit. limit can be 1–200.

Approve an asset


$ curl -X PATCH \
  -H "Authorization: Bearer $CODESTAX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"approval_status":"approved","reason":"Provider and data controls reviewed"}' \
  "https://codestax.co/api/ai-asm/assets/<asset_id>/approval"

Allowed approval values are unreviewed, approved, restricted, and denied.

List and triage findings


$ curl -H "X-API-Key: $CODESTAX_API_KEY" \
  "https://codestax.co/api/ai-asm/findings?severity=high&owasp_category=LLM06&status=open"


$ curl -X PATCH \
  -H "X-API-Key: $CODESTAX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"accepted_risk","reason":"Compensating approval is required for every tool call"}' \
  "https://codestax.co/api/ai-asm/findings/<finding_id>/triage"

Allowed statuses are open, acknowledged, accepted_risk, resolved, and dismissed. A reason is required for the last three.

Inspect runs and topology


$ curl -H "X-API-Key: $CODESTAX_API_KEY" \
  "https://codestax.co/api/ai-asm/runs?repo_id=<repo_id>&coverage_status=complete"


$ curl -H "X-API-Key: $CODESTAX_API_KEY" \
  "https://codestax.co/api/ai-asm/graph?repo_id=<repo_id>&limit=1000"

The graph response reports truncated: true when the node limit excludes part of the inventory.

Manage policy

First read the policy and retain its version. Send that value as expected_version to prevent lost updates.


$ curl -X PUT \
  -H "Authorization: Bearer $CODESTAX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "expected_version": 3,
    "enabled": true,
    "allowlist_enforced": true,
    "allowed_providers": ["openai", "anthropic"],
    "denied_models": ["legacy-model"],
    "require_model_pinning": true,
    "require_approved_assets": true,
    "block_prompt_injection": true,
    "block_sensitive_data_exposure": true,
    "fail_on_coverage_gap": true,
    "gate_enabled": true,
    "max_critical_findings": 0,
    "max_high_findings": 2
  }' \
  "https://codestax.co/api/ai-asm/policy"

A stale expected_version returns 409 Conflict. A repository override uses the same fields, but every control is optional:


PUT /api/ai-asm/policy/repositories/{repo_id}

Delete the override to restore organization inheritance:


DELETE /api/ai-asm/policy/repositories/{repo_id}

Create a waiver


$ curl -X POST \
  -H "Authorization: Bearer $CODESTAX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "repository",
    "repo_id": 42,
    "rule_id": "AIASM-LLM06-001",
    "reason": "Migration window with a reviewed manual approval control",
    "expires_at": "2027-09-30T23:59:59Z"
  }' \
  "https://codestax.co/api/ai-asm/waivers"

Use scope: organization without a repository or finding. Use scope: finding with both repo_id and finding_id. Waivers must expire in the future and within 366 days.

Export CSV


$ curl -H "X-API-Key: $CODESTAX_API_KEY" \
  "https://codestax.co/api/ai-asm/export?kind=findings&repo_id=<repo_id>" \
  -o ai-attack-surface-findings.csv

kind is assets or findings. Exports include at most 10,000 rows; inspect X-Export-Truncated before treating the file as complete.

Inspect AI BOM readiness


$ curl -H "X-API-Key: $CODESTAX_AI_BOM_KEY" \
  "https://codestax.co/api/ai-bom/repositories/<repo_id>"

The response separates coverage_status, bom_completeness, freshness_status, and snapshot_fidelity. Each entry in formats has its own ready flag and blockers. A missing current default-branch generation returns 409 AI_BOM_NOT_READY.

Export CycloneDX or SPDX


$ curl -H "X-API-Key: $CODESTAX_AI_BOM_KEY" \
  "https://codestax.co/api/ai-bom/repositories/<repo_id>/export?format=cyclonedx-1.7-json" \
  -o ai-bom.cdx.json

Use format=spdx-3.0.1-jsonld for SPDX AI Profile. SPDX returns 409 SPDX_AI_PROFILE_NOT_READY until every model and dataset has the mandatory verified declarations.

Successful downloads include:

ETag and X-Content-SHA256 for integrity and conditional requests;
X-AI-BOM-Generation and X-AI-BOM-Commit for provenance;
X-AI-BOM-Coverage and X-AI-BOM-Snapshot-Fidelity; and
a safe Content-Disposition filename.

Send If-None-Match with the previous ETag to receive 304 Not Modified when the artifact bytes have not changed.

Compare BOM generations


$ curl -H "X-API-Key: $CODESTAX_AI_BOM_KEY" \
  "https://codestax.co/api/ai-bom/repositories/<repo_id>/diff?from_generation=3&to_generation=4"

The response reports asset additions, removals, modified fields, evidence-only changes, relationship changes, and unchanged assets. comparison_status is exact, inferred, or requires_rebaseline. A canonicalization-version change returns requires_rebaseline rather than treating identity churn as a real supply-chain change.

Declare SPDX-required metadata

Read the current declaration and retain its version. Send it as expected_version when updating:


$ curl -X PUT \
  -H "Authorization: Bearer $CODESTAX_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "expected_version": 0,
    "supplier_name": "Acme AI",
    "component_version": "2026-07-15",
    "declared_license": "Apache-2.0",
    "download_location": "https://models.example.com/acme/2026-07-15",
    "release_time": "2026-07-15T12:00:00Z",
    "source_kind": "upstream",
    "source_uri": "https://models.example.com/acme/model-card",
    "source_digest": "<64-character-sha256>",
    "verified": true
  }' \
  "https://codestax.co/api/ai-bom/assets/<asset_id>/declaration"

source_kind is manual, repository, upstream, or imported_attestation. Non-manual sources require a URI or SHA-256 digest. A stale version returns 409 Conflict.

See Manage your AI attack surface for the dashboard workflow and coverage model.