Execute sequential recipe steps and stop at first failure or email verification pause. No session required. Not atomic: committed steps remain committed. One outer API request; all internal product permissions and plan ceilings remain enforced. dryRun validates and returns the step plan without product mutations. Registration pauses for a real verification link from local mock mail; resumeToken continues in the original session. PLAN_LIMIT returns 402 and upgrade next action; SAVE_CONFLICT returns 409 without automatic overwrite; RATE_LIMIT returns 429 and Retry-After without automatic retry. P13: operator-issued agent bearer supported with fixed organization scope; public registration may be closed (BETA_CLOSED).
Parameters, inputs and responses
{
"operationId": "post_agent_run",
"summary": "Execute sequential recipe steps and stop at first failure or email verification pause",
"description": "Execute sequential recipe steps and stop at first failure or email verification pause. No session required. Not atomic: committed steps remain committed. One outer API request; all internal product permissions and plan ceilings remain enforced. dryRun validates and returns the step plan without product mutations. Registration pauses for a real verification link from local mock mail; resumeToken continues in the original session. PLAN_LIMIT returns 402 and upgrade next action; SAVE_CONFLICT returns 409 without automatic overwrite; RATE_LIMIT returns 429 and Retry-After without automatic retry. P13: operator-issued agent bearer supported with fixed organization scope; public registration may be closed (BETA_CLOSED).",
"x-access": "public",
"parameters": [
{
"name": "x-zentro-request",
"in": "header",
"required": true,
"schema": {
"const": "1"
}
}
],
"security": [
{},
{
"sessionCookie": []
},
{
"mcpBearer": []
}
],
"responses": {
"200": {
"description": "Successful operation",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"recipe": {
"type": "string"
},
"status": {
"type": "string"
},
"steps": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
},
"exports": {
"type": "array",
"items": {
"type": "object",
"required": [
"documentId",
"content",
"contentType",
"byteLength"
],
"properties": {
"documentId": {
"type": "string"
},
"content": {
"type": "string"
},
"contentType": {
"const": "application/json"
},
"byteLength": {
"type": "integer",
"minimum": 0
}
}
}
},
"durationMs": {
"type": "number"
},
"resumeToken": {
"type": "string"
},
"next": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": true
}
}
},
"additionalProperties": true
}
}
}
},
"402": {
"description": "Plan ceiling reached (PLAN_LIMIT), or request rate limit (RATE_LIMIT).",
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/PlanLimit"
},
{
"$ref": "#/components/schemas/Error"
}
]
}
}
}
},
"409": {
"description": "Save conflict: inspect current document before retry.",
"headers": {},
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"429": {
"description": "Rate limit: respect Retry-After; no automatic retry.",
"headers": {
"Retry-After": {
"schema": {
"type": "integer",
"minimum": 1
}
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"additionalProperties": true
}
}
}
},
"default": {
"$ref": "#/components/responses/Error"
}
},
"x-agent-action-ids": [
"run-recipe"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$id": "urn:zentro:run-recipe:v1",
"type": "object",
"$defs": {
"Document": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "urn:vystaveni:document:v1",
"title": "Canonical document v1",
"type": "object",
"required": [
"schema",
"title",
"blocks"
],
"properties": {
"schema": {
"const": "vystaveni.document.v1"
},
"title": {
"type": "string",
"maxLength": 300
},
"blocks": {
"$ref": "#/$defs/blocks"
},
"footnotes": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"blocks"
],
"properties": {
"id": {
"$ref": "#/$defs/id"
},
"blocks": {
"$ref": "#/$defs/blocks"
}
},
"additionalProperties": false
}
},
"comments": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"text"
],
"properties": {
"id": {
"$ref": "#/$defs/id"
},
"text": {
"type": "string",
"maxLength": 200000
},
"author": {
"type": "string",
"maxLength": 200
}
},
"additionalProperties": false
}
},
"warnings": {
"type": "array",
"items": {
"type": "string",
"maxLength": 4000
},
"maxItems": 100
},
"source": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"maxLength": 40
},
"name": {
"type": "string",
"maxLength": 2000
},
"mediaType": {
"type": "string",
"maxLength": 2000
},
"sourceId": {
"type": "string",
"maxLength": 2000
},
"hash": {
"type": "string",
"maxLength": 2000
}
},
"additionalProperties": false
},
"locale": {
"type": "string",
"maxLength": 100
},
"language": {
"type": "string",
"maxLength": 100
},
"languageSource": {
"enum": [
"unknown",
"user",
"source-metadata"
]
},
"diagnostics": {
"type": "array",
"maxItems": 100,
"items": {
"type": "object",
"required": [
"key"
],
"properties": {
"key": {
"type": "string",
"pattern": "^[a-zA-Z][a-zA-Z0-9_.-]{0,150}$",
"maxLength": 151
},
"params": {
"type": "object",
"maxProperties": 20,
"additionalProperties": {
"type": [
"string",
"number",
"boolean"
],
"maxLength": 2000
},
"propertyNames": {
"type": "string",
"pattern": "^[a-zA-Z][a-zA-Z0-9_]{0,50}$"
}
},
"message": {
"type": "string",
"maxLength": 4000
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false,
"$defs": {
"id": {
"type": "string",
"pattern": "^[a-zA-Z0-9_-]{1,100}$"
},
"provenance": {
"type": "object",
"required": [
"sourceId"
],
"properties": {
"sourceId": {
"type": "string",
"minLength": 1,
"maxLength": 1000
},
"page": {
"type": "integer",
"minimum": 1
},
"sheet": {
"type": "string",
"maxLength": 200000
},
"quote": {
"type": "string",
"maxLength": 200000
}
},
"additionalProperties": false
},
"run": {
"type": "object",
"required": [
"text"
],
"properties": {
"text": {
"type": "string",
"maxLength": 200000
},
"bold": {
"type": "boolean"
},
"italic": {
"type": "boolean"
},
"footnoteId": {
"$ref": "#/$defs/id"
},
"commentIds": {
"type": "array",
"maxItems": 100,
"uniqueItems": true,
"items": {
"$ref": "#/$defs/id"
}
},
"value": {
"type": "object",
"required": [
"type",
"value"
],
"properties": {
"type": {
"enum": [
"number",
"percent",
"date",
"boolean"
]
},
"value": {
"type": [
"string",
"number",
"boolean"
]
}
},
"additionalProperties": false,
"oneOf": [
{
"properties": {
"type": {
"enum": [
"number",
"percent"
]
},
"value": {
"type": "number"
}
}
},
{
"properties": {
"type": {
"const": "boolean"
},
"value": {
"type": "boolean"
}
}
},
{
"properties": {
"type": {
"const": "date"
},
"value": {
"type": "string",
"pattern": "^\\d{4}-\\d\\d-\\d\\d(?:T[\\d:.]+Z)?$"
}
}
}
]
},
"labelKey": {
"type": "string",
"maxLength": 151,
"pattern": "^[a-zA-Z][a-zA-Z0-9_.-]{0,150}$"
},
"labelParams": {
"$ref": "#/properties/diagnostics/items/properties/params"
}
},
"additionalProperties": false
},
"blocks": {
"type": "array",
"maxItems": 20000,
"items": {
"$ref": "#/$defs/block"
}
},
"block": {
"oneOf": [
{
"type": "object",
"required": [
"type"
],
"properties": {
"id": {
"$ref": "#/$defs/id"
},
"provenance": {
"$ref": "#/$defs/provenance"
},
"type": {
"const": "page-break"
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type",
"runs"
],
"properties": {
"id": {
"$ref": "#/$defs/id"
},
"provenance": {
"$ref": "#/$defs/provenance"
},
"type": {
"const": "paragraph"
},
"runs": {
"type": "array",
"maxItems": 10000,
"items": {
"$ref": "#/$defs/run"
}
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type",
"runs",
"level"
],
"properties": {
"id": {
"$ref": "#/$defs/id"
},
"provenance": {
"$ref": "#/$defs/provenance"
},
"type": {
"const": "heading"
},
"runs": {
"type": "array",
"maxItems": 10000,
"items": {
"$ref": "#/$defs/run"
}
},
"level": {
"enum": [
1,
2,
3
]
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type",
"ordered",
"items"
],
"properties": {
"id": {
"$ref": "#/$defs/id"
},
"provenance": {
"$ref": "#/$defs/provenance"
},
"type": {
"const": "list"
},
"ordered": {
"type": "boolean"
},
"start": {
"type": "integer",
"minimum": 1,
"maximum": 100000
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"blocks"
],
"properties": {
"blocks": {
"$ref": "#/$defs/blocks"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
},
{
"type": "object",
"required": [
"type",
"rows"
],
"properties": {
"id": {
"$ref": "#/$defs/id"
},
"provenance": {
"$ref": "#/$defs/provenance"
},
"type": {
"const": "table"
},
"rows": {
"type": "array",
"maxItems": 2000,
"items": {
"type": "object",
"required": [
"cells"
],
"properties": {
"cells": {
"type": "array",
"maxItems": 100,
"items": {
"type": "object",
"required": [
"blocks"
],
"properties": {
"blocks": {
"$ref": "#/$defs/blocks"
},
"colSpan": {
"type": "integer",
"minimum": 1,
"maximum": 100
},
"rowSpan": {
"type": "integer",
"minimum": 1,
"maximum": 2000
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
]
}
}
},
"params-ask-document": {
"type": "object",
"properties": {
"documentId": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,100}$"
},
"question": {
"type": "string",
"minLength": 1,
"maxLength": 4000
}
},
"required": [
"documentId",
"question"
],
"additionalProperties": false
},
"params-new-customer": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email",
"maxLength": 254,
"pattern": "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$"
},
"password": {
"type": "string",
"minLength": 12,
"description": "At most 1024 UTF-8 bytes, as in product registration."
},
"title": {
"type": "string",
"minLength": 1,
"maxLength": 300
},
"inviteEmail": {
"type": "string",
"format": "email",
"maxLength": 254,
"pattern": "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$"
},
"comment": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"document": {
"$ref": "#/$defs/Document"
},
"versionDocument": {
"$ref": "#/$defs/Document"
},
"organization": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"uiLocale": {
"enum": [
"cs",
"en"
],
"type": "string"
}
},
"required": [
"email",
"password",
"title",
"inviteEmail",
"comment"
],
"additionalProperties": false
},
"params-share-document": {
"type": "object",
"properties": {
"documentId": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,100}$"
},
"inviteEmail": {
"type": "string",
"format": "email",
"maxLength": 254,
"pattern": "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$"
},
"role": {
"type": "string",
"enum": [
"viewer",
"commenter",
"editor"
]
},
"username": {
"type": "string",
"pattern": "^\\S{3,80}$"
},
"password": {
"type": "string",
"minLength": 12
}
},
"required": [
"documentId",
"inviteEmail"
],
"additionalProperties": false
},
"params-revise-compare-discuss": {
"type": "object",
"properties": {
"documentId": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,100}$"
},
"document": {
"$ref": "#/$defs/Document"
},
"comment": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"baseVersion": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,100}$"
}
},
"required": [
"documentId",
"document",
"comment"
],
"additionalProperties": false
},
"params-accept-and-comment": {
"type": "object",
"properties": {
"token": {
"type": "string",
"minLength": 1
},
"comment": {
"type": "string",
"minLength": 1,
"maxLength": 200
},
"documentId": {
"type": "string",
"pattern": "^[A-Za-z0-9_-]{1,100}$"
}
},
"required": [
"token",
"comment"
],
"additionalProperties": false
}
},
"properties": {
"recipe": {
"type": "string",
"enum": [
"ask-document",
"new-customer",
"share-document",
"revise-compare-discuss",
"accept-and-comment"
]
},
"params": {
"type": "object",
"anyOf": [
{
"$ref": "#/$defs/params-ask-document"
},
{
"$ref": "#/$defs/params-new-customer"
},
{
"$ref": "#/$defs/params-share-document"
},
{
"$ref": "#/$defs/params-revise-compare-discuss"
},
{
"$ref": "#/$defs/params-accept-and-comment"
}
]
},
"dryRun": {
"type": "boolean"
},
"resumeToken": {
"type": "string"
}
},
"additionalProperties": false,
"oneOf": [
{
"required": [
"recipe",
"params"
],
"properties": {
"recipe": {
"const": "ask-document"
},
"params": {
"$ref": "#/$defs/params-ask-document"
}
},
"not": {
"required": [
"resumeToken"
]
}
},
{
"required": [
"recipe",
"params"
],
"properties": {
"recipe": {
"const": "new-customer"
},
"params": {
"$ref": "#/$defs/params-new-customer"
}
},
"not": {
"required": [
"resumeToken"
]
}
},
{
"required": [
"recipe",
"params"
],
"properties": {
"recipe": {
"const": "share-document"
},
"params": {
"$ref": "#/$defs/params-share-document"
}
},
"not": {
"required": [
"resumeToken"
]
}
},
{
"required": [
"recipe",
"params"
],
"properties": {
"recipe": {
"const": "revise-compare-discuss"
},
"params": {
"$ref": "#/$defs/params-revise-compare-discuss"
}
},
"not": {
"required": [
"resumeToken"
]
}
},
{
"required": [
"recipe",
"params"
],
"properties": {
"recipe": {
"const": "accept-and-comment"
},
"params": {
"$ref": "#/$defs/params-accept-and-comment"
}
},
"not": {
"required": [
"resumeToken"
]
}
},
{
"required": [
"resumeToken"
],
"not": {
"required": [
"params"
]
}
}
]
}
}
}
}
}