openapi: 3.1.0
info:
  title: CreatorNode Visual API — Render Chem Reaction
  description: >
    Render chemical reactions (reactants → products) as 2D reaction scheme
    diagrams.


    Outputs base64 SVG (UTF-8) or base64 PNG.
  version: 1.0.0
  contact:
    name: CreatorNode Support
    url: https://creatornode.io/support
  license:
    name: Proprietary
    url: https://creatornode.io/legal
servers:
  - url: https://api.creatornode.io/visual
    description: Production
tags:
  - name: Chemistry
    description: Chemistry rendering endpoints
paths:
  /v1/render-chem-reaction:
    post:
      operationId: renderChemReaction
      tags:
        - Chemistry
      summary: Render a chemical reaction scheme (reactants → products)
      description: >
        Renders a chemical reaction as a 2D scheme (SVG or PNG) using
        smiles-drawer ReactionDrawer.

        Defaults to `responseFormat=json`; use `responseFormat=file` for raw SVG
        or PNG output.
      security:
        - ApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RenderChemReactionRequest"
            examples:
              structured:
                summary: Structured reaction (recommended)
                value:
                  responseFormat: json
                  reaction:
                    reactants:
                      - CCO
                      - O
                    reagents:
                      - "[Na+].[OH-]"
                    products:
                      - CC[O-].[Na+]
                  format: svg
                  theme: light
                  options:
                    width: 900
                    height: 450
              reaction-smiles:
                summary: Reaction SMILES (convenience)
                value:
                  responseFormat: file
                  reactionSmiles: CCO.O>[Na+].[OH-]>CC[O-].[Na+]
                  format: png
                  preset: social-card
      responses:
        "200":
          description: Rendered reaction scheme (`json` by default, or raw SVG/PNG when
            `responseFormat=file`)
          headers:
            X-Processing-Time-Ms:
              description: Processing time in milliseconds
              schema:
                type: integer
            X-Cache-Hit:
              description: Whether result was from cache
              schema:
                type: boolean
            X-Credits-Used:
              description: Credits consumed by this request (present only for paid tiers)
              schema:
                type: integer
                example: 3
            X-Credits-Remaining:
              description: Remaining credits on the API key (present only for paid tiers with
                prepaid credits)
              schema:
                type: integer
            X-Content-Type-Options:
              description: Security header
              schema:
                type: string
                enum:
                  - nosniff
            X-Image-Width:
              description: Output image width in pixels
              schema:
                type: integer
            X-Image-Height:
              description: Output image height in pixels
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RenderChemReactionResponse"
            image/svg+xml:
              schema:
                type: string
                format: binary
            image/png:
              schema:
                type: string
                format: binary
        "400":
          description: Invalid reaction or validation error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Unauthorized
        "429":
          description: Rate limited
        "503":
          description: Service temporarily saturated
          headers:
            Retry-After:
              description: Seconds before retrying the request
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
              example:
                success: false
                error:
                  code: SERVICE_BUSY
                  message: Visual rendering service is temporarily saturated. Retry shortly.
                meta:
                  requestId: abc123
components:
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: APIM subscription key for authentication. Free tier available
        without key.
  schemas:
    RenderChemColors:
      type: object
      description: Custom per-element color overrides (hex format
      properties:
        C:
          type: string
          pattern: ^#[0-9A-Fa-f]{6}$
        O:
          type: string
          pattern: ^#[0-9A-Fa-f]{6}$
        N:
          type: string
          pattern: ^#[0-9A-Fa-f]{6}$
        S:
          type: string
          pattern: ^#[0-9A-Fa-f]{6}$
        F:
          type: string
          pattern: ^#[0-9A-Fa-f]{6}$
        CL:
          type: string
          pattern: ^#[0-9A-Fa-f]{6}$
        BR:
          type: string
          pattern: ^#[0-9A-Fa-f]{6}$
        I:
          type: string
          pattern: ^#[0-9A-Fa-f]{6}$
        P:
          type: string
          pattern: ^#[0-9A-Fa-f]{6}$
        B:
          type: string
          pattern: ^#[0-9A-Fa-f]{6}$
        SI:
          type: string
          pattern: ^#[0-9A-Fa-f]{6}$
        H:
          type: string
          pattern: ^#[0-9A-Fa-f]{6}$
        BACKGROUND:
          type: string
          pattern: ^#[0-9A-Fa-f]{6}$
    RenderChemReactionOptions:
      type: object
      description: Rendering options for reaction schemes (subset of RenderChemOptions)
      properties:
        width:
          type: integer
          minimum: 100
          maximum: 2048
        height:
          type: integer
          minimum: 100
          maximum: 2048
        fit:
          type: string
          enum:
            - contain
            - stretch
        bondThickness:
          type: number
          minimum: 0.3
          maximum: 3
        bondLength:
          type: number
          minimum: 10
          maximum: 50
        bondSpacing:
          type: number
          minimum: 1
          maximum: 10
        atomVisualization:
          type: string
          enum:
            - default
            - balls
            - none
        terminalCarbons:
          type: boolean
        explicitHydrogens:
          type: boolean
        compactDrawing:
          type: boolean
        padding:
          type: number
          minimum: 0
          maximum: 100
        transparent:
          type: boolean
          description: Transparent background (SVG only)
        colors:
          $ref: "#/components/schemas/RenderChemColors"
    RenderChemReactionRequest:
      type: object
      description: |
        Provide exactly one of:
        - `reactionSmiles` (reaction SMILES string)
        - `reaction` (structured parts)
      oneOf:
        - required:
            - reactionSmiles
        - required:
            - reaction
      properties:
        responseFormat:
          type: string
          enum:
            - json
            - file
          default: json
          description: >
            Success response transport.

            - `json` (default): JSON wrapper with render metadata and optional
            recommendations.

            - `file`: raw SVG or PNG body with selected metadata in headers.
        reactionSmiles:
          type: string
          minLength: 1
          maxLength: 20000
          description: Reaction SMILES in the form reactants>reagents>products
          example: CCO.O>[Na+].[OH-]>CC[O-].[Na+]
        reaction:
          $ref: "#/components/schemas/RenderChemReactionStructured"
        format:
          type: string
          enum:
            - svg
            - png
          default: svg
        theme:
          type: string
          enum:
            - light
            - dark
          default: light
        preset:
          type: string
          enum:
            - default
            - publication
            - presentation
            - thumbnail
            - social-card
        options:
          $ref: "#/components/schemas/RenderChemReactionOptions"
    RenderChemReactionResponseMeta:
      type: object
      required:
        - requestId
        - format
        - contentType
        - processingTimeMs
        - sizeBytes
        - cached
        - width
        - height
        - itemCount
        - reactantCount
        - productCount
        - reagentCount
      properties:
        requestId:
          type: string
        format:
          type: string
          enum:
            - svg
            - png
        contentType:
          type: string
          description: MIME type for the produced artifact.
        filename:
          type: string
          description: Suggested filename for file-mode consumers.
        processingTimeMs:
          type: integer
        sizeBytes:
          type: integer
        cached:
          type: boolean
        width:
          type: integer
        height:
          type: integer
        itemCount:
          type: integer
        reactantCount:
          type: integer
        productCount:
          type: integer
        reagentCount:
          type: integer
    RenderChemReactionResponse:
      type: object
      required:
        - success
        - data
        - meta
      properties:
        success:
          type: boolean
          enum:
            - true
        data:
          type: string
          description: Base64-encoded output (SVG UTF-8 or PNG)
        meta:
          $ref: "#/components/schemas/RenderChemReactionResponseMeta"
        recommendations:
          type: array
          items:
            $ref: "#/components/schemas/Recommendation"
    Recommendation:
      type: object
      required:
        - type
        - title
        - message
        - priority
      properties:
        type:
          type: string
          enum:
            - upgrade
            - tip
            - warning
        title:
          type: string
        message:
          type: string
        priority:
          type: string
          enum:
            - high
            - medium
            - low
        url:
          type: string
          format: uri
    ErrorResponse:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          const: false
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Machine-readable error code. See each endpoint for possible values.
            message:
              type: string
            details:
              type: object
              description: Additional context about the error (varies by endpoint).
              additionalProperties: true
        meta:
          type: object
          required:
            - requestId
          properties:
            requestId:
              type: string
            demoMode:
              type: boolean
              description: Whether this is a demo endpoint response
        recommendations:
          type: array
          items:
            $ref: "#/components/schemas/Recommendation"
    RenderChemReactionDemoRequest:
      type: object
      required:
        - reactionSmiles
      properties:
        reactionSmiles:
          type: string
          minLength: 1
          description: |
            Reaction SMILES. The demo endpoint returns pre-built sample output —
            it does not render your exact reaction.
        format:
          type: string
          enum:
            - svg
            - png
          default: svg
    RenderChemReactionDemoResponse:
      allOf:
        - $ref: "#/components/schemas/RenderChemReactionResponse"
        - type: object
          required:
            - demoMode
            - warning
          properties:
            demoMode:
              type: boolean
              enum:
                - true
            warning:
              type: string
    RenderChemReactionStructured:
      type: object
      required:
        - reactants
        - products
      properties:
        reactants:
          type: array
          minItems: 1
          maxItems: 50
          items:
            type: string
            minLength: 1
            maxLength: 5000
        products:
          type: array
          minItems: 1
          maxItems: 50
          items:
            type: string
            minLength: 1
            maxLength: 5000
        reagents:
          type: array
          maxItems: 50
          items:
            type: string
            minLength: 1
            maxLength: 5000
        conditions:
          type: string
          maxLength: 500
          description: Display-only conditions label (may be ignored)