Cernion Cookbook API

openapi: 3.2.0
info:
  title: Cernion Energy Tools Cookbook API
  version: 0.99.22
  description: 'MicroService Agent System for Energy Markets - REST API with AI integration.


    CERNION_TOKEN: request at https://cernion.de/ or by email: dev@stromdao.com.


    For the public instance at https://api.cernion.de/, create your token at https://cernion.de/cet-token/.'
servers:
- url: https://api.cernion.de
  description: API Server
tags:
- name: Cookbook
  description: Reusable API workflow recipes (v0.20.5). Code-managed community cookbook with semantic lookup, runtime relation graph, and periodic validity checks against live microservice actions.
paths:
  /api/cookbook:
    get:
      summary: List cookbook recipes
      tags:
      - Cookbook
      operationId: cookbook_list
      parameters:
      - name: domain
        in: query
        required: false
        schema:
          type: string
          example: grid-operations
        description: Filter by recipe domain (exact, case-insensitive).
      - name: tag
        in: query
        required: false
        schema:
          type: string
          example: mastr
        description: Filter by tag (case-insensitive, any-of match).
      - name: status
        in: query
        required: false
        schema:
          type: string
          enum:
          - valid
          - degraded
          - broken
          - deprecated
          example: valid
        description: Filter by runtime validation status.
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
      description: Returns all cookbook recipes with runtime metadata (status, relatedRecipes, validation timestamps).
  /api/cookbook/:id:
    get:
      summary: Get a single cookbook recipe
      tags:
      - Cookbook
      operationId: cookbook_get
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          example: vnb-assets-from-name
        description: Unique recipe identifier.
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
      description: Returns one recipe by id including validation status and related recipes.
  /api/cookbook/search:
    post:
      summary: Semantic recipe lookup
      tags:
      - Cookbook
      operationId: cookbook_search
      parameters:
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
      description: Finds best-matching cookbook recipes for a free-text implementation problem using Gemini embeddings with keyword fallback.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
              - query
              properties:
                query:
                  type: string
                  minLength: 5
                  example: How do I look up a grid operator and list its MaStR assets?
                limit:
                  type: integer
                  minimum: 1
                  maximum: 20
                  default: 5
                includeBroken:
                  type: boolean
                  default: false
                token:
                  type: string
                  description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
            examples:
              vnbLookup:
                summary: Find recipes for grid operator asset lookup
                value:
                  query: How do I find assets for a named grid operator?
              validationAgent:
                summary: Find a validation agent workflow
                value:
                  query: redispatch settlement audit risk assessment
                  includeBroken: true
  /api/cookbook/validate:
    post:
      summary: Force cookbook validity check
      tags:
      - Cookbook
      operationId: cookbook_validate
      parameters:
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
      description: Re-validates all recipes against the live action registry and refreshes runtime statuses.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                token:
                  type: string
                  description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
            examples:
              default:
                summary: Trigger a forced re-validation
                value: {}
  /api/cookbook/health:
    get:
      summary: Cookbook service health
      tags:
      - Cookbook
      operationId: cookbook_health
      parameters:
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
      description: Returns recipe counts and latest validation timestamp.
  /api/cookbook/services:
    get:
      summary: Live service/action catalogue for recipe generator UI
      tags:
      - Cookbook
      operationId: cookbook_serviceCatalogue
      parameters:
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
      description: Returns all REST-exposed actions from the live Moleculer registry.
components:
  parameters:
    TokenQuery:
      name: token
      in: query
      required: false
      schema:
        type: string
      description: Optional Cernion MCP token as URL query parameter. If provided, it overrides CERNION_TOKEN for this request. Prefer Authorization Bearer header in production to reduce token exposure in URLs/logs.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Optional Cernion MCP token. If not provided, falls back to CERNION_TOKEN from environment. Request token at https://cernion.de/ or by email: dev@stromdao.com.'