Cernion Agent Receipts API
Runtime-managed receipt documents (v0.54.0 foundation). PouchDB-backed CRUD, validation, lifecycle status transitions, and auditable soft-delete.
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.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/cernion-de:cernion-de-agent-receipts-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.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Cernion Energy Tools Agent Receipts 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: Agent Receipts
description: Runtime-managed receipt documents (v0.54.0 foundation). PouchDB-backed CRUD, validation, lifecycle status transitions, and auditable soft-delete.
paths:
/api/agent-receipts:
post:
summary: Create an agent receipt
tags:
- Agent Receipts
operationId: agent_receipts_create
parameters:
- $ref: '#/components/parameters/TokenQuery'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
description: Creates a runtime-managed receipt with validated schema and auditable lifecycle metadata.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- receiptId
- title
- description
- domain
- matching
- toolPlan
properties:
receiptId:
type: string
example: bess-screening-v1
title:
type: string
example: BESS Screening Baseline
description:
type: string
domain:
type: string
example: grid-operations
tags:
type: array
items:
type: string
matching:
type: object
requiredInputs:
type: array
items:
type: string
toolPlan:
type: object
knowledgeQueries:
type: array
items:
type: object
knowledgeEvidencePolicy:
type: object
knowledgePlan:
type: object
evidencePolicy:
type: object
forbiddenInferences:
type: array
items:
type: string
responsePolicy:
type: object
defaults:
type: object
metadata:
type: object
status:
type: string
enum:
- draft
- active
- deprecated
- archived
token:
type: string
description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
get:
summary: List agent receipts
tags:
- Agent Receipts
operationId: agent_receipts_list
parameters:
- name: status
in: query
required: false
schema:
type: string
enum:
- draft
- active
- deprecated
- archived
- name: domain
in: query
required: false
schema:
type: string
- name: tag
in: query
required: false
schema:
type: string
- name: includeArchived
in: query
required: false
schema:
type: boolean
default: false
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 200
default: 50
- name: offset
in: query
required: false
schema:
type: integer
minimum: 0
default: 0
- $ref: '#/components/parameters/TokenQuery'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
/api/agent-receipts/select:
post:
summary: Select a runtime receipt for Personal Agent orchestration
tags:
- Agent Receipts
operationId: agent_receipts_select
parameters:
- $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:
message:
type: string
example: Wer ist der zuständige VNB in Trier?
question:
type: string
example: Wer ist der zuständige Netzbetreiber?
knownContext:
type: object
default: {}
example:
city: Wiesloch
context:
type: object
default: {}
example: {}
input:
type: object
default: {}
example: {}
city:
type: string
example: Wiesloch
bdewCode:
type: string
example: '9900992720003'
vnbName:
type: string
example: STROMDAO Netze GmbH
forceReceipt:
type: string
example: vnb-lookup-v1
preferredReceipts:
type: array
items:
type: string
example:
- vnb-lookup-v1
- grid-ops-fallback-v1
allowDraftReceipts:
type: boolean
default: false
explainReceiptSelection:
type: boolean
default: false
disableReceiptSelection:
type: boolean
default: false
token:
type: string
description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
examples:
preferredMatching:
summary: Prefer a list of receipts with diagnostics enabled
value:
message: Bitte finde den zuständigen VNB in Trier.
preferredReceipts:
- vnb-lookup-v1
- grid-ops-fallback-v1
explainReceiptSelection: true
/api/agent-receipts/:id:
get:
summary: Get an agent receipt by id
tags:
- Agent Receipts
operationId: agent_receipts_get
parameters:
- name: id
in: path
required: true
schema:
type: string
example: bess-screening-v1
- $ref: '#/components/parameters/TokenQuery'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
put:
summary: Update an agent receipt
tags:
- Agent Receipts
operationId: agent_receipts_update
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
properties:
id:
type: string
patch:
type: string
_rev:
type: string
token:
type: string
description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
required: []
delete:
summary: Archive an agent receipt (soft delete)
tags:
- Agent Receipts
operationId: agent_receipts_archive
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
properties:
id:
type: string
reason:
type: string
_rev:
type: string
token:
type: string
description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
required: []
/api/agent-receipts/:id/status:
post:
summary: Set receipt lifecycle status
tags:
- Agent Receipts
operationId: agent_receipts_setStatus
parameters:
- name: id
in: path
required: true
schema:
type: string
example: bess-screening-v1
- $ref: '#/components/parameters/TokenQuery'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
description: Transitions a receipt between lifecycle statuses. Transitioning to active requires full-access scope or ROLE_RECEIPT_PROMOTER (#289), same as promote.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- status
properties:
status:
type: string
enum:
- draft
- active
- deprecated
- archived
reason:
type: string
_rev:
type:
- string
- 'null'
token:
type: string
description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
/api/agent-receipts/propose:
post:
summary: Propose a new draft receipt (governed learning loop)
tags:
- Agent Receipts
operationId: agent_receipts_proposeDraft
parameters:
- $ref: '#/components/parameters/TokenQuery'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
description: Creates a receipt in draft status only. Chat and automated flows must use this path instead of create. The receipt is pending review and must be explicitly promoted before becoming active.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- receiptId
- title
- description
- domain
- matching
- toolPlan
properties:
receiptId:
type: string
example: vnb-lookup-v2
title:
type: string
description:
type: string
domain:
type: string
tags:
type: array
items:
type: string
matching:
type: object
requiredInputs:
type: array
items:
type: string
toolPlan:
type: object
creatorId:
type:
- string
- 'null'
description: Identity of the creator (user id, agent name, etc).
creatorSource:
type: string
enum:
- chat
- admin
- api
- seed
default: api
description: Origin of the proposal. Chat-originated proposals must use chat.
changeReason:
type: string
description: Optional human-readable reason for this proposal.
supersedes:
type: string
description: Optional receiptId of an active receipt this draft intends to supersede upon promotion.
token:
type: string
description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
/api/agent-receipts/:id/promote:
post:
summary: Promote a draft receipt to active (explicit review gate)
tags:
- Agent Receipts
operationId: agent_receipts_promote
parameters:
- name: id
in: path
required: true
schema:
type: string
example: vnb-lookup-v2
- $ref: '#/components/parameters/TokenQuery'
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
description: Transitions a draft receipt to active. Requires promotedBy identity. Validates the receipt fully before promotion. Optionally auto-deprecates a superseded active receipt. Requires _rev for CAS conflict protection. Caller must have full-access scope or ROLE_RECEIPT_PROMOTER (#289).
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- promotedBy
properties:
promotedBy:
type: string
description: Identity of the reviewer who approved promotion.
example: admin@example.com
changeReason:
type: string
supersedes:
type: string
description: Optional receiptId of an active receipt to auto-deprecate on promotion. Falls back to supersedes field stored on the draft.
_rev:
type:
- string
- 'null'
description: CAS revision token. Prevents concurrent promotion race conditions.
token:
type: string
description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
/api/agent-receipts/validate:
post:
summary: Validate receipt payload or persisted receipt
tags:
- Agent Receipts
operationId: agent_receipts_validate
parameters:
- $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:
id:
type: string
example: bess-screening-v1
receipt:
type: object
token:
type: string
description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
/api/agent-receipts/:id/validate:
post:
summary: Validate a persisted receipt with optional live registry checks
tags:
- Agent Receipts
operationId: agent_receipts_validateStored
parameters:
- name: id
in: path
required: true
schema:
type: string
example: mastr-asset-inventory-by-location
- $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:
token:
type: string
description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
/api/agent-receipts/evaluate:
post:
summary: Evaluate receipt match and execution plan without running tools
tags:
- Agent Receipts
operationId: agent_receipts_evaluate
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
properties:
id:
type: string
receipt:
type: string
context:
type: string
input:
type: string
token:
type: string
description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
required: []
/api/agent-receipts/:id/evaluate:
post:
summary: Evaluate persisted receipt by id
tags:
- Agent Receipts
operationId: agent_receipts_evaluateStored
parameters:
- name: id
in: path
required: true
schema:
type: string
example: mastr-asset-inventory-by-location
- $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:
token:
type: string
description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
/api/agent-receipts/test:
post:
summary: Test receipt planning and return runnable execution details
tags:
- Agent Receipts
operationId: agent_receipts_test
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
properties:
id:
type: string
receipt:
type: string
context:
type: string
input:
type: string
token:
type: string
description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
required: []
/api/agent-receipts/:id/test:
post:
summary: Test persisted receipt by id
tags:
- Agent Receipts
operationId: agent_receipts_testStored
parameters:
- name: id
in: path
required: true
schema:
type: string
example: mastr-asset-inventory-by-location
- $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:
token:
type: string
description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
/api/agent-receipts/explain:
post:
summary: Explain why a receipt matched or failed and what would run
tags:
- Agent Receipts
operationId: agent_receipts_explain
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
properties:
id:
type: string
receipt:
type: string
context:
type: string
input:
type: string
token:
type: string
description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
required: []
/api/agent-receipts/:id/explain:
post:
summary: Explain persisted receipt by id
tags:
- Agent Receipts
operationId: agent_receipts_explainStored
parameters:
- name: id
in: path
required: true
schema:
type: string
example: mastr-asset-inventory-by-location
- $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:
token:
type: string
description: Optional Cernion MCP token for this request. Overrides CERNION_TOKEN when provided.
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.'