Apicurio AI API

openapi: 3.1.0
info:
  title: Apicurio Registry Admin AI API
  version: 3.1.x
  description: Apicurio Registry is a high-performance, runtime registry for schemas and API designs. It stores and manages OpenAPI, AsyncAPI, Avro, JSON Schema, Protobuf, and other artifact types, providing a REST API for schema management with compatibility checking and content versioning.
  contact:
    name: Apicurio
    url: https://www.apicur.io/
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: http://localhost:8080/apis/registry/v3
  description: Local Apicurio Registry
tags:
- name: AI
paths:
  /groups/{groupId}/artifacts/{artifactId}/versions/{versionExpression}/render:
    summary: Render a prompt template artifact by substituting variables.
    parameters:
    - name: groupId
      description: The artifact group ID.  Must be a string provided by the client, representing the name of the grouping of artifacts. Must follow the ".{1,512}" pattern.
      schema:
        $ref: '#/components/schemas/GroupId'
      in: path
      required: true
    - name: artifactId
      description: The artifact ID.  Can be a string (client-provided) or UUID (server-generated), representing the unique artifact identifier. Must follow the ".{1,512}" pattern.
      schema:
        $ref: '#/components/schemas/ArtifactId'
      in: path
      required: true
    - name: versionExpression
      description: "An expression resolvable to a specific version ID within the given group and artifact. The following rules apply:\n\n - If the expression is in the form \"branch={branchId}\", and artifact branch {branchId} exists: The expression is resolved to a version that the branch points to.\n - Otherwise: The expression is resolved to a version with the same ID, which must follow the \"[a-zA-Z0-9._\\\\-+]{1,256}\" pattern."
      schema:
        type: string
      in: path
      required: true
    post:
      tags:
      - AI
      requestBody:
        description: The variables to use for rendering the prompt template.
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RenderPromptRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RenderPromptResponse'
          description: The rendered prompt template.
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
      operationId: renderPromptTemplate
      summary: Render a prompt template
      description: 'Renders a prompt template artifact by substituting the provided variables into the template.

        The artifact must be of type `PROMPT_TEMPLATE`. Variables are validated against the template''s

        variable schema before rendering.


        This operation can fail for the following reasons:


        * No artifact with this `artifactId` exists (HTTP error `404`)

        * No version with this `version` exists (HTTP error `404`)

        * The artifact is not a PROMPT_TEMPLATE (HTTP error `400`)

        * Required variables are missing or have invalid types (HTTP error `400`)

        * A server error occurred (HTTP error `500`)

        '
components:
  responses:
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            UnauthorizedExample:
              value:
                detail: 'UnauthorizedException: User is not authenticated.'
                title: User is not authenticated.
                status: 401
                name: UnauthorizedException
      description: Common response for all operations that can return a `401` error indicating authentication is required.
    ServerError:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            ErrorExample:
              value:
                error_code: 500
                message: Lost connection to the database.
      description: Common response for all operations that can fail with an unexpected server error.
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
      description: Common response for all operations that can return a `400` error.
    NotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            NotFoundExample:
              value:
                error_code: 404
                message: No artifact with id 'Topic-1/Inbound' could be found.
      description: Common response for all operations that can return a `404` error.
    Forbidden:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            ForbiddenExample:
              value:
                detail: 'ForbiddenException: User is not authorized to perform this operation.'
                title: User is not authorized to perform this operation.
                status: 403
                name: ForbiddenException
      description: Common response for all operations that can return a `403` error indicating the user is authenticated but not authorized.
  schemas:
    GroupId:
      description: An ID of a single artifact group.
      pattern: ^.{1,512}$
      type: string
      example: '"my-group"'
    ProblemDetails:
      title: Root Type for Error
      description: 'All error responses, whether `4xx` or `5xx` will include one of these as the response

        body.'
      required:
      - title
      - status
      type: object
      properties:
        detail:
          description: A human-readable explanation specific to this occurrence of the problem.
          type: string
        type:
          description: A URI reference [RFC3986] that identifies the problem type.
          type: string
        title:
          description: A short, human-readable summary of the problem type.
          type: string
        status:
          format: int32
          description: The HTTP status code.
          type: integer
        instance:
          description: A URI reference that identifies the specific occurrence of the problem.
          type: string
        name:
          description: The name of the error (typically a server exception class name).
          type: string
      example:
        status: 500
        name: NullPointerException
        title: An error occurred somewhere.
    RenderPromptResponse:
      title: Root Type for RenderPromptResponse
      description: Response from rendering a prompt template.
      required:
      - rendered
      type: object
      properties:
        rendered:
          description: The rendered prompt with all variables substituted.
          type: string
        groupId:
          description: The group ID of the artifact.
          type: string
        artifactId:
          description: The artifact ID.
          type: string
        version:
          description: The version of the artifact that was rendered.
          type: string
        validationErrors:
          description: Any validation errors encountered when validating variables against the template schema.
          type: array
          items:
            $ref: '#/components/schemas/RenderValidationError'
      example:
        rendered: 'Style: concise

          Maximum length: 100 words

          Document: The quick brown fox jumps over the lazy dog.'
        groupId: default
        artifactId: summarization-v1
        version: '1.2'
        validationErrors: []
    RenderPromptRequest:
      title: Root Type for RenderPromptRequest
      description: Request body for rendering a prompt template with variable substitution.
      required:
      - variables
      type: object
      properties:
        variables:
          description: A map of variable names to their values. These will be substituted into the prompt template.
          type: object
          additionalProperties: {}
      example:
        variables:
          document: The quick brown fox jumps over the lazy dog.
          max_words: 100
          style: concise
    RenderValidationError:
      title: Root Type for RenderValidationError
      description: A validation error encountered when validating template variables.
      required:
      - variableName
      - message
      type: object
      properties:
        variableName:
          description: The name of the variable that failed validation.
          type: string
        message:
          description: A description of the validation error.
          type: string
        expectedType:
          description: The expected type of the variable.
          type: string
        actualType:
          description: The actual type that was provided.
          type: string
      example:
        variableName: max_words
        message: Expected integer but got string
        expectedType: integer
        actualType: string
    ArtifactId:
      description: The ID of a single artifact.
      pattern: ^.{1,512}$
      type: string
      example: '"example-artifact"'
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://example.com/realms/apicurio/protocol/openid-connect/token
          scopes:
            read: Read access
            write: Write access
            admin: Admin access
x-codegen:
  suppress-date-time-formatting: true
  bean-annotations:
  - io.quarkus.runtime.annotations.RegisterForReflection
  - annotation: lombok.experimental.SuperBuilder
    excludeEnums: true
  - annotation: lombok.AllArgsConstructor
    excludeEnums: true
  - annotation: lombok.NoArgsConstructor
    excludeEnums: true
  - annotation: lombok.EqualsAndHashCode
    excludeEnums: true
  - annotation: lombok.ToString(callSuper = true)
    excludeEnums: true