> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pragmatiks.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Register Runtime Version

> Register a new runtime image version.

Called by the ``release-runtime`` CI workflow after building and
pushing a runtime image to the container registry. Creates or
updates the version record in the shared SurrealDB namespace.

Authenticated against the Pragmatiks Console Clerk realm — only a
ConsoleMachine M2M token is accepted. Customer-realm tokens are
rejected at the Clerk SDK layer (wrong JWKS); ConsoleUser session
tokens are rejected with 403 by ``require_console_machine``.

Args:
    body: Runtime version registration payload.
    service: Shared-namespace RuntimeVersionService for persistence.
    machine: Authenticated ConsoleMachine performing the release.

Returns:
    The persisted RuntimeVersion record.



## OpenAPI

````yaml https://api.pragmatiks.io/openapi.json post /console/runtime/versions
openapi: 3.1.0
info:
  title: Pragma API
  version: 0.1.0
servers: []
security: []
paths:
  /console/runtime/versions:
    post:
      tags:
        - console
      summary: Register Runtime Version
      description: |-
        Register a new runtime image version.

        Called by the ``release-runtime`` CI workflow after building and
        pushing a runtime image to the container registry. Creates or
        updates the version record in the shared SurrealDB namespace.

        Authenticated against the Pragmatiks Console Clerk realm — only a
        ConsoleMachine M2M token is accepted. Customer-realm tokens are
        rejected at the Clerk SDK layer (wrong JWKS); ConsoleUser session
        tokens are rejected with 403 by ``require_console_machine``.

        Args:
            body: Runtime version registration payload.
            service: Shared-namespace RuntimeVersionService for persistence.
            machine: Authenticated ConsoleMachine performing the release.

        Returns:
            The persisted RuntimeVersion record.
      operationId: console-register_runtime_version
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RuntimeVersionCreate'
        required: true
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeVersion'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    RuntimeVersionCreate:
      properties:
        version:
          type: string
          title: Version
        image_url:
          type: string
          title: Image Url
        changelog:
          anyOf:
            - type: string
            - type: 'null'
          title: Changelog
      type: object
      required:
        - version
        - image_url
      title: RuntimeVersionCreate
      description: |-
        Request body for registering a new runtime version.

        Attributes:
            version: Semver version string (e.g., ``"0.40.0"``).
            image_url: Full container image URL for this runtime version
                (e.g., ``europe-west4-docker.pkg.dev/...``/``pragma-runtime:0.40.0``).
            changelog: Optional release notes in markdown.
    RuntimeVersion:
      properties:
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
        version:
          type: string
          title: Version
        image_url:
          type: string
          title: Image Url
        released_at:
          type: string
          format: date-time
          title: Released At
        changelog:
          anyOf:
            - type: string
            - type: 'null'
          title: Changelog
      type: object
      required:
        - version
        - image_url
        - released_at
      title: RuntimeVersion
      description: |-
        A tracked runtime image version.

        Identity fields (frozen):
            version: Semver string (e.g., "0.39.0"), used as SurrealDB record ID.

        Metadata:
            image_url: Full container image URL for this runtime version.
            released_at: Timestamp when this version was released.
            changelog: Optional release notes in markdown.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError

````