Cernion

Cernion HITL API

Human-in-the-loop approval workflow with tenant-scoped review items, intervention trail, and lifecycle events.

GitHub OpenAPI

Operations 14

POST /api/hitl/items Create HITL item #
GET /api/hitl/items List HITL items #
GET /api/hitl/summary Summarize HITL queue and workload #
GET /api/hitl/sla-heatmap Get HITL SLA heatmap buckets #
GET /api/hitl/items/:id Get HITL item #
POST /api/hitl/items/:id/approve Approve HITL item #
POST /api/hitl/items/:id/reject Reject HITL item #
POST /api/hitl/items/:id/escalate Escalate HITL item #
POST /api/hitl/items/bulk-approve Approve multiple HITL items #
POST /api/hitl/items/bulk-reject Reject multiple HITL items #
POST /api/hitl/items/bulk-escalate Escalate multiple HITL items #
GET /api/hitl/items/:id/workflow-state Get workflow completion state for HITL item #
POST /api/hitl/items/:id/completion-plausibility Preview pre-completion plausibility hints for a HITL item (read-only, advisory) #
POST /api/hitl/items/:id/mark-completed Mark HITL workflow as completed #

Specifications

⚙
OpenAPI
https://artifacts.apis.io/cernion-de/openapi/cernion-de-hitl-api-openapi.yml

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this
  • find_apisBrowse and filter every API in the catalog.
  • get_api_artifactsOne API's artifacts, grouped by type.
  • get_openapiThe primary OpenAPI for this API.
  • find_similar_apisAPIs that look like this one.
  • apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
  • resolveTurn a domain, URL or GitHub org into the provider it belongs to.
  • find_cohortsEvery scored population of providers in the catalog.
All 92 tools →

Call it yourself

curl for this page
This API 
curl "https://apis.io/api/v1/apis/cernion-de:cernion-de-hitl-api"
All apis 
curl "https://apis.io/api/v1/apis?limit=25"

Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

cernion-de-hitl-api-openapi.yml Raw ↑ 
openapi: 3.2.0
info:
  title: Cernion Energy Tools HITL 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: HITL
  description: Human-in-the-loop approval workflow with tenant-scoped review items, intervention trail, and lifecycle events.
paths:
  /api/hitl/items:
    post:
      summary: Create HITL item
      tags:
      - HITL
      operationId: hitl_create
      parameters:
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - kind
              properties:
                kind:
                  type: string
                  example: cya-consensus-failed
                payload:
                  type: object
                  example:
                    sessionId: S-123
                responsibleRole:
                  type: string
                  example: ROLE_NETZPLANUNG
                requiredResolverRoles:
                  type: array
                  items:
                    type: string
                  example:
                  - ROLE_KAUFMAENNISCHE_LEITUNG
                  - ROLE_NETZPLANUNG
                personaId:
                  type: string
                  example: tenant-a/thorsten-human
                originService:
                  type: string
                  example: cya
                originAction:
                  type: string
                  example: refine
                severity:
                  type: string
                  example: warning
                requiredScope:
                  type: string
                  example: full-access
                dueAt:
                  type: string
                  format: date-time
                  example: '2026-05-12T12:00:00.000Z'
                token:
                  type: string
                  description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
            examples:
              default:
                value:
                  kind: cya-consensus-failed
                  payload:
                    sessionId: S-123
                  responsibleRole: ROLE_NETZPLANUNG
                  requiredResolverRoles:
                  - ROLE_KAUFMAENNISCHE_LEITUNG
                  - ROLE_NETZPLANUNG
                  personaId: tenant-a/thorsten-human
                  originService: cya
                  originAction: refine
                  severity: warning
                  requiredScope: full-access
    get:
      summary: List HITL items
      tags:
      - HITL
      operationId: hitl_list
      parameters:
      - name: status
        in: query
        schema:
          type: string
          example: pending
      - name: kind
        in: query
        schema:
          type: string
          example: finance-hypothetical-review
      - name: originService
        in: query
        schema:
          type: string
          example: finance-agent
      - name: originAction
        in: query
        schema:
          type: string
          example: analyze
      - name: severity
        in: query
        schema:
          type: string
          example: warning
      - name: overdueOnly
        in: query
        schema:
          type: boolean
          default: false
      - name: limit
        in: query
        schema:
          type: integer
          default: 50
          maximum: 200
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
  /api/hitl/summary:
    get:
      summary: Summarize HITL queue and workload
      tags:
      - HITL
      operationId: hitl_summary
      parameters:
      - name: sinceDays
        in: query
        schema:
          type: integer
          default: 30
          maximum: 365
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
  /api/hitl/sla-heatmap:
    get:
      summary: Get HITL SLA heatmap buckets
      tags:
      - HITL
      operationId: hitl_slaHeatmap
      parameters:
      - name: sinceDays
        in: query
        schema:
          type: integer
          default: 14
          maximum: 90
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
  /api/hitl/items/:id:
    get:
      summary: Get HITL item
      tags:
      - HITL
      operationId: hitl_get
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          example: 00000000-0000-4000-8000-000000000001
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
  /api/hitl/items/:id/approve:
    post:
      summary: Approve HITL item
      tags:
      - HITL
      operationId: hitl_approve
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          example: 00000000-0000-4000-8000-000000000001
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                comment:
                  type: string
                  example: Looks good
                token:
                  type: string
                  description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
            examples:
              default:
                value:
                  comment: Looks good
  /api/hitl/items/:id/reject:
    post:
      summary: Reject HITL item
      tags:
      - HITL
      operationId: hitl_reject
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          example: 00000000-0000-4000-8000-000000000001
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                comment:
                  type: string
                  example: Missing supporting evidence
                feedbackToAgent:
                  type: string
                  example: Please provide legal reference to §21a EnWG.
                token:
                  type: string
                  description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
            examples:
              default:
                value:
                  comment: Missing supporting evidence
                  feedbackToAgent: Please provide legal reference to §21a EnWG.
  /api/hitl/items/:id/escalate:
    post:
      summary: Escalate HITL item
      tags:
      - HITL
      operationId: hitl_escalate
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          example: 00000000-0000-4000-8000-000000000001
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                comment:
                  type: string
                  example: Escalate to legal review
                token:
                  type: string
                  description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
            examples:
              default:
                value:
                  comment: Escalate to legal review
  /api/hitl/items/bulk-approve:
    post:
      summary: Approve multiple HITL items
      tags:
      - HITL
      operationId: hitl_bulkApprove
      parameters:
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - ids
              properties:
                ids:
                  type: array
                  minItems: 1
                  maxItems: 100
                  example:
                  - 00000000-0000-4000-8000-000000000001
                  items:
                    type: string
                    example: 00000000-0000-4000-8000-000000000001
                comment:
                  type: string
                  example: Bulk approval by shift lead
                token:
                  type: string
                  description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
            examples:
              default:
                value:
                  ids:
                  - 00000000-0000-4000-8000-000000000001
                  comment: Bulk approval by shift lead
  /api/hitl/items/bulk-reject:
    post:
      summary: Reject multiple HITL items
      tags:
      - HITL
      operationId: hitl_bulkReject
      parameters:
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - ids
              properties:
                ids:
                  type: array
                  minItems: 1
                  maxItems: 100
                  example:
                  - 00000000-0000-4000-8000-000000000001
                  items:
                    type: string
                    example: 00000000-0000-4000-8000-000000000001
                comment:
                  type: string
                  example: Bulk rejection after policy review
                feedbackToAgent:
                  type: string
                  example: Evidence package missing legal references.
                token:
                  type: string
                  description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
            examples:
              default:
                value:
                  ids:
                  - 00000000-0000-4000-8000-000000000001
                  comment: Bulk rejection after policy review
                  feedbackToAgent: Evidence package missing legal references.
  /api/hitl/items/bulk-escalate:
    post:
      summary: Escalate multiple HITL items
      tags:
      - HITL
      operationId: hitl_bulkEscalate
      parameters:
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - ids
              properties:
                ids:
                  type: array
                  minItems: 1
                  maxItems: 100
                  example:
                  - 00000000-0000-4000-8000-000000000001
                  items:
                    type: string
                    example: 00000000-0000-4000-8000-000000000001
                comment:
                  type: string
                  example: Escalate batch to legal queue
                token:
                  type: string
                  description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
            examples:
              default:
                value:
                  ids:
                  - 00000000-0000-4000-8000-000000000001
                  comment: Escalate batch to legal queue
  /api/hitl/items/:id/workflow-state:
    get:
      summary: Get workflow completion state for HITL item
      tags:
      - HITL
      operationId: hitl_getWorkflowState
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          example: 00000000-0000-4000-8000-000000000001
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
  /api/hitl/items/:id/completion-plausibility:
    post:
      summary: Preview pre-completion plausibility hints for a HITL item (read-only, advisory)
      tags:
      - HITL
      operationId: hitl_completionPlausibility
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          example: 00000000-0000-4000-8000-000000000001
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                rules:
                  type: array
                  items:
                    type: object
                  example:
                  - ruleId: summary_required
                    type: required
                    fieldKey: summary
                fields:
                  type: object
                  example:
                    summary: ok
                token:
                  type: string
                  description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
  /api/hitl/items/:id/mark-completed:
    post:
      summary: Mark HITL workflow as completed
      tags:
      - HITL
      operationId: hitl_markWorkflowCompleted
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          example: 00000000-0000-4000-8000-000000000001
      - $ref: '#/components/parameters/TokenQuery'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                completionNotes:
                  type: string
                  example: Workflow completed with approval
                handoffPersonaId:
                  type: string
                  example: tenant-a/persona-b
                plausibilityRules:
                  type: array
                  items:
                    type: object
                  example:
                  - ruleId: summary_required
                    type: required
                    fieldKey: summary
                completionFields:
                  type: object
                  example:
                    summary: ok
                token:
                  type: string
                  description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
            examples:
              default:
                value:
                  completionNotes: Workflow completed with approval
                  handoffPersonaId: null
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.'