Architecture Standards API

Documents-backed standards endpoints are available under /api/v1.0/spaces/{slug}/standards. They expose the Architecture Standards workspace, published standard_item inventory, constraint validation, exception review, AI-generated artifact proposals, managed artifact repository files, and repository rollout.

All endpoints require authentication and access to the target space.

export QARION_API="https://api.qarion.com/api/v1.0"
export QARION_TOKEN="YOUR_API_KEY"
export QARION_SPACE="platform"

Workspace and Inventory

Method	Endpoint	Description
GET	/spaces/{slug}/standards/workspace	Get the standards root page metadata.
GET	/spaces/{slug}/standards/tree	List the standards document tree.
GET	/spaces/{slug}/standards/items	List extracted standard_item blocks plus parse errors.
GET	/spaces/{slug}/standards/constraints	List constraints derived from supported standard_item.rule values.
GET	/spaces/{slug}/standards/validation	Validate supported repository config files against derived constraints.

List published standard items:

curl "$QARION_API/spaces/$QARION_SPACE/standards/items" \
  -H "Authorization: Bearer $QARION_TOKEN"

A standard_item response includes its stable id, human-readable title and statement, severity, applies_to, tags, structured rule, artifact_targets, source page metadata, active exceptions, and retrieval text. Parse errors are returned alongside valid items so authors can fix invalid YAML blocks without losing the rest of the inventory.

Validate repository configuration against constraints derived from published standard items:

curl "$QARION_API/spaces/$QARION_SPACE/standards/validation" \
  -H "Authorization: Bearer $QARION_TOKEN"

Validation results include passed, target_exists, actual_value, expected_value, a message, and the source standard item that produced the check. V1 derivation supports pyproject.ruff, eslint.required_plugins, precommit.required_repositories, snowflake.*, snowpark.*, bigquery.*, and agentic.instructions.

snowpark.* checks parse Python AST only. They do not import snowflake.snowpark, execute repository code, shell out, or connect to Snowflake. Snowpark pages can generate scripts/validate_snowpark_standards.py; teams commonly run it with python scripts/validate_snowpark_standards.py . in pre-commit or GitHub Actions.

agentic.instructions checks scan common agent-facing files: AGENTS.md, accepted-but-non-canonical agents.md, CLAUDE.md, .cursorrules, and .cursor/rules/*.md(c). The canonical generated file is AGENTS.md; companion files can either include the required guidance directly or clearly defer to AGENTS.md.

Exceptions

Method	Endpoint	Description
GET	/spaces/{slug}/standards/exceptions?status=pending	List standards exceptions, optionally filtered by status.
POST	/spaces/{slug}/standards/items/{item_id}/exceptions	File a standards exception for one item.
POST	/spaces/{slug}/standards/exceptions/{exception_id}/approve	Approve a pending exception.
POST	/spaces/{slug}/standards/exceptions/{exception_id}/reject	Reject a pending exception.
POST	/spaces/{slug}/standards/exceptions/{exception_id}/cancel	Cancel an exception requested by the current user.
POST	/spaces/{slug}/standards/exceptions/{exception_id}/revoke	Revoke an approved exception.

Create a scoped exception:

curl -X POST "$QARION_API/spaces/$QARION_SPACE/standards/items/python.ruff-tooling/exceptions" \
  -H "Authorization: Bearer $QARION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": {
      "paths": ["legacy/pyproject.toml"],
      "components": ["legacy-importer"]
    },
    "reason": "Legacy formatter migration is scheduled separately.",
    "business_justification": "Avoids blocking a regulated release branch.",
    "expires_at": "2026-09-30T00:00:00Z"
  }'

Approve or reject exceptions from the request workflow or through the standards API:

curl -X POST "$QARION_API/spaces/$QARION_SPACE/standards/exceptions/EXCEPTION_ID/approve" \
  -H "Authorization: Bearer $QARION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"notes":"Approved until the legacy importer is migrated."}'

Artifact Generation

Method	Endpoint	Description
POST	/spaces/{slug}/standards/pages/{page_id}/artifacts/generate	Generate deterministic artifacts from page blocks and store them as attachments.
POST	/spaces/{slug}/standards/pages/{page_id}/artifacts/ai-preview	Generate AI artifact proposals for review.
POST	/spaces/{slug}/standards/pages/{page_id}/artifacts/ai-preview/stream	Stream AI artifact proposal progress as server-sent events.
POST	/spaces/{slug}/standards/pages/{page_id}/artifacts/apply	Apply selected AI artifact proposals as page attachments and managed repository files.
POST	/spaces/{slug}/standards/pages/{page_id}/artifacts/repository-preview	Preview managed repository changes for selected artifacts.

Generate deterministic artifacts from standard_artifact blocks:

curl -X POST "$QARION_API/spaces/$QARION_SPACE/standards/pages/PAGE_ID/artifacts/generate" \
  -H "Authorization: Bearer $QARION_TOKEN"

Preview AI-generated artifacts from standard_item blocks:

curl -X POST "$QARION_API/spaces/$QARION_SPACE/standards/pages/PAGE_ID/artifacts/ai-preview" \
  -H "Authorization: Bearer $QARION_TOKEN"

The preview response contains reviewable artifact proposals:

{
  "artifacts": [
    {
      "file_name": ".pre-commit-config.yaml",
      "file_type": "text/yaml",
      "content": "repos:\n  - repo: https://github.com/astral-sh/ruff-pre-commit\n",
      "source_item_ids": ["python.ruff-tooling"],
      "rationale": "Applies the Ruff standard through pre-commit.",
      "detected_artifact_type": "pre_commit",
      "detected_language": "yaml",
      "validation_passed": true,
      "validation_checks": []
    }
  ],
  "ai_log_ids": ["5b50842c-97b0-4d72-93e2-583a5e1dd5ab"],
  "validation_attempts": 1,
  "workflow_run_id": "65e4ce3b-a043-41c5-b3b5-6e51f267624f"
}

Agentic standards use the same artifact workflow. A page containing agentic.instructions items can produce AGENTS.md and, when generate_common_companions is true, companion files such as CLAUDE.md and .cursor/rules/qarion-agentic-standards.mdc.

Stream AI workflow progress when you want status updates before the final review payload:

curl -N -X POST "$QARION_API/spaces/$QARION_SPACE/standards/pages/PAGE_ID/artifacts/ai-preview/stream" \
  -H "Authorization: Bearer $QARION_TOKEN" \
  -H "Accept: text/event-stream"

The stream emits planner progress events and ends with a final_response event containing the same artifact preview payload as the non-streaming endpoint.

Apply selected proposals after a human review:

curl -X POST "$QARION_API/spaces/$QARION_SPACE/standards/pages/PAGE_ID/artifacts/apply" \
  -H "Authorization: Bearer $QARION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "artifacts": [
      {
        "file_name": ".pre-commit-config.yaml",
        "file_type": "text/yaml",
        "content": "repos:\n  - repo: https://github.com/astral-sh/ruff-pre-commit\n",
        "source_item_ids": ["python.ruff-tooling"],
        "rationale": "Applies the Ruff standard through pre-commit.",
        "validation_passed": true
      }
    ]
  }'

The apply response includes created or updated page attachments and managed artifact repository information when available.

Repository Preview and Rollout

Method	Endpoint	Description
GET	/spaces/{slug}/standards/artifacts/repository/files	List files currently present in the managed standards artifact repository.
POST	/spaces/{slug}/standards/artifacts/rollout-preview	Preview artifact changes for selected target repositories.
POST	/spaces/{slug}/standards/artifacts/rollout-apply	Apply artifact rollout and create or update provider merge requests when supported.

Preview the managed standards artifact repository diff for selected proposals:

curl -X POST "$QARION_API/spaces/$QARION_SPACE/standards/pages/PAGE_ID/artifacts/repository-preview" \
  -H "Authorization: Bearer $QARION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "artifacts": [
      {
        "file_name": ".github/workflows/standards.yml",
        "file_type": "text/yaml",
        "content": "name: Standards\non: [pull_request]\njobs: {}\n",
        "source_item_ids": ["delivery.ci-standards"],
        "rationale": "Adds a standards check workflow.",
        "validation_passed": true
      }
    ]
  }'

List files already present in the managed artifact repository:

curl "$QARION_API/spaces/$QARION_SPACE/standards/artifacts/repository/files" \
  -H "Authorization: Bearer $QARION_TOKEN"

Preview rollout to target repositories:

curl -X POST "$QARION_API/spaces/$QARION_SPACE/standards/artifacts/rollout-preview" \
  -H "Authorization: Bearer $QARION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "repository_ids": ["8f2a1ff0-5df0-4e51-8510-6d6264d11f44"]
  }'

Apply rollout after reviewing the preview:

curl -X POST "$QARION_API/spaces/$QARION_SPACE/standards/artifacts/rollout-apply" \
  -H "Authorization: Bearer $QARION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "repository_ids": ["8f2a1ff0-5df0-4e51-8510-6d6264d11f44"]
  }'

Rollout responses include per-repository status, changed files, source branch, target branch, merge request metadata, and any provider error. Each generated file keeps source standard item and source page metadata so reviewers can trace repository changes back to the published standard.

Related

• Documents API - Standards pages use document drafts, revisions, comments, attachments, diagrams, and polls
• Templates API - Architecture page templates
• Search API - Published standards pages participate in document search
• User Guide - Practical workflow for standards, ADRs, RFCs, diagrams, polls, exceptions, and Git rollout