> ## Documentation Index > Fetch the complete documentation index at: https://docs.usenexio.com/llms.txt > Use this file to discover all available pages before exploring further. # Publish Engine Version > Release the engine's current saved config as a new immutable version, moving the validated change into live traffic. ## OpenAPI ````yaml POST /api/v1/engines/{engine_slug}/versions openapi: 3.1.0 info: title: Nexio API version: '1.0' description: | Nexio agentic infrastructure API. Configure engines for placement, entity analysis, and other patterns. Submit runs, poll for results, or subscribe to signed webhook callbacks. contact: email: support@usenexio.com url: https://docs.usenexio.com servers: - url: https://api.usenexio.com description: Production security: - BearerAuth: [] tags: - name: EngineManagement description: Create, configure, and manage inference engines. - name: Engines description: Engine-scoped endpoints for submitting runs and retrieving results. - name: Runs description: Retrieve and reconcile submitted runs. - name: Catalog description: >- Read current markets and products extracted for the authenticated organization. - name: Environments description: Isolated tenancy scopes under your org (one live plus non-live sandboxes). - name: Webhooks description: Manage webhook endpoints for push-based delivery of terminal run events. - name: Converse description: The raw stateless conversational model turn (caller-owned state). - name: Conversations description: >- Conversation instances (orchestrators over engines) and their managed conversations, turns, annotations, evals, and exports. paths: /api/v1/engines/{engine_slug}/versions: post: tags: - EngineManagement summary: Publish an engine version description: | Release the engine's current saved config as a new immutable version. Unpinned runs execute the latest release, so this is the step that moves a validated config change into traffic: `PUT /config` alone never changes live behavior. The platform mints the version number: a schema comparator diffs the config's declared I/O contract against the latest release and bumps the major on a breaking change, the minor otherwise. A caller-supplied `version` or `is_breaking_from_previous_major` is accepted for compatibility but not consulted: read the authoritative version from the response. Idempotent: re-publishing an unchanged config returns the current latest version with `already_released: true`, never an error. operationId: publishEngineVersion parameters: - $ref: '#/components/parameters/EngineSlug' requestBody: required: false content: application/json: schema: type: object properties: changelog: type: string description: Human-readable summary recorded on the version row. version: type: string description: Accepted for compatibility; the platform mints the version. is_breaking_from_previous_major: type: boolean description: Accepted for compatibility; the schema comparator decides. responses: '200': description: | The released version: freshly minted, or the existing latest release (`already_released: true`) when the saved config is already released. content: application/json: schema: allOf: - $ref: '#/components/schemas/EngineVersion' - type: object properties: already_released: type: boolean description: Present and true on the idempotent no-op. bump: type: string enum: - major - minor description: Comparator verdict for a fresh publish. reasons: type: array items: type: string description: Breaking-change reasons when `bump` is `major`. example: version: '2.0' released_at: '2026-06-11T18:00:00Z' changelog: 'v2 config: cover letter + budget review outputs.' is_breaking_from_previous_major: true gate_verified: true bump: major reasons: - 'output field removed: output.readiness_score' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/EngineNotFound' '409': description: | The engine has no saved config to publish (`engine_config_hash_missing`), or the engine's config was saved again between the eval gate evaluating the candidate and the release being written (`engine_config_changed`). `engine_config_changed` is retryable and is the only publish error whose fix is to retry: publishing again re-runs the gate against the config that is live now. It never means the config was rejected. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: engine_config_hash_missing message: Engine has no live config to publish '422': description: | The live config could not be parsed for schema derivation (`invalid_engine_config`), or the release is blocked by the eval gate (`cold_start_gate_not_met`, `cold_start_gate_failed`, `cold_start_gate_regressed`). The gate applies to every release, not only a first one: the config being published must have a passing eval on the engine's corpus. The `cold_start_` prefix is retained for compatibility with clients that already match on these codes. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: cold_start_gate_not_met message: >- release blocked: the config being released has no passing eval on this engine's corpus; run one against this candidate config hash before publishing '429': $ref: '#/components/responses/RateLimited' components: parameters: EngineSlug: name: engine_slug in: path required: true description: Engine identifier slug (e.g. `default`). schema: type: string schemas: EngineVersion: type: object required: - version - released_at - changelog - is_breaking_from_previous_major - gate_verified properties: version: type: string pattern: ^\d+\.\d+$ description: Two-tier `major.minor` identifier (e.g. `1.0`, `1.3`, `2.0`). released_at: type: string format: date-time description: When the version row was created. changelog: type: string description: Operator-supplied human-readable summary of what changed. request_schema_hash: type: string pattern: ^[0-9a-f]{64}$ description: SHA-256 of the exact canonical released request schema bytes. response_schema_hash: type: string pattern: ^[0-9a-f]{64}$ description: SHA-256 of the exact canonical released response schema bytes. is_breaking_from_previous_major: type: boolean description: | True only when this is a `*.0` row AND a prior major (`(major-1).*`) also exists for the same engine. The first-ever release of an engine reports `false`. published_by: type: string description: | Actor recorded at publish: a dashboard user ID for dashboard publishes, `api_key:` for API publishes. Omitted on backfilled rows with no recorded actor. gate_verified: type: boolean description: Whether the release passed the cold-start trust gate. cold_start_eval_set_id: type: string description: Cold-start evaluation set used by a gate-verified release. Error: type: object required: - code - message properties: code: type: string description: | Stable snake_case error identifier. Safe to match programmatically. Known codes: `invalid_request`, `invalid_input`, `unauthorized`, `auth_unavailable`, `rate_limited`, `missing_run_id`, `invalid_run_id`, `run_not_found`, `invalid_offerings`, `missing_input`, `queue_unreachable`, `engine_not_found`, `engine_slug_conflict`, `engine_archived`, `instance_not_found`, `instance_slug_conflict`, `instance_archived`, `instance_follows_canonical`, `instance_not_published`, `invalid_engine_type`, `validation_error`, `webhook_not_found`, `webhook_limit_exceeded`, `invalid_url`, `invalid_events`, `invalid_description`, `invalid_auth_token`, `missing_endpoint_id`, `invalid_endpoint_id`, `missing_delivery_id`, `invalid_delivery_id`, `delivery_not_found`, `delivery_not_resendable`, `insufficient_capability`, `engine_version_required`, `engine_version_exact_required`, `engine_version_not_found`, `engine_version_invalid_format`, `engine_version_draft_requires_sandbox_key`, `engine_version_none_released`, `test_scenario_sandbox_only`, `test_scenario_forbidden`, `test_scenario_exact_version_required`, `test_scenario_version_not_supported`, `invalid_test_scenario`, `request_bound_exceeded`, and `run_cap_exceeded`. message: type: string description: Human-readable error message. May change between versions. details: description: | Optional request-specific details. Request-bound failures use the `RequestBoundDetails` object. Validation failures may use an array of field issues or another documented object. responses: Unauthorized: description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: unauthorized message: Missing or invalid API key EngineNotFound: description: Engine not found. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: engine_not_found message: Engine not found RateLimited: description: Rate limit exceeded. Retry after the window resets. headers: Retry-After: description: Seconds until the rate limit window resets. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: code: rate_limited message: Rate limit exceeded securitySchemes: BearerAuth: type: http scheme: bearer description: | Send the credential as `Authorization: Bearer `. Scoped partner credentials use the exclusive `nxsk_v1_...` namespace. Each scoped key is bound at issuance to one organization, one canonical named environment, an explicit engine set, and a least-privilege capability set. A malformed, unknown, rotated, or revoked `nxsk_` key fails closed and is never retried as a legacy key. Capabilities used by this API are `runs:write`, `runs:read`, `engines:read`, `catalog:read`, `webhooks:manage`, `runs:defensibility:read`, `runs:test`, `conversations:use`, and `conversations:export`. Operation descriptions name the required capability. Grandfathered `nx_live_...` and `nx_test_...` keys retain their existing broad access during the compatibility window. ````