Versions

Generated from apiome-rest/openapi.yaml (API version 1.204.1) — do not edit by hand. How to authenticate is on the REST API reference.

Tag: versions · 52 operations

GET /v1/versions/{tenant_slug}/sunset-timeline

Get Sunset Timeline

Aggregate deprecation and sunset dates across projects (#508). Must be registered before /{tenant_slug}/{project_id} so sunset-timeline is not parsed as a project id.

Operation id: get_sunset_timeline_v1_versions__tenant_slug__sunset_timeline_get

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
projectId	query	string or null	no	Query parameter: project id.
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Responses

Status	Description	Body
200	Successful response for get sunset timeline.	application/json SunsetTimelineResponse
422	Validation Error	application/json HTTPValidationError

GET /v1/versions/{tenant_slug}/{project_id}

List Versions

List all versions for a project.

Supports authentication via:

• JWT token in Authorization header (Bearer token)
• API key in X-API-Key header

Args: tenant_slug: The tenant slug project_id: The project ID auth_data: Authentication data (injected by dependency)

Returns: List of versions for the project

Operation id: list_versions_v1_versions__tenant_slug___project_id__get

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
lifecycle	query	string or null	no	Filter catalog/history by revision lifecycle tag (#739): stable, beta, deprecated, archived.
q	query	string or null	no	Search revision note, changelog, full commit message body, and commit author (case-insensitive, #2579).
creatorId	query	string or null	no	Filter by creator user id (#2579).
createdAfter	query	string (date-time) or null	no	Include revisions with created_at on or after this instant (ISO 8601, #2579).
createdBefore	query	string (date-time) or null	no	Include revisions with created_at on or before this instant (ISO 8601, #2579).
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Responses

Status	Description	Body
200	Successful response for list versions.	application/json array of VersionSchema
422	Validation Error	application/json HTTPValidationError

POST /v1/versions/{tenant_slug}/{project_id}

Create Version

Create a new version (push).

Supports authentication via JWT token or API key. When using JWT, the creator_id field will be set to the authenticated user.

Optimistic locking (#2566): baseRevisionId is required. It must match the server head (branch tip, or latest revision when there are no branches) before this push. If another client advanced the head, the API returns 409 with code: STALE_HEAD and currentHead metadata.

If version_id is not provided, it will be auto-generated by bumping the latest version. Use bump_strategy='minor' for minor version bump, or 'patch' (default) for patch bump.

If source_version_id is provided, classes will be copied from that version.

A push is a version change, so the new revision's quality/lint score is captured onto its record after the response is sent (#5259) — the versions list then renders the badge from the stored score instead of linting on read.

Args: tenant_slug: The tenant slug project_id: The project ID request: Version creation data background_tasks: FastAPI background tasks (post-response lint capture) auth_data: Authentication data (injected by dependency)

Returns: The created version

Operation id: create_version_v1_versions__tenant_slug___project_id__post

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Request body (required)

Request body for create version.

• application/json — VersionCreateRequest

Responses

Status	Description	Body
200	Successful response for create version.	application/json VersionSchema
422	Validation Error	application/json HTTPValidationError

GET /v1/versions/{tenant_slug}/{project_id}/by-version/{version_id}

Get Version By Version Id

Get a specific version by version ID string (e.g., '1.0.0').

Supports authentication via JWT token or API key. Successor resolution (#749) matches GET .../{version_record_id}. Pull payload selection (#2591) matches GET .../{version_record_id}. Delta pull (#2592) matches GET .../{version_record_id}.

Operation id: get_version_by_version_id_v1_versions__tenant_slug___project_id__by_version__version_id__get

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_id	path	string	yes	Version identifier or semantic version label, depending on the route.
successorResolution	query	enum "none", "resolve", "redirect"	no	none: return the requested revision only. resolve: follow metadata.successorRevisionId (same project, #748); JSON body is the final revision; see X-Apiome-* response headers. redirect: HTTP 307 to this path with the final revision id and successorResolution=none.
auditSuccessorResolution	query	boolean	no	When true, emit version_protection_audit for successor resolution (#749).
includeSections	query	string or null	no	Comma-separated pull payload sections to include (#2591). Always includes id, project_id, and version_id. Mutually exclusive with excludeSections. Sections: core, commit, publish, lineage, governance, creator, project, timestamps.
excludeSections	query	string or null	no	Comma-separated sections to omit from the pull body (#2591). Core identifiers cannot be removed. Mutually exclusive with includeSections.
sinceRevisionId	query	string or null	no	When set, the JSON body includes schemaPullDelta with changed OpenAPI components.schemas entities since this revision (#2592). Must be the resolved head revision or an ancestor in the revision parent graph.
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Responses

Status	Description	Body
200	Full VersionSchema, or JSON with includeSections/excludeSections (#2591), or JSON with schemaPullDelta when sinceRevisionId is set (#2592).	application/json VersionSchema
422	Validation Error	application/json HTTPValidationError

POST /v1/versions/{tenant_slug}/{project_id}/fork

Fork Version From Revision

Fork a schema version line into this project from a source revision in another project (sandbox / provenance).

Not the same as a named branch within one project (#500): fork is cross-project isolation with recorded lineage. The forked revision's quality/lint score is captured after the response is sent (#5259).

Operation id: fork_version_from_revision_v1_versions__tenant_slug___project_id__fork_post

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Request body (required)

Request body for fork version from revision.

• application/json — VersionForkRequest

Responses

Status	Description	Body
200	Successful response for fork version from revision.	application/json VersionSchema
422	Validation Error	application/json HTTPValidationError

GET /v1/versions/{tenant_slug}/{project_id}/merge-sessions/{merge_session_id}

Get Merge Session

Load persisted merge session and status transition history (#2573).

Operation id: get_merge_session_v1_versions__tenant_slug___project_id__merge_sessions__merge_session_id__get

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
merge_session_id	path	string	yes	Path parameter identifying the merge session id segment.
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Responses

Status	Description	Body
200	Successful response for get merge session.	application/json object
422	Validation Error	application/json HTTPValidationError

PATCH /v1/versions/{tenant_slug}/{project_id}/merge-sessions/{merge_session_id}

Patch Merge Session Status

Transition merge session status with audited events (#2573).

Operation id: patch_merge_session_status_v1_versions__tenant_slug___project_id__merge_sessions__merge_session_id__patch

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
merge_session_id	path	string	yes	Path parameter identifying the merge session id segment.
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Request body (required)

Request body for patch merge session status.

• application/json — MergeSessionStatusPatchRequest

Responses

Status	Description	Body
200	Successful response for patch merge session status.	application/json object
422	Validation Error	application/json HTTPValidationError

GET /v1/versions/{tenant_slug}/{project_id}/merge-sessions/{merge_session_id}/conflicts

List Merge Session Conflicts Route

List conflict rows for a merge session (#2573).

Operation id: list_merge_session_conflicts_route_v1_versions__tenant_slug___project_id__merge_sessions__merge_session_id__conflicts_get

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
merge_session_id	path	string	yes	Path parameter identifying the merge session id segment.
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Responses

Status	Description	Body
200	Successful response for list merge session conflicts route.	application/json object
422	Validation Error	application/json HTTPValidationError

GET /v1/versions/{tenant_slug}/{project_id}/version-branches

List Version Branches

List named version branches for a project (Studio BFF / git menu).

Operation id: list_version_branches_v1_versions__tenant_slug___project_id__version_branches_get

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Responses

Status	Description	Body
200	Successful response for list version branches.	application/json array of object
422	Validation Error	application/json HTTPValidationError

POST /v1/versions/{tenant_slug}/{project_id}/version-branches

Create Version Branch

Create a branch whose tip is an existing revision.

Operation id: create_version_branch_v1_versions__tenant_slug___project_id__version_branches_post

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Request body (required)

Request body for create version branch.

• application/json — VersionBranchCreateRequest

Responses

Status	Description	Body
200	Successful response for create version branch.	application/json object
422	Validation Error	application/json HTTPValidationError

POST /v1/versions/{tenant_slug}/{project_id}/version-branches/from-revision

Version Branch From Revision

Create a named branch whose tip is an existing revision (in-project lineage; #2570).

Idempotency: Repeating the same branchName + sourceRevisionId returns 200 with idempotentReplay: true when the branch already exists with that tip (and compatible lineage). Conflicting reuse of branchName returns 409 with a clear message.

Operation id: version_branch_from_revision_v1_versions__tenant_slug___project_id__version_branches_from_revision_post

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Request body (required)

Request body for version branch from revision.

• application/json — VersionBranchFromRevisionRequest

Responses

Status	Description	Body
200	Successful response for version branch from revision.	application/json VersionBranchFromRevisionResponse
422	Validation Error	application/json HTTPValidationError

POST /v1/versions/{tenant_slug}/{project_id}/version-branches/merge

Version Branch Merge

Execute merge into target branch: new revision with two parents, three-way materialization.

Operation id: version_branch_merge_v1_versions__tenant_slug___project_id__version_branches_merge_post

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Request body (required)

Request body for version branch merge.

• application/json — VersionBranchMergeRequest

Responses

Status	Description	Body
200	Successful response for version branch merge.	application/json object
422	Validation Error	application/json HTTPValidationError

POST /v1/versions/{tenant_slug}/{project_id}/version-branches/merge-preview

Version Branch Merge Preview

Dry-run merge (no DB writes): merge-base id, two-way summary counts, per-kind conflict metadata, classification, and optional capped merged OpenAPI when auto-merge is possible (#2572).

Operation id: version_branch_merge_preview_v1_versions__tenant_slug___project_id__version_branches_merge_preview_post

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Request body (required)

Request body for version branch merge preview.

• application/json — VersionBranchMergePreviewRequest

Responses

Status	Description	Body
200	Successful response for version branch merge preview.	application/json object
422	Validation Error	application/json HTTPValidationError

POST /v1/versions/{tenant_slug}/{project_id}/version-branches/rollback

Version Branch Rollback

Apply revert-style rollback: new revision with target snapshot, parent = prior tip (#745).

Operation id: version_branch_rollback_v1_versions__tenant_slug___project_id__version_branches_rollback_post

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Request body (required)

Request body for version branch rollback.

• application/json — VersionBranchRollbackRequest

Responses

Status	Description	Body
200	Successful response for version branch rollback.	application/json object
422	Validation Error	application/json HTTPValidationError

POST /v1/versions/{tenant_slug}/{project_id}/version-branches/rollback-preview

Version Branch Rollback Preview

Dry-run rollback: schema compatibility tip→target, deprecation warnings (#506), fingerprint.

Operation id: version_branch_rollback_preview_v1_versions__tenant_slug___project_id__version_branches_rollback_preview_post

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Request body (required)

Request body for version branch rollback preview.

• application/json — VersionBranchRollbackPreviewRequest

Responses

Status	Description	Body
200	Successful response for version branch rollback preview.	application/json object
422	Validation Error	application/json HTTPValidationError

PATCH /v1/versions/{tenant_slug}/{project_id}/version-branches/{branch_id}

Patch Version Branch Policy

Tenant administrators: set protected and/or requireMergePath and/or promote default branch.

Operation id: patch_version_branch_policy_v1_versions__tenant_slug___project_id__version_branches__branch_id__patch

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
branch_id	path	string	yes	Path parameter identifying the branch id segment.
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Request body (required)

Request body for patch version branch policy.

• application/json — VersionBranchPolicyPatchRequest

Responses

Status	Description	Body
200	Successful response for patch version branch policy.	application/json object
422	Validation Error	application/json HTTPValidationError

GET /v1/versions/{tenant_slug}/{project_id}/version-branches/{branch_id}/divergence

Get Version Branch Divergence

Branch-vs-branch divergence: merge base, ahead/behind counts, and sampled commits (#2721).

Operation id: get_version_branch_divergence_v1_versions__tenant_slug___project_id__version_branches__branch_id__divergence_get

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
branch_id	path	string	yes	Path parameter identifying the branch id segment.
against	query	string or null	no	Query parameter: against.
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Responses

Status	Description	Body
200	Successful response for get version branch divergence.	application/json VersionBranchDivergenceResponse
422	Validation Error	application/json HTTPValidationError

GET /v1/versions/{tenant_slug}/{project_id}/{version_record_id}

Get Version

Get a specific version by ID.

Supports authentication via JWT token or API key.

Successor resolution (#749): when successorResolution is resolve or redirect, follows metadata.successorRevisionId (#748) within the project until a revision has no successor, hits a protected branch tip / protected tag target (#504), or errors. Loops return 409 SUCCESSOR_CYCLE.

Pull payload selection (#2591): includeSections / excludeSections reduce JSON size for CI; the strong ETag still identifies the revision only (same as full body, #2568).

Delta pull (#2592): sinceRevisionId adds schemaPullDelta (changed schema entities only).

Operation id: get_version_v1_versions__tenant_slug___project_id___version_record_id__get

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
successorResolution	query	enum "none", "resolve", "redirect"	no	none: return the requested revision only. resolve: follow metadata.successorRevisionId (same project, #748); JSON body is the final revision; see X-Apiome-* response headers. redirect: HTTP 307 to this path with the final revision id and successorResolution=none.
auditSuccessorResolution	query	boolean	no	When true, emit version_protection_audit for successor resolution (#749).
includeSections	query	string or null	no	Comma-separated pull payload sections to include (#2591). Always includes id, project_id, and version_id. Mutually exclusive with excludeSections. Sections: core, commit, publish, lineage, governance, creator, project, timestamps.
excludeSections	query	string or null	no	Comma-separated sections to omit from the pull body (#2591). Core identifiers cannot be removed. Mutually exclusive with includeSections.
sinceRevisionId	query	string or null	no	When set, the JSON body includes schemaPullDelta with changed OpenAPI components.schemas entities since this revision (#2592). Must be the resolved head revision or an ancestor in the revision parent graph.
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Responses

Status	Description	Body
200	Full VersionSchema, or JSON with includeSections/excludeSections (#2591), or JSON with schemaPullDelta when sinceRevisionId is set (#2592).	application/json VersionSchema
422	Validation Error	application/json HTTPValidationError

PUT /v1/versions/{tenant_slug}/{project_id}/{version_record_id}

Update Version

Update an existing version.

Supports authentication via JWT token or API key. Published versions cannot be updated (they are frozen).

Args: tenant_slug: The tenant slug project_id: The project ID version_record_id: The version record ID request: Version update data auth_data: Authentication data (injected by dependency)

Returns: The updated version

Operation id: update_version_v1_versions__tenant_slug___project_id___version_record_id__put

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Request body (required)

Request body for update version.

• application/json — VersionUpdateRequest

Responses

Status	Description	Body
200	Successful response for update version.	application/json VersionSchema
422	Validation Error	application/json HTTPValidationError

DELETE /v1/versions/{tenant_slug}/{project_id}/{version_record_id}

Delete Version

Delete a version (soft delete).

Supports authentication via JWT token or API key.

Args: tenant_slug: The tenant slug project_id: The project ID version_record_id: The version record ID auth_data: Authentication data (injected by dependency)

Returns: Success message

Operation id: delete_version_v1_versions__tenant_slug___project_id___version_record_id__delete

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Responses

Status	Description	Body
200	Successful response for delete version.	application/json map of string
422	Validation Error	application/json HTTPValidationError

GET /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/breaking-publish-guardrail

Get Breaking Publish Guardrail

Preflight the breaking-publish guardrail for a revision (CTG-3.4, #4478).

What the publish dialog calls before showing Publish: it reports whether this revision would break consumers without a major-version bump, which changes are breaking, and whether the tenant's policy warns or blocks. Read-only — nothing is published or stored.

Args: tenant_slug: The tenant slug project_id: The project ID version_record_id: The version record ID auth_data: Authentication data (injected by dependency)

Returns: The guardrail assessment; status is unavailable (never an error) when the comparison could not be made.

Raises: HTTPException: 404 when the revision does not exist in this project.

Operation id: get_breaking_publish_guardrail_v1_versions__tenant_slug___project_id___version_record_id__breaking_publish_guardrail_get

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Responses

Status	Description	Body
200	Successful response for get breaking publish guardrail.	application/json BreakingPublishGuardrailOut
422	Validation Error	application/json HTTPValidationError

GET /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/draft-lock

Get Draft Lock Status

Return whether an active edit lock exists on this draft revision (polling / Studio header #2585).

Operation id: get_draft_lock_status_v1_versions__tenant_slug___project_id___version_record_id__draft_lock_get

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Responses

Status	Description	Body
200	Successful response for get draft lock status.	application/json VersionDraftLockStatusResponse
422	Validation Error	application/json HTTPValidationError

POST /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/draft-lock/acquire

Acquire Draft Lock

Acquire or refresh an edit lock on an unpublished (draft) revision.

Returns 409 with code: DRAFT_LOCK_CONFLICT and ownerUserId / expiresAt when another user holds an active lock.

Operation id: acquire_draft_lock_v1_versions__tenant_slug___project_id___version_record_id__draft_lock_acquire_post

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Request body (optional)

Request body for acquire draft lock.

• application/json — VersionDraftLockAcquireRequest or null

Responses

Status	Description	Body
200	Successful response for acquire draft lock.	application/json VersionDraftLockResponse
422	Validation Error	application/json HTTPValidationError

POST /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/draft-lock/force-release

Force Release Draft Lock

Remove any lock on the revision (tenant administrators only).

Operation id: force_release_draft_lock_v1_versions__tenant_slug___project_id___version_record_id__draft_lock_force_release_post

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Responses

Status	Description	Body
204	Successful response for force release draft lock.	—
422	Validation Error	application/json HTTPValidationError

POST /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/draft-lock/release

Release Draft Lock

Release the current user's lock. Idempotent when no lock exists (204).

Operation id: release_draft_lock_v1_versions__tenant_slug___project_id___version_record_id__draft_lock_release_post

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Responses

Status	Description	Body
204	Successful response for release draft lock.	—
422	Validation Error	application/json HTTPValidationError

POST /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/draft-lock/renew

Renew Draft Lock

Extend the lease on an active lock held by the current user.

Operation id: renew_draft_lock_v1_versions__tenant_slug___project_id___version_record_id__draft_lock_renew_post

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Request body (optional)

Request body for renew draft lock.

• application/json — VersionDraftLockRenewRequest or null

Responses

Status	Description	Body
200	Successful response for renew draft lock.	application/json VersionDraftLockResponse
422	Validation Error	application/json HTTPValidationError

POST /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/freeze-schema

Freeze Version Schema

Freeze (capture) class schemas into apiome.class_schema for this version. Only available when the version has no class_schema rows yet (e.g. published before schema capture existed). Only the version creator or a tenant administrator can freeze schema.

Operation id: freeze_version_schema_v1_versions__tenant_slug___project_id___version_record_id__freeze_schema_post

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Responses

Status	Description	Body
200	Successful response for freeze version schema.	application/json VersionSchema
422	Validation Error	application/json HTTPValidationError

PUT /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/mock

Set Version Mock

Enable or disable the hosted mock for a version (#4422 SIM-2.1, #4446 SIM-2.5).

Operation id: set_version_mock_v1_versions__tenant_slug___project_id___version_record_id__mock_put

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Request body (required)

Request body for set version mock.

• application/json — VersionMockToggleRequest

Responses

Status	Description	Body
200	Successful response for set version mock.	application/json VersionSchema
422	Validation Error	application/json HTTPValidationError

GET /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/mock/bundle

Get Version Mock Bundle

Export the version's portable mock bundle (#4741, PMR-1.1).

The bundle pins the version snapshot (its generated OpenAPI document), the portable subset of versions.mock_settings (scenarios and chaos knobs), and fixture digests into one self-contained, signed JSON document that apiome-mock can serve offline — in CI, on a laptop, or inside an air-gapped network.

The document is deterministic: exporting the same version with the same settings always yields the same manifestDigest, which is the identifier release proofs attach (PMR-3.2). Tenant credentials never travel: only allowlisted settings keys are bundled, and credential-shaped fields inside them are dropped and listed in manifest.redactions.

Args: tenant_slug: The tenant slug. project_id: The project ID that must own the version. version_record_id: The version record ID (UUID) to export. response: Injected so the export can advertise a download filename. auth_data: Authentication context; requires versions:view.

Returns: The bundle document (bundleFormat, manifest, manifestDigest, signature, spec, settings, fixtures).

Raises: HTTPException: 404 when the version does not exist in the project, 409 when mock serving is not enabled for the version.

Operation id: get_version_mock_bundle_v1_versions__tenant_slug___project_id___version_record_id__mock_bundle_get

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Responses

Status	Description	Body
200	Successful response for get version mock bundle.	application/json object
422	Validation Error	application/json HTTPValidationError

GET /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/mock/callbacks

Get Version Mock Callbacks

Return the version's mock callback definitions and their content digests (#4746, PMR-2.3).

Operation id: get_version_mock_callbacks_v1_versions__tenant_slug___project_id___version_record_id__mock_callbacks_get

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Responses

Status	Description	Body
200	Successful response for get version mock callbacks.	application/json VersionMockCallbacksResponse
422	Validation Error	application/json HTTPValidationError

PUT /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/mock/callbacks

Set Version Mock Callbacks

Replace the version's mock callback definitions (#4746, PMR-2.3).

Definitions are validated against the versioned callback schema and against this version's generated OpenAPI document: a trigger must name a real operation, a payloadSchema $ref must resolve, every destination must be a safe absolute http(s) URL, and the retry schedule must stay inside its cost ceiling. Valid definitions are stored canonically in versions.mock_settings under callbacks, alongside the other mock knobs, and travel inside portable mock bundles. The response echoes each definition's content digest — the identity a test asserts when it exercises the callback. An empty callbacks map clears them.

Operation id: set_version_mock_callbacks_v1_versions__tenant_slug___project_id___version_record_id__mock_callbacks_put

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Request body (required)

Request body for set version mock callbacks.

• application/json — VersionMockCallbacksRequest

Responses

Status	Description	Body
200	Successful response for set version mock callbacks.	application/json VersionMockCallbacksResponse
422	Validation Error	application/json HTTPValidationError

GET /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/mock/capture-policy

Get Version Mock Capture Policy

Return the version's guarded proxy capture policy and its current state (#4747, PMR-2.4).

Operation id: get_version_mock_capture_policy_v1_versions__tenant_slug___project_id___version_record_id__mock_capture_policy_get

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Responses

Status	Description	Body
200	Successful response for get version mock capture policy.	application/json VersionMockCapturePolicyResponse
422	Validation Error	application/json HTTPValidationError

PUT /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/mock/capture-policy

Set Version Mock Capture Policy

Authorize (or switch off) guarded proxy capture for a version (#4747, PMR-2.4).

Capture lets the hosted mock forward a request to a real upstream and record the exchange as a reviewable fixture candidate. Three things gate it, and this endpoint is where two of them are set:

• Explicit owner authorization. The caller must own the mock (version creator or tenant administrator) and must set acknowledged — an affirmative statement that they are permitted to record traffic from these upstreams. The authorization block recording who they were, when, and when the grant lapses is stamped by the server; it is never accepted from the client, and it is clamped to at most MAX_AUTHORIZATION_HOURS. Capture stops on its own when the grant expires.
• An upstream allowlist. upstreams is the complete set of base URLs capture may ever fetch. A request whose path does not fall under one of them is refused rather than proxied, which is what keeps capture from becoming an SSRF pivot.

The third gate — address-level SSRF policy, public addresses only, re-checked on every redirect hop — is enforced by the runtime at fetch time and cannot be configured away here.

redaction adds rules on top of the always-on credential rules; it can never subtract from them. Sending enabled: false keeps the allowlist but stops recording.

Operation id: set_version_mock_capture_policy_v1_versions__tenant_slug___project_id___version_record_id__mock_capture_policy_put

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Request body (required)

Request body for set version mock capture policy.

• application/json — VersionMockCapturePolicyRequest

Responses

Status	Description	Body
200	Successful response for set version mock capture policy.	application/json VersionMockCapturePolicyResponse
422	Validation Error	application/json HTTPValidationError

DELETE /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/mock/capture-policy

Delete Version Mock Capture Policy

Revoke guarded proxy capture entirely (#4747, PMR-2.4).

Removes the policy — allowlist, authorization, redaction rules — so nothing can be recorded until a new grant is made. Already-recorded exchanges are deliberately left alone: revoking permission to record must not destroy the evidence of what was recorded. Discard those explicitly with DELETE .../mock/captures.

Operation id: delete_version_mock_capture_policy_v1_versions__tenant_slug___project_id___version_record_id__mock_capture_policy_delete

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Responses

Status	Description	Body
200	Successful response for delete version mock capture policy.	application/json VersionMockCapturePolicyResponse
422	Validation Error	application/json HTTPValidationError

GET /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/mock/captures

List Version Mock Captures

List the exchanges guarded capture has recorded for this version (#4747, PMR-2.4).

This is the review queue. Every entry is already redacted — the runtime never stores anything else — and carries the full list of redaction decisions plus the provenance of the fetch, so a reviewer can see what was removed and where the data came from before approving anything.

Operation id: list_version_mock_captures_v1_versions__tenant_slug___project_id___version_record_id__mock_captures_get

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
state	query	enum "pending", "approved", "rejected", "published" or null	no	Filter by review state.
limit	query	integer	no	Maximum captures to return.
offset	query	integer	no	Captures to skip, for paging.
includeExchange	query	boolean	no	Include each capture's full redacted document, not only its summary.
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Responses

Status	Description	Body
200	Successful response for list version mock captures.	application/json VersionMockCapturesResponse
422	Validation Error	application/json HTTPValidationError

DELETE /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/mock/captures

Delete Version Mock Captures

Discard recorded exchanges (#4747, PMR-2.4).

Recorded traffic is the one thing here that should never accumulate: this removes it outright rather than flagging it. Captures also expire on their own; this is the manual path for an owner who wants them gone now.

Operation id: delete_version_mock_captures_v1_versions__tenant_slug___project_id___version_record_id__mock_captures_delete

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
state	query	enum "pending", "approved", "rejected", "published" or null	no	Discard only captures in this review state.
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Responses

Status	Description	Body
200	Successful response for delete version mock captures.	application/json object
422	Validation Error	application/json HTTPValidationError

POST /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/mock/captures/publish

Publish Version Mock Captures

Convert approved captures into a fixture pack (#4747, PMR-2.4).

The publish half of "review before publish": only captures an owner has explicitly approved are converted, and the resulting pack is stamped with a provenance block naming the upstreams it drew from, how many captures went into it, and how many redactions were applied. That block is what the runtime reports back on every pack listing and session reset, so a fixture replayed months later still says where it came from.

Successful JSON responses whose operation identifies a CRUD collection become session seed resources; everything else becomes named template fixture data. Anything that could not be converted is reported in notes rather than dropped silently. Publishing to an existing pack name replaces that pack.

Operation id: publish_version_mock_captures_v1_versions__tenant_slug___project_id___version_record_id__mock_captures_publish_post

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Request body (required)

Request body for publish version mock captures.

• application/json — VersionMockCapturePublishRequest

Responses

Status	Description	Body
200	Successful response for publish version mock captures.	application/json VersionMockCapturePublishResponse
422	Validation Error	application/json HTTPValidationError

POST /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/mock/captures/review

Review Version Mock Captures

Approve or reject recorded exchanges (#4747, PMR-2.4).

Nothing a capture recorded reaches a fixture pack without passing through here first. A capture already published is never re-decided: the pack that carries its provenance would otherwise be left claiming a source that disowns it.

Operation id: review_version_mock_captures_v1_versions__tenant_slug___project_id___version_record_id__mock_captures_review_post

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Request body (required)

Request body for review version mock captures.

• application/json — VersionMockCaptureReviewRequest

Responses

Status	Description	Body
200	Successful response for review version mock captures.	application/json VersionMockCaptureReviewResponse
422	Validation Error	application/json HTTPValidationError

GET /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/mock/correlation

Get Version Mock Correlation

Return the version's mock response-correlation settings (#5527, MSC-1.1).

Operation id: get_version_mock_correlation_v1_versions__tenant_slug___project_id___version_record_id__mock_correlation_get

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Responses

Status	Description	Body
200	Successful response for get version mock correlation.	application/json VersionMockCorrelationResponse
422	Validation Error	application/json HTTPValidationError

PUT /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/mock/correlation

Set Version Mock Correlation

Replace the version's mock response-correlation settings (#5527, MSC-1.1).

Correlation is what makes the default response path answer GET /pets/42 with an id of 42 — with no request header, so a generated SDK or a browser app gets it too. The block is validated against this version's generated OpenAPI document (every operation key must name a real operation) and against the bounded template language (every explicit expression must parse), then stored canonically in versions.mock_settings under responseCorrelation, alongside the other mock knobs, and travels inside portable mock bundles.

Omitting correlation (or sending null, or a block with mode: "off") clears the stored block and reverts the version to today's static behaviour.

With ?dryRun=true nothing is written: the same validation runs and the response describes what would be stored (#5530, MSC-1.4).

Operation id: set_version_mock_correlation_v1_versions__tenant_slug___project_id___version_record_id__mock_correlation_put

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
dryRun	query	boolean	no	Validate and report what would be stored, without writing anything.
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Request body (required)

Request body for set version mock correlation.

• application/json — VersionMockCorrelationRequest

Responses

Status	Description	Body
200	Successful response for set version mock correlation.	application/json VersionMockCorrelationResponse
422	Validation Error	application/json HTTPValidationError

GET /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/mock/fixture-packs

Get Version Mock Fixture Packs

Return the version's mock fixture packs and their content digests (#4745, PMR-2.2).

Operation id: get_version_mock_fixture_packs_v1_versions__tenant_slug___project_id___version_record_id__mock_fixture_packs_get

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Responses

Status	Description	Body
200	Successful response for get version mock fixture packs.	application/json VersionMockFixturePacksResponse
422	Validation Error	application/json HTTPValidationError

PUT /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/mock/fixture-packs

Set Version Mock Fixture Packs

Replace the version's mock fixture packs (#4745, PMR-2.2).

Packs are validated against the versioned fixture pack schema (format id and version, name shapes, collection path/resource rules, size caps) and stored canonically in versions.mock_settings under fixturePacks, alongside the other mock knobs. The response echoes each pack's content digest — the identity a test asserts when it resets a session to the pack. An empty packs map clears them.

With ?dryRun=true nothing is written: the same validation runs and the response describes what would be stored (#5530, MSC-1.4).

Operation id: set_version_mock_fixture_packs_v1_versions__tenant_slug___project_id___version_record_id__mock_fixture_packs_put

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
dryRun	query	boolean	no	Validate and report what would be stored, without writing anything.
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Request body (required)

Request body for set version mock fixture packs.

• application/json — VersionMockFixturePacksRequest

Responses

Status	Description	Body
200	Successful response for set version mock fixture packs.	application/json VersionMockFixturePacksResponse
422	Validation Error	application/json HTTPValidationError

GET /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/mock/operations

Get Version Mock Operations

Return the mock-authoring catalogue for this version (#5529, MSC-1.3).

The editor that configures response correlation needs three things the stored settings do not contain: the operations this version actually has (with their path, query and header parameters, so an author picks a token instead of memorizing the grammar), the JSON Pointers a binding can target, and — the part that makes inference trustworthy — which properties the path-params and inferred passes would bind, and to what, before anything is saved.

Those bindings are projected over the response schema with the very name-matching rules the runtime applies to a response body (:mod:app.mock_correlation_rules, imported by :mod:apiome_mock.correlation), so the preview cannot promise a binding the mock declines to make. Two limits follow from working on a schema instead of a body and are reported rather than hidden: a pointer inside an array names member 0 and is flagged repeated (the runtime binds every member), and a oneOf/anyOf schema is projected through its first branch.

Read-only and cheap: it generates the version's OpenAPI document and walks it. Nothing about mock serving is involved, so it answers for a version whose mock is switched off — which is exactly when correlation is being configured for the first time.

Args: tenant_slug: The tenant slug. project_id: The project ID that must own the version. version_record_id: The version record ID (UUID) to describe. auth_data: Authentication context; requires versions:view.

Returns: The operations catalogue and the fixture names templates can read on this version.

Raises: HTTPException: 404 when the version does not exist in the project.

Operation id: get_version_mock_operations_v1_versions__tenant_slug___project_id___version_record_id__mock_operations_get

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Responses

Status	Description	Body
200	Successful response for get version mock operations.	application/json VersionMockOperationsResponse
422	Validation Error	application/json HTTPValidationError

POST /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/mock/preview

Preview Version Mock

Render one synthetic request against this version's mock, without sending it (#5528, MSC-1.2).

Answers the question an author actually has — what comes back? — with no mock enabled, no instance provisioned, and no live request. The response carries the status, headers, media type and body the mock would serve, plus a decision trace naming which layer produced the body: a scenario (and which rule), session-scoped CRUD, correlation (and which pointers), or a declared example versus schema synthesis.

The render happens in apiome-mock, through the very function its data plane calls, so a preview cannot disagree with the served response. This route builds the version's portable mock bundle — the same document the bundle export produces — and asks the runtime to render it. Two consequences worth knowing: the preview reflects the bundled settings keys (scenarios, chaos, fixture packs, callbacks, correlation), and it works on a version whose mock is disabled, because nothing about serving access is involved.

Nothing is written. Session state lives and dies inside the render, no callback is delivered, no usage or provisioning row is touched, and an unsaved settings override leaves the stored settings exactly as they were. Chaos is reported rather than applied: a preview that slept for a configured latency, or that randomly answered 500, would be answering a different question.

Args: tenant_slug: The tenant slug. project_id: The project ID that must own the version. version_record_id: The version record ID (UUID) to preview. request: The synthetic request and, optionally, an unsaved settings override. auth_data: Authentication context; requires versions:view, and versions:edit when a settings override is supplied.

Returns: The rendered response and its decision trace.

Raises: HTTPException: 404 when the version does not exist in the project; 413 when the synthetic body is too large; 422 when a draft override fails the same validation its save route applies, or the runtime rejects the request; 429 when the per-version preview rate limit is exhausted; 502 when the mock runtime cannot be reached; 503 when preview is not configured on this deployment.

Operation id: preview_version_mock_v1_versions__tenant_slug___project_id___version_record_id__mock_preview_post

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Request body (required)

Request body for preview version mock.

• application/json — VersionMockPreviewRequest

Responses

Status	Description	Body
200	Successful response for preview version mock.	application/json VersionMockPreviewResponse
422	Validation Error	application/json HTTPValidationError

GET /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/mock/scenarios

Get Version Mock Scenarios

Return the version's mock scenario definitions (#4454 SIM-4.2).

Operation id: get_version_mock_scenarios_v1_versions__tenant_slug___project_id___version_record_id__mock_scenarios_get

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Responses

Status	Description	Body
200	Successful response for get version mock scenarios.	application/json VersionMockScenariosResponse
422	Validation Error	application/json HTTPValidationError

PUT /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/mock/scenarios

Set Version Mock Scenarios

Replace the version's mock scenario definitions (#4454 SIM-4.2).

Canned responses are validated against the version's generated OpenAPI document (operation exists, status defined, media type declared, body matches the response schema); a response may opt out with offSpec. Definitions persist in versions.mock_settings alongside other mock knobs and survive publish/republish and mock toggles.

The request also carries the version-level latency/chaos knobs (#4455 SIM-4.3): chaos replaces the stored block, and omitting it (or sending null) clears the stored block.

activeScenario (#5531, MSC-2.1) names the scenario the hosted mock serves when a request sends no X-Mock-Scenario header; it must name one of the scenarios in this same request. Unlike the other two keys it is preserved when the field is omitted and cleared only when it is sent as null — an editor written before the field existed keeps sending {scenarios, chaos}, and a save from it must not silently switch a version's mock back to its default flow.

With ?dryRun=true nothing is written: the same validation runs and the response describes what would be stored (#5530, MSC-1.4).

Operation id: set_version_mock_scenarios_v1_versions__tenant_slug___project_id___version_record_id__mock_scenarios_put

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
dryRun	query	boolean	no	Validate and report what would be stored, without writing anything.
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Request body (required)

Request body for set version mock scenarios.

• application/json — VersionMockScenariosRequest

Responses

Status	Description	Body
200	Successful response for set version mock scenarios.	application/json VersionMockScenariosResponse
422	Validation Error	application/json HTTPValidationError

GET /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/preservation

Get Preservation Envelope

Return the revision's live preservation envelope and semantic fingerprint.

Operation id: get_preservation_envelope_v1_versions__tenant_slug___project_id___version_record_id__preservation_get

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Responses

Status	Description	Body
200	Successful response for get preservation envelope.	application/json PreservationEnvelopeResponse
422	Validation Error	application/json HTTPValidationError

PUT /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/preservation

Put Preservation Envelope

Validate and replace a draft revision's preservation envelope.

Responses: * 200 — envelope stored; body echoes the live envelope + fingerprint. * 404 — revision not in the caller's tenant/project scope. * 409 — revision is published (immutable); nothing mutated. * 422 — structured validation errors; nothing mutated.

Operation id: put_preservation_envelope_v1_versions__tenant_slug___project_id___version_record_id__preservation_put

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Request body (required)

Request body for put preservation envelope.

• application/json — PreservationEnvelopePutRequest

Responses

Status	Description	Body
200	Successful response for put preservation envelope.	application/json PreservationEnvelopeResponse
422	Validation Error	application/json HTTPValidationError

POST /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/publish

Publish Version

Publish a version.

Only the version creator or a tenant administrator can publish a version. Published versions are frozen and cannot be modified.

Args: tenant_slug: The tenant slug project_id: The project ID version_record_id: The version record ID request: Optional publish options (visibility) auth_data: Authentication data (injected by dependency)

Returns: The published version

Operation id: publish_version_v1_versions__tenant_slug___project_id___version_record_id__publish_post

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Request body (optional)

Request body for publish version.

• application/json — VersionPublishRequest

Responses

Status	Description	Body
200	Successful response for publish version.	application/json VersionSchema
422	Validation Error	application/json HTTPValidationError

POST /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/source-apply

Apply Source Changes

Apply a reviewed candidate once, in a single transaction.

Operation id: apply_source_changes_v1_versions__tenant_slug___project_id___version_record_id__source_apply_post

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Request body (required)

Request body for apply source changes.

• application/json — SourceApplyRequest

Responses

Status	Description	Body
200	Successful response for apply source changes.	application/json SourceApplyResponse
422	Validation Error	application/json HTTPValidationError

POST /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/source-review

Review Source Changes

Classify a candidate source text against the revision. Never mutates.

Operation id: review_source_changes_v1_versions__tenant_slug___project_id___version_record_id__source_review_post

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Request body (required)

Request body for review source changes.

• application/json — SourceReviewRequest

Responses

Status	Description	Body
200	Successful response for review source changes.	application/json SourceReviewResponse
422	Validation Error	application/json HTTPValidationError

POST /v1/versions/{tenant_slug}/{project_id}/{version_record_id}/unpublish

Unpublish Version

Unpublish a version.

Only the version creator or a tenant administrator can unpublish a version.

Args: tenant_slug: The tenant slug project_id: The project ID version_record_id: The version record ID auth_data: Authentication data (injected by dependency)

Returns: The unpublished version

Operation id: unpublish_version_v1_versions__tenant_slug___project_id___version_record_id__unpublish_post

Parameters

Name	In	Type	Required	Description
tenant_slug	path	string	yes	URL-safe tenant slug that scopes the request.
project_id	path	string	yes	Project identifier that scopes the request.
version_record_id	path	string	yes	Version row identifier (versions.id UUID).
authorization	header	string or null	no	JWT bearer token for authenticated access (Authorization: Bearer <token>).
X-API-Key	header	string or null	no	Tenant-scoped API key used as an alternative to JWT bearer authentication.

Responses

Status	Description	Body
200	Successful response for unpublish version.	application/json VersionSchema
422	Validation Error	application/json HTTPValidationError

Schemas used

BreakingPublishGuardrailOut

Breaking-publish guardrail assessment for a candidate publish (CTG-3.4, #4478).

Shared verbatim by the preflight endpoint, the blocked-publish 422 body, and the audit trail, so the dialog, the API error, and the audit row can never disagree.

Property	Type	Required	Description
policy	string	yes	Resolved guardrail level: off | warn | block.
status	string	yes	disabled | no-baseline | ok | warning | blocked | unavailable.
triggered	boolean	yes	The guardrail has a warning or a block to report.
blocked	boolean	yes	Publish is refused unless force-published.
breaking	boolean	yes	Head classifies breaking against the baseline.
majorBumped	boolean or null	no	Null when a version label is not semver (unknown, never assumed).
fromVersion	string or null	no	From Version.
toVersion	string or null	no	To Version.
baselineRevisionId	string or null	no	Baseline Revision ID.
breakingChanges	array of BreakingPublishChangeOut	no	Breaking Changes.
breakingCount	integer	no	Number of breaking.
truncated	boolean	no	Listed changes omit some of breakingCount.
counts	map of integer	no	Counts.
maxSeverity	string or null	no	Max Severity.
recommendedVersion	string or null	no	Recommended Version.
detail	string or null	no	Detail.
message	string	yes	Message.

HTTPValidationError

Validation error response emitted when request data fails schema checks.

Property	Type	Required	Description
detail	array of ValidationError	no	Detail.

MergeSessionStatusPatchRequest

Update merge session lifecycle state (#2573).

Property	Type	Required	Description
status	enum "resolving", "applied", "aborted"	yes	Target status: resolving, applied, or aborted (from preview/resolving only).

PreservationEnvelopePutRequest

Replace a draft revision's preservation envelope.

Property	Type	Required	Description
dialect	string	yes	OAS dialect the claims target (e.g. 3.1.0).
claims	array of PreservationClaimBody	no	The full new set of claims (empty clears).

PreservationEnvelopeResponse

A revision's live preservation envelope plus its semantic fingerprint.

Property	Type	Required	Description
envelopeVersion	string	yes	Envelope payload contract version.
dialect	string	yes	OAS dialect the claims were validated under.
claims	array of PreservationClaimBody	yes	Claims.
fingerprint	SemanticFingerprint	yes	Semantic fingerprint of the merged (canonical + preserved) document, reporting the intentionally excluded lexical differences.

SourceApplyRequest

Apply a reviewed candidate under optimistic concurrency.

Property	Type	Required	Description
sourceText	string	yes	The full candidate source text.
sourceFormat	enum "yaml", "json"	no	Serialization of source_text.
baseDigest	string	yes	The baseDigest the review endpoint returned; the apply is rejected as stale when the revision no longer fingerprints to it.
changeSetDigest	string	yes	The changeSetDigest the review endpoint returned for this candidate against that base.

SourceApplyResponse

Apply outcome: exactly one revision mutation, or an idempotent no-op.

Property	Type	Required	Description
applied	boolean	yes	Applied.
alreadyApplied	boolean	no	Already Applied.
noChanges	boolean	no	No Changes.
resultDigest	string	yes	Result Digest.
auditId	string or null	no	Audit ID.
counts	SourceChangeCounts or null	no	Counts.
enrichments	array of string	no	Pointers the generator deterministically added during the apply (reported, never silent).
claimCount	integer	no	Preservation claims live after the apply.

SourceReviewRequest

A candidate source text to classify against the revision.

Property	Type	Required	Description
sourceText	string	yes	The full candidate source text.
sourceFormat	enum "yaml", "json"	no	Serialization of source_text.

SourceReviewResponse

Review outcome: the classified change set, nothing mutated.

Property	Type	Required	Description
dialect	string	yes	Dialect.
changeSet	SourceChangeSetBody	yes	Change Set.

SunsetTimelineResponse

Aggregated sunset / deprecation timeline for accessible projects (#508).

Property	Type	Required	Description
entries	array of SunsetTimelineEntryOut	no	Entries.

VersionBranchCreateRequest

Create a named branch whose tip is an existing revision.

Property	Type	Required	Description
name	string	yes	Branch name; unique per project.
fromVersionId	string	yes	Existing revision (version row id) to use as the branch tip.

VersionBranchDivergenceResponse

Branch-vs-branch divergence metrics and commit samples (#2721).

Property	Type	Required	Description
branch	VersionBranchDivergenceBranchOut	yes	Branch.
against	VersionBranchDivergenceBranchOut	yes	Against.
mergeBase	VersionBranchDivergenceMergeBaseOut or null	no	Merge Base.
ahead	integer	yes	Ahead.
behind	integer	yes	Behind.
aheadSample	array of VersionBranchDivergenceSampleOut	no	Ahead Sample.
behindSample	array of VersionBranchDivergenceSampleOut	no	Behind Sample.

VersionBranchFromRevisionRequest

Create a named branch whose tip is an existing revision (in-project; #2570).

Property	Type	Required	Description
sourceRevisionId	string	yes	Revision (versions.id) to use as the branch tip.
branchName	string	yes	New branch name; unique per project.

VersionBranchFromRevisionResponse

Result of branch-from-revision; idempotentReplay documents safe retries (#2570).

Property	Type	Required	Description
branch	VersionBranchRecordOut	yes	Branch.
tipVersion	VersionSchema	yes	Tip Version.
idempotentReplay	boolean	no	True when the branch already existed with the same tip and lineage (safe retry).

VersionBranchMergePreviewRequest

Dry-run merge preview (three-way schema merge + merge-base).

Property	Type	Required	Description
sourceBranchName	string	yes	Source Branch Name.
targetBranchName	string	yes	Target Branch Name.
includeMergedOpenApi	boolean	no	When true (default), include merged OpenAPI preview when auto-merge is possible and under the size cap; set false to omit large payloads (counts and conflicts unchanged).
persistMergeSession	boolean	no	When true, insert merge_sessions + conflict rows for resumable resolution (#2573).
overridePublishedImmutability	boolean	no	Tenant admin only: preview merge when a branch tip is published immutable (#2586).
overrideReason	string or null	no	Audit text when overriding published immutability (#2586).

VersionBranchMergeRequest

Merge source branch into target: requires baseRevisionId = current target tip (optimistic lock).

Property	Type	Required	Description
sourceBranchName	string	yes	Source Branch Name.
targetBranchName	string	yes	Target Branch Name.
baseRevisionId	string	yes	Base Revision ID.
skipCompatGate	boolean	no	When true, skip optional project compatGateOnMerge check against merge result.
compatGateOverrideReason	string or null	no	Required when skipCompatGate is true and compatGateOnMerge is enabled (#2590).
overridePublishedImmutability	boolean	no	Tenant admin only: merge when a branch tip is published immutable (#2586).
overrideReason	string or null	no	Audit text when overriding published immutability (#2586).

VersionBranchPolicyPatchRequest

Tenant-admin: branch protection and merge-path policy (#504, #2583).

Property	Type	Required	Description
protected	boolean or null	no	Protected.
isDefault	boolean or null	no	Is Default.
requireMergePath	boolean or null	no	Require Merge Path.

VersionBranchRollbackPreviewRequest

Dry-run rollback: compatibility / deprecation signals before apply (#745).

Property	Type	Required	Description
branchName	string	yes	Named branch whose tip is rolled forward with restored content.
targetRevisionId	string	yes	Revision (versions.id) whose class snapshot is restored (must be an ancestor of the branch tip).
overridePublishedImmutability	boolean	no	Tenant admin only: preview rollback when branch tip is published immutable (#2586).
overrideReason	string or null	no	Audit text when overriding published immutability (#2586).

VersionBranchRollbackRequest

Revert-style rollback: new revision whose tree matches target; parent = prior branch tip (#745).

Property	Type	Required	Description
branchName	string	yes	Branch Name.
targetRevisionId	string	yes	Target Revision ID.
baseRevisionId	string	yes	Must equal current branch tip (optimistic concurrency).
skipCompatWarning	boolean	no	When true, apply even if compat analysis is not safe (still blocked if compatGateOnRollback is on).
shortMessage	string or null	no	Short Message.
changelog	string or null	no	Changelog.
reason	string or null	no	Optional audit reason persisted on rollback workflow audit (#2582).
overridePublishedImmutability	boolean	no	Tenant admin only: roll back when branch tip is published immutable (#2586).
overrideReason	string or null	no	Audit text when overriding published immutability (#2586).

VersionCreateRequest

Request model for creating a version.

Property	Type	Required	Description
version_id	string or null	no	Project version identifier or semantic version label, depending on context.
shortMessage	string or null	no	Revision note (commit message analog).
changelog	string or null	no	Changelog.
author	string or null	no	Author.
message	string or null	no	Message.
externalRef	string or null	no	External Ref.
baseRevisionId	string	yes	Revision id the client believes is the current head (optimistic lock; #2566).
branchName	string or null	no	Named branch to advance; required when the project has multiple branches.
source_version_id	string or null	no	Source Version ID.
sourceCommitSha	string or null	no	Repository source commit SHA that triggered this revision (RAR-4.2 refresh provenance); recorded for repository auto-refresh imports.
sourceCommittedAt	string (date-time) or string or null	no	Commit timestamp of source_commit_sha (RAR-4.2 refresh provenance).
bump_strategy	string or null	no	Bump Strategy.
overridePublishedImmutability	boolean	no	Tenant admin only: allow push from an immutable published tip (#2586).
overrideReason	string or null	no	Audit text when overriding published immutability (#2586).

VersionDraftLockAcquireRequest

Optional lease duration for draft lock acquire/renew (#2584).

Property	Type	Required	Description
leaseSeconds	integer or null	no	Lock duration in seconds (default 900).

VersionDraftLockRenewRequest

VersionDraftLockRenewRequest schema.

Property	Type	Required	Description
leaseSeconds	integer or null	no	Lease Seconds.

VersionDraftLockResponse

Active draft edit lock on an unpublished revision (#2584).

Property	Type	Required	Description
versionId	string	yes	Version ID.
ownerUserId	string	yes	Owner User ID.
expiresAt	string (date-time)	yes	Expires At.

VersionDraftLockStatusResponse

Draft lock presence for a revision — used for Studio polling (#2585).

Property	Type	Required	Description
active	boolean	yes	Active.
versionId	string or null	no	Version ID.
ownerUserId	string or null	no	Owner User ID.
expiresAt	string (date-time) or null	no	Expires At.

VersionForkRequest

Fork a schema version line into another project from a source revision (cross-project sandbox).

Property	Type	Required	Description
sourceRevisionId	string	yes	Source version row id (revision) to copy from.
upstreamProjectId	string or null	no	Optional upstream project for merge-back; defaults to the source revision's project.
versionId	string or null	no	Explicit semantic version string for the forked version (e.g. '2.0.0').
shortMessage	string or null	no	Short Message.
changelog	string or null	no	Changelog.
author	string or null	no	Author.
message	string or null	no	Message.
externalRef	string or null	no	External Ref.
bumpStrategy	string or null	no	Auto-versioning strategy when versionId is omitted: 'minor' or 'patch' (default).

VersionMockCallbacksRequest

Replace the version's mock callback definitions (#4746 PMR-2.3).

Property	Type	Required	Description
callbacks	map of MockCallbackSpec	no	Callback definitions keyed by callback name; an empty map clears them.

VersionMockCallbacksResponse

The version's persisted mock callback definitions and their content digests (#4746 PMR-2.3).

Property	Type	Required	Description
callbacks	map of MockCallbackSpec	no	Callback definitions keyed by callback name, in canonical stored form.
digests	map of string	no	sha256:<hex> content digest of each definition — the identity a test pins.

VersionMockCapturePolicyRequest

Grant, change, or switch off guarded proxy capture for a version (#4747 PMR-2.4).

The authorization block is never accepted from the client: the API stamps the authenticated user and clamps the lifetime itself, so "who authorized this" cannot be claimed.

Property	Type	Required	Description
enabled	boolean	no	Switch capture on (the default) or off without losing the allowlist.
upstreams	array of string	no	Absolute http(s) base URLs capture may fetch; at least one is required.
redaction	MockCaptureRedactionSpec or null	no	Extra redaction rules on top of the always-on credential rules.
validateResponses	boolean	no	Check each captured response against the version's declared contract.
ttlHours	integer or null	no	Requested authorization lifetime in hours (clamped to at most 168).
acknowledged	boolean	no	Explicit confirmation that the caller is authorized to record traffic from these upstreams. Capture cannot be granted without it.

VersionMockCapturePolicyResponse

The version's stored capture policy, its digest, and whether capture is live (#4747 PMR-2.4).

Property	Type	Required	Description
policy	MockCapturePolicySpec or null	no	The stored policy, or null when capture was never configured.
digest	string or null	no	sha256:<hex> digest of the policy; recorded on every capture.
state	string	yes	Why capture is or is not live: authorized, unconfigured, disabled, no-upstreams, unauthorized, or expired.
captures	map of integer	no	Live capture counts by review state (pending/approved/rejected/published).

VersionMockCapturePublishRequest

Convert approved captures into a fixture pack (#4747 PMR-2.4).

Property	Type	Required	Description
packName	string	yes	Name of the fixture pack to create or replace.
captureIds	array of string	no	Approved capture ids to publish; empty means every approved capture.
description	string	no	Description stored on the resulting pack.

VersionMockCapturePublishResponse

The fixture pack produced from reviewed captures (#4747 PMR-2.4).

Property	Type	Required	Description
packName	string	yes	The pack that was written.
digest	string	yes	sha256:<hex> digest of the published pack.
published	array of string	no	Capture ids marked published.
notes	array of string	no	What the conversion skipped and why, so nothing is dropped silently.
provenance	MockFixturePackProvenanceSpec	yes	The provenance block stamped on the pack — its origin and redaction totals.

VersionMockCaptureReviewRequest

Approve or reject recorded exchanges (#4747 PMR-2.4).

Property	Type	Required	Description
captureIds	array of string	no	Capture ids to decide.
decision	enum "approve", "reject"	yes	The review decision to record.
note	string or null	no	Optional note stored with the decision.

VersionMockCaptureReviewResponse

The result of a review decision (#4747 PMR-2.4).

Property	Type	Required	Description
reviewed	array of string	no	Capture ids whose review state changed.
counts	map of integer	no	Live capture counts by review state after the decision.

VersionMockCapturesResponse

A version's recorded exchanges awaiting review (#4747 PMR-2.4).

Property	Type	Required	Description
captures	array of MockCaptureSummary	no	Recorded exchanges, newest first.
counts	map of integer	no	Live capture counts by review state.

VersionMockCorrelationRequest

Replace the version's mock response-correlation settings (#5527 MSC-1.1).

Property	Type	Required	Description
correlation	MockResponseCorrelationSpec or null	no	The correlation block; omit or send null to clear it (correlation reverts to off).

VersionMockCorrelationResponse

The version's persisted mock response-correlation settings (#5527 MSC-1.1).

Property	Type	Required	Description
correlation	MockResponseCorrelationSpec or null	no	The stored correlation block; null when the version has none (correlation is off).

VersionMockFixturePacksRequest

Replace the version's mock fixture packs (#4745 PMR-2.2).

Property	Type	Required	Description
packs	map of MockFixturePackSpec	no	Fixture packs keyed by pack name; an empty map clears them.

VersionMockFixturePacksResponse

The version's persisted mock fixture packs and their content digests (#4745 PMR-2.2).

Property	Type	Required	Description
packs	map of MockFixturePackSpec	no	Fixture packs keyed by pack name, in canonical stored form.
digests	map of string	no	sha256:<hex> content digest of each pack — the identity tests pin on reset.

VersionMockOperationsResponse

The mock-authoring catalogue for one version (#5529 MSC-1.3).

What an author needs to configure correlation without hand-writing JSON: the version's own operations and their parameters, the pointers a binding can target, the fixture names templates can read, and — the part a preview exists for — which properties the path-params and inferred passes would bind, computed with the same name-matching rules the runtime applies.

Property	Type	Required	Description
operations	array of MockAuthoringOperationSpec	no	One entry per operation, in document order.
fixtures	array of string	no	Fixture names readable as {{fixture.<name>}} on this version.

VersionMockPreviewRequest

Render one synthetic request against the version's mock (#5528 MSC-1.2).

Property	Type	Required	Description
request	MockPreviewRequestSpec	no	The synthetic request; defaults to GET / when omitted.
settings	MockPreviewSettingsSpec or null	no	An unsaved configuration to render against instead of the stored one. Requires versions:edit; nothing is persisted.

VersionMockPreviewResponse

What the mock would serve for the previewed request, and why (#5528 MSC-1.2).

Property	Type	Required	Description
operation	string or null	no	Matched operation key ("GET /pets/{petId}"); null when nothing matched.
pathParams	map of string	no	Path template parameters routing extracted from the request.
status	integer	yes	The HTTP status the mock would return.
headers	map of string	no	Response headers the mock would return, including the X-Mock-* family.
mediaType	string	no	Negotiated response media type.
body	any	no	The response body, per bodyEncoding.
bodyEncoding	string	no	How body is carried: json, text, base64, or empty.
trace	MockPreviewTrace	yes	Which layer produced the body, and why.
chaos	MockPreviewChaos	no	What chaos the data plane would have applied.
draft	boolean	no	True when an unsaved settings override was rendered instead of the stored settings.

VersionMockScenariosRequest

Replace the version's mock scenario definitions (#4454 SIM-4.2).

Property	Type	Required	Description
scenarios	map of MockScenarioSpecInput	no	Scenario definitions keyed by scenario name; an empty map clears them.
chaos	MockChaosSpec or null	no	Version-level latency/chaos knobs; omit or send null to clear them (#4455 SIM-4.3).
activeScenario	string or null	no	The scenario the mock serves when a request sends no X-Mock-Scenario header (#5531 MSC-2.1). It must name one of the scenarios in this same request. Sending null clears it; omitting the field entirely keeps whatever is stored, so an editor that does not know about it cannot silently drop a version's active scenario.

VersionMockScenariosResponse

The version's persisted mock scenario definitions (#4454 SIM-4.2).

Property	Type	Required	Description
scenarios	map of MockScenarioSpecOutput	no	Scenario definitions keyed by scenario name.
chaos	MockChaosSpec or null	no	Version-level latency/chaos knobs (#4455 SIM-4.3).
activeScenario	string or null	no	The scenario served when a request sends no X-Mock-Scenario header; null when the version has none (#5531 MSC-2.1).

VersionMockToggleRequest

Enable or disable the hosted mock for a version (#4422 SIM-2.1, #4446 SIM-2.5).

Property	Type	Required	Description
enabled	boolean	yes	When true, apiome-mock serves this version (draft mocks are private/key-gated).

VersionPublishRequest

Publish: optional last-minute revision note / changelog applied before freeze.

Property	Type	Required	Description
visibility	string or null	no	Visibility.
shortMessage	string or null	no	Short Message.
changelog	string or null	no	Changelog.
publishedImmutable	boolean or null	no	If true (default), published revision rejects git-like writes unless admin override (#2586).
changeReportBaselineMode	enum "auto", "initial", "manual"	no	How to choose the baseline for the publication change report: auto (prior published ancestor), initial (empty baseline), or manual.
changeReportBaselineRevisionId	string or null	no	Required when changeReportBaselineMode is manual: published revision to diff from.
allowBreaking	boolean or null	no	Allow publishing when backward-compatibility vs the baseline is breaking (#3212).
skipPublishChecks	boolean or null	no	Bypass OpenAPI build, documentation, compatibility, and style-guide gates (emergency only).
forcePublishReason	string or null	no	Required when skipPublishChecks is true — recorded to the audit trail (GOV-2.5).

VersionSchema

Schema revision: shortMessage = commit-style note; changelog = release notes (markdown).

Property	Type	Required	Description
id	string	yes	Stable resource identifier.
project_id	string	yes	Project identifier the resource belongs to.
creator_id	string or null	no	Creator ID.
version_id	string	yes	Project version identifier or semantic version label, depending on context.
shortMessage	string or null	no	Human-readable revision note (stored as description in DB).
changelog	string or null	no	Markdown changelog / release notes (stored as change_log in DB).
author	string or null	no	Optional commit author string (audit / CI identity; stored as commit_author).
message	string or null	no	Optional full commit message body (stored as commit_message).
externalRef	string or null	no	External work item id or URL (Jira, Linear, etc.).
visibility	string	no	Visibility.
published	boolean	no	Published.
published_at	string (date-time) or string or null	no	Published At timestamp (ISO 8601).
publishedImmutable	boolean	no	When published: if true, git-like writes require tenant-admin override (#2586).
mockEnabled	boolean	no	When true, apiome-mock serves this revision (#4422). Draft mocks require a tenant API key (#4446).
mockPrivate	boolean	no	When true, the mock is key-gated for an unpublished draft (#4446, SIM-2.5).
mockBaseUrl	string or null	no	Stable mock URL when mockEnabled is true (computed by REST).
enabled	boolean	no	Whether the resource is active.
parent_version_id	string or null	no	Parent Version ID.
merge_parent_version_id	string or null	no	Merge Parent Version ID.
sourceCommitSha	string or null	no	Repository source commit SHA that triggered this revision (RAR-4.2 refresh provenance); NULL for hand-authored revisions.
sourceCommittedAt	string (date-time) or string or null	no	Commit timestamp of source_commit_sha (RAR-4.2 refresh provenance).
forkedFromRevisionId	string or null	no	Source revision (versions.id) if this row is a fork.
upstreamProjectId	string or null	no	Upstream project for merge/sync (optional).
forkSourceVersionLabel	string or null	no	Fork Source Version Label.
forkSourceProjectName	string or null	no	Fork Source Project Name.
upstreamProjectName	string or null	no	Upstream Project Name.
revisionLocked	boolean	no	Tenant-admin lock: revision cannot be soft-deleted by non-admins.
metadata	object or null	no	Revision-level JSON (deprecation, sunset, successor revision id, lifecycle tag, etc.).
lifecycle	string	no	Governance lifecycle tag: stable | beta | deprecated | archived (#739); aligns with metadata.lifecycle and #507 deprecation when unset.
qualityScore	integer or null	no	Stored 0-100 quality score for this revision (#5259); null when the revision has not been linted yet. Open GET .../lint to compute and store it.
qualityGrade	string or null	no	Stored A-F grade matching qualityScore; null when unscored.
creator_name	string or null	no	Creator Name.
creator_email	string or null	no	Creator Email.
project_name	string or null	no	Project Name.
project_slug	string or null	no	Project Slug.
created_at	string (date-time) or string or null	no	Creation timestamp (ISO 8601).
updated_at	string (date-time) or string or null	no	Last update timestamp (ISO 8601).

VersionUpdateRequest

Request model for updating a version.

Property	Type	Required	Description
shortMessage	string or null	no	Short Message.
changelog	string or null	no	Changelog.
enabled	boolean or null	no	Whether the resource is active.
revisionLocked	boolean or null	no	Tenant admins only: lock revision against deletion.
metadata	object or null	no	Shallow-merge into versions.metadata (deprecation fields, lifecycle tag #739, etc.).