docs: engine API contract spec + OpenAPI 3.1 document (Epic 0, issue #3011)#3013
Merged
Merged
Conversation
…issue #3011) Create docs/studio/engine-api-contract.md and docs/studio/openapi.yaml to define the AGT Studio Engine API before implementation begins, fulfilling the gate requirement in ADR 0028 lines 142-148. - engine-api-contract.md: human-readable spec covering all 12 HTTP endpoints, three capability flags (runtime_mutating, user_intent_required, read_only_surface), read-only invariant with client-allowlist worked example, auth model (loopback/non-loopback), error envelope, pagination model, conformance rules, excluded endpoints (POST /api/v1/policy/reload), and WebSocket route reservation (/api/v1/events, Epic 7a) - openapi.yaml: OpenAPI 3.1 document with x-capability-flags extension on every operation, full request/response schemas, reusable error and pagination components, and BearerToken security scheme; passes npx @redocly/cli lint with zero warnings - mkdocs.yml: add Studio nav section linking to engine-api-contract.md No existing source files modified. Docs link check and frontmatter check pass. Closes #3011 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Ricky Gummadi <ricky.gummadi@outlook.com>
Ricky-G
requested review from
MohammadHaroonAbuomar and
imran-siddique
as code owners
Dependency Review✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.Scanned FilesNone |
github-actions
Bot
added
documentation
PR Review Summary
Verdict: AI review comments are untrusted advisory output. The summary reports workflow-generated completion status only, not model-authored pass/fail claims. |
|
🟡 Contributor Check: MEDIUM
Automated check by AGT Contributor Check. |
github-actions
Bot
added
the
needs-review:MEDIUM
Ground trust_level enum in the real trust_level_for_score vocabulary (untrusted, probationary, standard, trusted, verified_partner) instead of invented values, document the reserved WS /api/v1/events route with its three capability flags in both files (spec flag table + section 12, and an x-reserved-routes block in openapi.yaml), exclude reserved routes from the client allowlist, add the optional resolution_metadata field to FixtureResult to match policy_test.FixtureResult, and clarify how inline fixtures are adapted for policy_test.replay. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Ricky Gummadi <ricky.gummadi@outlook.com>
Replace informal 'footgun' with 'dangerous pattern', fix two example error messages that contained the intentional typo 'actiom' (the spell checker flags example strings too), and add Redocly to the repo cspell terms file as it is a recognised tool name. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Ricky Gummadi <ricky.gummadi@outlook.com>
Ricky-G
changed the title
imran-siddique
approved these changes
Jun 14, 2026
imran-siddique
left a comment
imran-siddique
left a comment
Collaborator
There was a problem hiding this comment.
Spec looks good — fulfills the ADR-0028 gate requirement. Approving.
Collaborator
|
/ok-to-test |
1 task
This was referenced Jun 15, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Define the AGT Studio Engine API by shipping two artifacts: a human-readable spec (
docs/studio/engine-api-contract.md) and a machine-readable OpenAPI 3.1 document (docs/studio/openapi.yaml). This is the gate for Epic 0 issues 2-4 and all of Epic 1, fulfilling the contract requirement from ADR 0028 lines 142-148.Problem
ADR 0028 mandates that an Engine API contract must exist before Studio implementation lands. Without this spec, issues #2 (capability metadata decorator), #3 (FastAPI implementation), and #4 (conformance tests) have no contract to implement or test against.
Changes
docs/studio/engine-api-contract.mddocs/studio/openapi.yamlx-capability-flagsextension, full request/response schemas, reusableErrorandPaginationMetacomponents,BearerTokensecurity scheme; zero warnings fromnpx @redocly/cli lintmkdocs.ymlengine-api-contract.mdNo existing source files modified. This is a doc-only PR.
Acceptance criteria verification
docs/studio/engine-api-contract.mdexists and includes the maintainer note about skipping ADR 0029docs/studio/openapi.yamlexists and passesnpx @redocly/cli lint(zero warnings, exit 0)runtime_mutating: true(POST /api/v1/policy/save)POST /api/v1/policy/reloadis named in the "Excluded Endpoints" section with rationale/api/v1/eventsis reserved with a pointer to Epic 7a/policies,/audit/log,/decisions,/agentsTesting
Doc-only PR. Validated with:
npx @redocly/cli lint docs/studio/openapi.yamlpasses (zero warnings, exit 0)python scripts/docs/check_links.pypasses (0 new broken links, exit 0)python scripts/docs/check_frontmatter.pypasses (all 300 warnings are pre-existing, exit 0)